This functionality is currently under development. It will hopefully appear in eZ publish 3.2. Most of it will be available from within trunk [as soon as it reaches an alpha/usable state].

eZ WebDAV is a WebDAV server abstraction library. It enables you to quickly develop WebDAV enabled PHP servers/applications.

A few words about WebDAV

WebDAV is an abbreviation for "Web-based Distributed Authoring and Versioning". It is a set of extensions to the HTTP protocol which allows users to collaboratively edit and manage files on remote web servers using WebDAV enabled clients. For example, you can use recent versions of KDE's Konqueror or Microsoft's Internet Explorer to browse/manage a WebDAV server (similar to browsing/managing local filesystems). DAV is an IETF Proposed Standard (published as RFC 2518). This means that it is an entirely open, published standard.

WebDAV definitions

Since the WebDAV protocol is XML based and can be used to manage any type of digitally stored information it uses a different kind of notation that you might be used to. Details about WebDAV and the specification is far beyond the scope of this document (check out the official webdav site). For now you'll only need to get used to the following nomenclature: WebDAV defines a file (collection of relevant data/information) as a RESOURCE and a directory (collection of files) as a COLLECTION. We'll be using these terms throughout this document and within the source code.

The eZWebDAVServer class

The eZWebDAVServer class provides a basic framework. It is an abstract base class that developers can use to build various kinds of WebDAV enabled servers/applications. The class needs to be inherited and extended, it will absolutely not work without some extra/additional code (your code :-).

The functionality provided within this class takes care of the low-level communication between a WebDAV compatible client (for example a browser) and a server. Additional/custom code takes care of actual file/data management and interpretation (based on the various actions; GET, PUT, DELETE,etc.). In other words: by extending this class, you could build a WebDAV server that makes it possible to manage any kind of information (files, folders, documents, images, etc.) that you would like to administer using a WebDAV client.

WebDAV methods

Currently, the following WebDAV methods are supported by the base class:

Actual implementation

The actual implementation of the base class is really simple, it consists of four main parts, which are briefly described in the following text.

The process function
This function simply checks what the client wants, and initiates a corresponding sequence of actions. For example if the client requests the contents and properties of the resources within a collection (in other words: directory listing), the process function will call a virtual function (here, your code will acquire/collect and return the necessary data about the resources). Finally, an output function will be called (which takes care of WebDAV-style-formatting of your data).

The Output functions
These functions take care of formatting and outputting various data (collection content, resource content, etc.) in WebDAV-style so that WebDAV clients can read, understand and present it to a user. You don't need to worry about formatting, the only thing you need to do is to provide necessary data (using the virtual functions) and an output function will take care of any low-level communication and the formatting.

The Virtual functions
These functions are empty and should be overridden and filled with custom code in your class (which extends the eZWebDAVServer class). It is here where you must put in code to do various stuff like getting the required attributes for files, etc. These functions must return a set of predefined values (look in the beginning of eZWebDAVServer.php).

