Table of Contents
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 and realizes most parts of the changes defined in RFC 4918. 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.
There are some terms used in a WebDAV environment whose meanings differ slightly from the usage in similar environments.
To set up a basic WebDAV server, you must consider two steps:
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.
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.
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.
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.
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.
Since version 1.1 the Webdav component has support for locking (WebDAV compliance class 2). It is realized through a plugin, which means that you can integrate it into your own WebDAV environment easily, without changing your setup a lot.
To make the lock plugin work in your environment, you need to fulfill the following pre-conditions:
The ezcWebdavLockBackend interface requires your back-end to implement 2 new methods, that allow the lock plugin to gain an exclusive lock on the back-end. This is necessary to ensure that the lock plugins operations are atomic. Note that you don't need to support the LOCK and UNLOCK requests in your back-end. Both are completely handled by the lock plugin, which communicates with the back-end only by standard requests. For more information see Writing a custom back-end. The file back-end shipped with the Webdav component supports all requirements.
The ezcWebdavLockAuthorizer interface defines methods to let your authorization mechanism know about the assignment between users and locks. You need to store string lock tokens per user.
The following example shows a typical setup for a Webdav server with locking:
An instance of your custom authentication/authorization class is assigned to the server. You will need to adjust the location of the token assignment file, if you want to get this example running. It must be writable by the user running your web server and should be located outside of your web root.
For the back-end initialization you will need to adjust the path, too. The same rules as for the token.php file apply here:
To test your setup properly, you should first access the URL using a web browser. You should now see any exceptions, errors and warnings that might be generated. If you see a white page, everything seems correct. Now try with a WebDAV client.
Whenever a clients successfully acquires a lock, a timeout value is assigned to it. If the client does not access the lock for that number of seconds, it might be considered orphan and can safely be removed. To achieve this removal of locks, the Webdav component provides an API for you, that you might use in a CRON job or a similar mechanism, to purge all outdated locks.
The setup for the lock administration should be identical to your web setup. Except, you might leave out the authentication instance, since it will be deactivated by the administrator object anyway. However, it does not hurt to have it in place.
The ezcWebdavLockAdministrator object is instantiated given the back-end it should work on. The call to ezcWebdavLockAdministrator->purgeLocks() optionally accepts a string parameter to indicate which paths should be searched for orphan locks. Omitting this parameter, as shown in the example, searches the complete back-end.
Note that the process of purging locks will lock your back-end completely, as the lock plugin does it during any request that needs to perform multiple requests.
The most common way of extending WebDAV 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 extending ezcWebdavBackend directly, or you can reuse the existing helper class ezcWebdavSimpleBackend.
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.
If you do not extend ezcWebdavSimpleBackend, be sure to implement authorization and to pay attention to the If-Match and If-None-Match headers. Both are already handled by ezcWebdavSimpleBackend, so you don't need to take care about that if you extend this class.
If you want to use your custom back-end with the lock plugin, it needs to implement some more interfaces. First of all, you need to implement all of the basic back-end interfaces:
All of these are already implemented by ezcWebdavSimpleBackend. It is recommended that you use this one as the basis for your custom lock back-end, since it already handles authorization for you and processes the HTTP headers If-Match and If-None-Match. You will need to handle both on your own, if you do not extend ezcWebdavSimpleBackend.
No matter which way you choose, you need to implement ezcWebdavLockBackend. This interface requires you to implement 2 methods:
The ezcWebdavFileBackend, which is shipped with the Webdav component, supports all of the features mentioned above.