Path

ez components / documentation / api reference / latest / webdav

Webdav

[ Tutorial ] [ Plugin architecture ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Table of Contents

Introduction

The Webdav component enables you to easily set up a WebDAV-enabled HTTP server. Users can then create and edit site content by uploading and downloading files to and from their desktop. The current implementation is compatible with RFC 2518. It also supports clients that do not conform to the standard and provides an interface to support these clients.

The component is intended to support you by providing access to your data through the HTTP 1.1 protocol. The data can be stored in the file system, or any other custom data storage. It is then served as a virtual directory tree to the user.

Terms

There are some terms used in a WebDAV environment whose meanings differ slightly from the usage in similar environments.

Collection
When it comes to WebDAV, a collection means a set of files and other collections, which may be compared with directories in a normal file system.
Resource
A resource equals a file, but we use a different term here to differentiate between real files on the hard disk and the virtual resources (files) in a WebDAV share.
Properties
There are several default properties, like the modification time or file size of WebDAV resources, but you can also store and modify custom properties on all resources.

Setting up a WebDAV server

To set up a basic WebDAV server, you must consider two steps:

  1. You need to configure the WebDAV server to work correctly with the incoming requests from WebDAV clients. This means that you need to set up some rewriting for the request paths (which the client sends) to the paths that are used in the back-end.
  2. You need to set up the back-end, so that it points to the resources you want to share through WebDAV.

Path auto detection

Using the default path factory, which tries to auto detect your setup and map the paths accordingly, you need very little code to setup a WebDAV server.

  1. <?php
  3. require_once 'tutorial_autoload.php';
  5. $server = ezcWebdavServer::getInstance();
  6. $backend = new ezcWebdavFileBackend(
  7. dirname( __FILE__ ) . '/backend'
  8. );
  10. $server->handle( $backend );
  12. ?>

As you can see in the example, we first create a new WebDAV server instance. Then a file back-end is created, which just receives the directory as a parameter, where your contents are stored.

Finally we call the method handle() on ezcWebdavServer, which actually parses and responds to the request with the created back-end as a parameter.

Basic path factory

A custom path factory enables you to specify the request path mapping to the path of a resource in the repository. This can be used if the automatic detection does not work.

  1. <?php
  3. require_once 'tutorial_autoload.php';
  5. $server = ezcWebdavServer::getInstance();
  7. $pathFactory = new ezcWebdavBasicPathFactory(
  8. 'http://example.com/webdav/index.php'
  9. );
  11. foreach ( $server->configurations as $conf )
  12. {
  13. $conf->pathFactory = $pathFactory;
  14. }
  16. $backend = new ezcWebdavFileBackend(
  17. dirname( __FILE__ ) . '/backend'
  18. );
  20. $server->handle( $backend );
  22. ?>

When assigning the server configuration to the new ezcWebdavBasicPathFactory object, you provide the base URL, which will always be removed from the request URLs.

If you need more specialized mapping of request paths to repository paths, you can write your own path factory, by implementing the ezcWebdavPathFactory interface, or extending one of the existing path factories.

Testing the server

You can test the server directly with a WebDAV client of your choice. However, most WebDAV clients have very poor debugging capabilities.

The WebDAV client with the most verbose error reporting currently is the command line WebDAV client cadaver, where you might get more information than failed request notifications.

The second step you should take is to enable error logging, either by catching all exceptions from WebDAV and logging them to a file, or by simply enabling log_errors in php.ini.

You can also access the WebDAV server with a browser, since WebDAV is just an extension to the HTTP protocol. You should be able to get valid results out of this, and also see possible errors. Remember that collections (or directories), although they can contain other collections and resources, do not consist of any data themselves. Therefore, if everything is working properly, you will get a blank page when viewing collections in your browser. However, you should still be able to download resources (or files) in the WebDAV share.

Writing a custom back-end

The most common way of extending a WebDAV server is to provide a custom back-end to your data. A back-end receives ezcWebdavRequest objects and generates ezcWebdavResponse objects, which are displayed in a way that the current client will understand.

There are basically two ways for you to implement a custom back-end. You can implement all the request object handling yourself, by directly extending ezcWebdavBackend, or you can reuse the existing helper class ezcWebdavSimpleBackend.

The simple back-end

The simple back-end, defined in the ezcWebdavSimpleBackend class, already implements all request-to-response mapping, so you only need to implement several methods that directly access the data in your back-end (like the file back-end does).

If you need more fine-grained control, or optimizations, you will still need to extend the basic ezcWebdavBackend class directly. If you want to implement a custom back-end you could use the file back-end or the memory back-end (which as mainly intended for testing) as an implementation guide.

Last updated: Mon, 04 Aug 2008