The handler function
This function takes care of handling the return values of the output and the virtual functions. Based on the return value, it simply sends the necessary HTTP header(s) etc. For example when a resource is successfully deleted, the handler will send a HTTP OK header to the client (or a HTTP FORBIDDEN header if the client doesn't have permissions to delete the resource).

How does all this work?

Simple:

(1) The client sends a request (perhaps with some parameters along with the request).
(2) The server checks what the client wants and attempts to do the requested action.
(3) The server returns something (data or just control information) to the client.
(4) GOTO (1)

How to get it working?

First of all, you need to define a class that inherits from the eZWebDAVServer:

include_once( "lib/ezwebdav/classes/ezwebdavserver.php" );

 

class eZWebDAVCustomServer extends eZWebDAVServer

{

   [...]

}

Secondly, you need to override the empty/virtual functions of eZWebDAVServer:

 

function options( <i>$target</i> ) {...}

function getCollectionContent( <i>$target</i> ) {...}

function head( <i>$target ) {...}

function get( <i>$target</i> ) {...}

function put( <i>$target</i> ) {...}

function mkcol( <i>$target</i> ) {...}

function copy( <i>$source, $destination</i> ) {...}

function move( <i>$source, $destination</i> ) {...}

function delete( <i>$target</i> ) {...}

function options( $target ) {...}
Only needs to be overridden if you want a custom OPTIONS reply. By default, the server will reply with a collection of safe WebDAV ID-headers. The $target parameter specifies the path-to and the name-of the resource/collection that was targeted by the OPTIONS command.

function getCollectionContent( $target ) {...}
This function must generate and return an array of resources/collections (files/dirs) that reside at a location specified by the $target parameter. For each and every collection/directory-entry, the following properties must be returned:

Name
Size (in bytes)
Mime type
Creation date/time (UNIX timestamp)
Modification date/time (UNIX timestamp)

function head( $target ) {...}
This function should check if the a resource/collection (file/dir), specified by the $target parameter, exists or not. Must return either EZ_WEBDAV_OK_CREATED or EZ_WEBDAV_NOT_FOUND.

function get( $target ) {...}
The get function should take care of sending data from the server to the client. However, in the virtual function you only need to specify the type, location and/or contents of the data. Actual data transmission and low-level communication is taken care of by the base class. The $target parameter reveals what the client requested. The data you wish to send can either be a file (located somewhere on the filesystem) or a custom data-string. The get function should just return an associative array; the following examples should demonstrate this clearly:

Sending custom data:

[...]

$result = array();

$result["data"] = "custom data string, whatever, bla bla bla";

$result["file"] = FALSE;

 

return( $result );

[...]

 

Sending a file:

[...]

$result = array();

$result["data"] = FALSE;

$result["file"] = "/bring/on/the/babes/forfun.txt";

 

return( $result );

[...]

Obviously, one of the elements must be FALSE while the other is NON-FALSE.

function put( $target, $tempFile ) {...}
The put function is automatically called by the base class after some data has been uploaded from a client to the server. Again, the base class takes care of the low level stuff and puts the contents of the uploaded data into a temporary file passed to this function as $tempFile. The $target parameter reveals the location and name of the file/data that the client just uploaded. When dealing with files, you would simply do a move (called "rename" in PHP) operation in order to move the file from temporary to permanent location. Return values: EZ_WEBDAV_OK_CREATED on success and EZ_WEBDAV_FAILED_FORBIDDEN on failure.

function mkcol( $target ) {...}
This function is called when the client issues an MKCOL command, which means "make collection" (or make directory if you prefer working with files/dirs). The $target parameter reveals the location and name of the collection that should be created. Your function must check if the location is valid. If there already exists a resource/collection (file/dir) with the specified name, the must return EZ_WEBDAV_FAILED_EXSITS. If the creation was successful, EZ_WEBDAV_OK_CREATED should be returned. If creation failed (for some other reason, permissions, etc.), the return value must be EZ_WEBDAV_FAILED_FORBIDDEN.

function copy( $source, $destination ) {...}
This function should take care of copying a resource (or a collection, recursively) from the $source to the $destination location on the server. Return values: EZ_WEBDAV_OK_CREATED on success and EZ_WEBDAV_FAILED_FORBIDDEN if the operation failed.

function move( $source, $destination ) {...}
Almost identical to the copy function. The move function should take care of moving a resource (or a collection, recursively) from the $source to the $destination location on the server. Return values: EZ_WEBDAV_OK_CREATED on success and EZ_WEBDAV_FAILED_FORBIDDEN if the operation failed.

function delete( $target ) {...}
The delete function must remove a resource or a collection (file or dir) specified by the $target parameter. It must either return EZ_WEBDAV_OK (on success) or EZ_WEBDAV_FAILED_FORBIDDEN (if the operation failed).

Third, you need to create an object of your eZWebDAVServer extended class and let the process function run when the script is called:

$myServer = new eZWebDAVCustomServer();

$myServer->processClientRequest();

Please keep in mind that the functionality and documentation presented here is currently under development.