eZ Component: Webdav, Plugin-Architecture
Contents
Scope
The scope of this document is to give authors of plugins for the Webdav component an introduction on how to implement new plugins. If you just want to use the Webdav component, this document does not contain any relevant information for you.
The Plugin-API is not part of the Webdav component in version 1.0, but will be part of a later release.
Overview
The Webdav component provides a flexible plugin architecture to extend the features of the component. A plugin is a certain set of classes, that represents a certain functionality for the component. Every plugin must ship a class that extends ezcWebdavPluginConfiguration and is used to add the plugin to the component.
To interact with the component, a plugin can assign an unlimited number of callbacks to so called "hooks" which are offered by certain parts of the component. A hook indicates that a certain event has occured inside the component and informs plugins about this event. A plugin callback will receive a defined number of parameters, wrapped into an instance of ezcWebavPluginParameters, it may work on and even possibly alter.
A callback assigned to a hook should usually not return anything, because procesing of further callbacks will be stopped immediatelly in this case. Therefore, a plugin callback usually returns null and interacts with the component through the received parameters. Some special hooks expect a plugin callback to return a certain object to stop processing of further callbacks by intention and to inject a certain object into the component. If this is the case, it is explicitly mentioned in the hook description.
Plugin configuration
Every plugin must provide a class that extends ezcWebdavPluginConfiguration and is used to activate the plugin in the server. This class is instantiated by the user and submitted to ezcWebdavPluginRegistry->registerPlugin(). After that, the plugin is registered and active.
The configuration class expects 2 abstract methods to be implemented, which are used by the server to determine all necessary information about the plugin:
- getNamespace()
- This method must return a string, representing a unique identifier for the plugin, called the namespace of the plugin. This sting should usually reflect the plugins name for clearity. A good namespace identifier would e.g. be "ezcWebdavLockPlugin".
- getHooks()
- The server calls this method on the configuration object to receive an array containing all hooks the plugin wants to assign to, including the callbacks for each hook. The detailed structure of this definition can be found in the Webdav API docs.
Additionally, the server will call the init() method on the configuration object, which by default does nothing. A plugin can overwrite this method, to perform any kind of setup work.
Hooks
Plugin hooks are catgorized by the class that issues them. 3 classes of the Webdav component currently support the following plugin hooks:
ezcWebdavTransport
The ezcWebdavTransport class offers hooks that are related to request parsing and response handling. To give you the most comfortable way of interacting with these processes, for each of the request parsing and response handling methods offer a "before" and an "after" hook. The "before" hook is announced right before the speicifc method is invoked, while "after" announcement happens right after the method has been called.
Additionally a hook for parsing unknown requests and one for handling unknown response objects is announced if such cases occur.
beforeParseCopyRequest
This hook is announced right before a COPY request is parsed. It retrieves the parameters
- path
- The path contained in the request URI, already transformed by an ezcWebdavPathFactory, as a string.
- body
- The body contained in the request as a string.
Both parameters are submitted by reference, so any changes made to them will have effects on other mechanisms accessing those. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterParseCopyRequest
Analogous to the "before" hook of this method, this hook is announced right after a COPY request has been parsed. The parameter received by the callbacks assigned to this hook receives the following parameters:
- request
- The request object parsed from the request data (ezcWebdavRequest).
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeParseDeleteRequest
This hook is announced right before a DELETE request is parsed. It retrieves the parameters
- path
- The path contained in the request URI, already transformed by an ezcWebdavPathFactory, as a string.
- body
- The body contained in the request as a string.
Both parameters are submitted by reference, so any changes made to them will have effects on other mechanisms accessing those. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterParseDeleteRequest
Analogous to the "before" hook of this method, this hook is announced right after a DELETE request has been parsed. The parameter received by the callbacks assigned to this hook receives the following parameters:
- request
- The request object parsed from the request data (ezcWebdavRequest).
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeParseGetRequest
This hook is announced right before a GET request is parsed. It retrieves the parameters
- path
- The path contained in the request URI, already transformed by an ezcWebdavPathFactory, as a string.
- body
- The body contained in the request as a string.
Both parameters are submitted by reference, so any changes made to them will have effects on other mechanisms accessing those. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterParseGetRequest
Analogous to the "before" hook of this method, this hook is announced right after a GET request has been parsed. The parameter received by the callbacks assigned to this hook receives the following parameters:
- request
- The request object parsed from the request data (ezcWebdavRequest).
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeParseHeadRequest
This hook is announced right before a HEAD request is parsed. It retrieves the parameters
- path
- The path contained in the request URI, already transformed by an ezcWebdavPathFactory, as a string.
- body
- The body contained in the request as a string.
Both parameters are submitted by reference, so any changes made to them will have effects on other mechanisms accessing those. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterParseHeadRequest
Analogous to the "before" hook of this method, this hook is announced right after a HEAD request has been parsed. The parameter received by the callbacks assigned to this hook receives the following parameters:
- request
- The request object parsed from the request data (ezcWebdavRequest).
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeParseMakeCollectionRequest
This hook is announced right before a MKCOL request is parsed. It retrieves the parameters
- path
- The path contained in the request URI, already transformed by an ezcWebdavPathFactory, as a string.
- body
- The body contained in the request as a string.
Both parameters are submitted by reference, so any changes made to them will have effects on other mechanisms accessing those. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterParseMakeCollectionRequest
Analogous to the "before" hook of this method, this hook is announced right after a MKCOL request has been parsed. The parameter received by the callbacks assigned to this hook receives the following parameters:
- request
- The request object parsed from the request data (ezcWebdavRequest).
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeParseMoveRequest
This hook is announced right before a MOVE request is parsed. It retrieves the parameters
- path
- The path contained in the request URI, already transformed by an ezcWebdavPathFactory, as a string.
- body
- The body contained in the request as a string.
Both parameters are submitted by reference, so any changes made to them will have effects on other mechanisms accessing those. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterParseMoveRequest
Analogous to the "before" hook of this method, this hook is announced right after a MOVE request has been parsed. The parameter received by the callbacks assigned to this hook receives the following parameters:
- request
- The request object parsed from the request data (ezcWebdavRequest).
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeParseOptionsRequest
This hook is announced right before a OPTIONS request is parsed. It retrieves the parameters
- path
- The path contained in the request URI, already transformed by an ezcWebdavPathFactory, as a string.
- body
- The body contained in the request as a string.
Both parameters are submitted by reference, so any changes made to them will have effects on other mechanisms accessing those. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterParseOptionsRequest
Analogous to the "before" hook of this method, this hook is announced right after a OPTIONS request has been parsed. The parameter received by the callbacks assigned to this hook receives the following parameters:
- request
- The request object parsed from the request data (ezcWebdavRequest).
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeParsePropFindRequest
This hook is announced right before a PROPFIND request is parsed. It retrieves the parameters
- path
- The path contained in the request URI, already transformed by an ezcWebdavPathFactory, as a string.
- body
- The body contained in the request as a string.
Both parameters are submitted by reference, so any changes made to them will have effects on other mechanisms accessing those. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterParsePropFindRequest
Analogous to the "before" hook of this method, this hook is announced right after a PROPFIND request has been parsed. The parameter received by the callbacks assigned to this hook receives the following parameters:
- request
- The request object parsed from the request data (ezcWebdavRequest).
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeParsePropPatchRequest
This hook is announced right before a PROPPATCH request is parsed. It retrieves the parameters
- path
- The path contained in the request URI, already transformed by an ezcWebdavPathFactory, as a string.
- body
- The body contained in the request as a string.
Both parameters are submitted by reference, so any changes made to them will have effects on other mechanisms accessing those. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterParsePropPatchRequest
Analogous to the "before" hook of this method, this hook is announced right after a PROPPATCH request has been parsed. The parameter received by the callbacks assigned to this hook receives the following parameters:
- request
- The request object parsed from the request data (ezcWebdavRequest).
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeParsePutRequest
This hook is announced right before a PUT request is parsed. It retrieves the parameters
- path
- The path contained in the request URI, already transformed by an ezcWebdavPathFactory, as a string.
- body
- The body contained in the request as a string.
Both parameters are submitted by reference, so any changes made to them will have effects on other mechanisms accessing those. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterParsePutRequest
Analogous to the "before" hook of this method, this hook is announced right after a PUT request has been parsed. The parameter received by the callbacks assigned to this hook receives the following parameters:
- request
- The request object parsed from the request data (ezcWebdavRequest).
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore, all manipulations must be performed very carefully.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeProcessCopyResponse
This hook is announce directly before a ezcWebdavCopy response object is serialized and send back to the client. The parameter submitted to the hook is the response object that is going to be serialized.
- response
- The response object that is going to be serialized.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterProcessCopyResponse
This hook is announce directly after a ezcWebdavCopy response object has been serialized to be send back to the client. The parameter submitted to the hook is the instance of ezcWebdavDisplayInformation that was created by the processing method.
- result
- The ezcWebdavDisplayInformation instance representing the data to send to the client.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeProcessDeleteResponse
This hook is announce directly before a ezcWebdavDelete response object is serialized and send back to the client. The parameter submitted to the hook is the response object that is going to be serialized.
- response
- The response object that is going to be serialized.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterProcessDeleteResponse
This hook is announce directly after a ezcWebdavDelete response object has been serialized to be send back to the client. The parameter submitted to the hook is the instance of ezcWebdavDisplayInformation that was created by the processing method.
- result
- The ezcWebdavDisplayInformation instance representing the data to send to the client.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeProcessErrorResponse
This hook is announce directly before a ezcWebdavError response object is serialized and send back to the client. The parameter submitted to the hook is the response object that is going to be serialized.
- response
- The response object that is going to be serialized.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterProcessErrorResponse
This hook is announce directly after a ezcWebdavError response object has been serialized to be send back to the client. The parameter submitted to the hook is the instance of ezcWebdavDisplayInformation that was created by the processing method.
- result
- The ezcWebdavDisplayInformation instance representing the data to send to the client.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeProcessGetCollectionResponse
This hook is announce directly before a ezcWebdavGetCollection response object is serialized and send back to the client. The parameter submitted to the hook is the response object that is going to be serialized.
- response
- The response object that is going to be serialized.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterProcessGetCollectionResponse
This hook is announce directly after a ezcWebdavGetCollection response object has been serialized to be send back to the client. The parameter submitted to the hook is the instance of ezcWebdavDisplayInformation that was created by the processing method.
- result
- The ezcWebdavDisplayInformation instance representing the data to send to the client.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeProcessGetResourceResponse
This hook is announce directly before a ezcWebdavGetResource response object is serialized and send back to the client. The parameter submitted to the hook is the response object that is going to be serialized.
- response
- The response object that is going to be serialized.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterProcessGetResourceResponse
This hook is announce directly after a ezcWebdavGetResource response object has been serialized to be send back to the client. The parameter submitted to the hook is the instance of ezcWebdavDisplayInformation that was created by the processing method.
- result
- The ezcWebdavDisplayInformation instance representing the data to send to the client.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeProcessHeadResponse
This hook is announce directly before a ezcWebdavHead response object is serialized and send back to the client. The parameter submitted to the hook is the response object that is going to be serialized.
- response
- The response object that is going to be serialized.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterProcessHeadResponse
This hook is announce directly after a ezcWebdavHead response object has been serialized to be send back to the client. The parameter submitted to the hook is the instance of ezcWebdavDisplayInformation that was created by the processing method.
- result
- The ezcWebdavDisplayInformation instance representing the data to send to the client.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeProcessMakeCollectionResponse
This hook is announce directly before a ezcWebdavMakeCollection response object is serialized and send back to the client. The parameter submitted to the hook is the response object that is going to be serialized.
- response
- The response object that is going to be serialized.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterProcessMakeCollectionResponse
This hook is announce directly after a ezcWebdavMakeCollection response object has been serialized to be send back to the client. The parameter submitted to the hook is the instance of ezcWebdavDisplayInformation that was created by the processing method.
- result
- The ezcWebdavDisplayInformation instance representing the data to send to the client.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeProcessMoveResponse
This hook is announce directly before a ezcWebdavMove response object is serialized and send back to the client. The parameter submitted to the hook is the response object that is going to be serialized.
- response
- The response object that is going to be serialized.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterProcessMoveResponse
This hook is announce directly after a ezcWebdavMove response object has been serialized to be send back to the client. The parameter submitted to the hook is the instance of ezcWebdavDisplayInformation that was created by the processing method.
- result
- The ezcWebdavDisplayInformation instance representing the data to send to the client.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeProcessMultiStatusResponse
This hook is announce directly before a ezcWebdavMultistatus response object is serialized and send back to the client. The parameter submitted to the hook is the response object that is going to be serialized.
- response
- The response object that is going to be serialized.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterProcessMultiStatusResponse
This hook is announce directly after a ezcWebdavMultistatus response object has been serialized to be send back to the client. The parameter submitted to the hook is the instance of ezcWebdavDisplayInformation that was created by the processing method.
- result
- The ezcWebdavDisplayInformation instance representing the data to send to the client.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeProcessOptionsResponse
This hook is announce directly before a ezcWebdavOptions response object is serialized and send back to the client. The parameter submitted to the hook is the response object that is going to be serialized.
- response
- The response object that is going to be serialized.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterProcessOptionsResponse
This hook is announce directly after a ezcWebdavOptions response object has been serialized to be send back to the client. The parameter submitted to the hook is the instance of ezcWebdavDisplayInformation that was created by the processing method.
- result
- The ezcWebdavDisplayInformation instance representing the data to send to the client.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeProcessPropFindResponse
This hook is announce directly before a ezcWebdavPropFind response object is serialized and send back to the client. The parameter submitted to the hook is the response object that is going to be serialized.
- response
- The response object that is going to be serialized.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterProcessPropFindResponse
This hook is announce directly after a ezcWebdavPropFind response object has been serialized to be send back to the client. The parameter submitted to the hook is the instance of ezcWebdavDisplayInformation that was created by the processing method.
- result
- The ezcWebdavDisplayInformation instance representing the data to send to the client.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeProcessPropPatchResponse
This hook is announce directly before a ezcWebdavPropPatch response object is serialized and send back to the client. The parameter submitted to the hook is the response object that is going to be serialized.
- response
- The response object that is going to be serialized.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterProcessPropPatchResponse
This hook is announce directly after a ezcWebdavPropPatch response object has been serialized to be send back to the client. The parameter submitted to the hook is the instance of ezcWebdavDisplayInformation that was created by the processing method.
- result
- The ezcWebdavDisplayInformation instance representing the data to send to the client.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeProcessPutResponse
This hook is announce directly before a ezcWebdavPut response object is serialized and send back to the client. The parameter submitted to the hook is the response object that is going to be serialized.
- response
- The response object that is going to be serialized.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterProcessPutResponse
This hook is announce directly after a ezcWebdavPut response object has been serialized to be send back to the client. The parameter submitted to the hook is the instance of ezcWebdavDisplayInformation that was created by the processing method.
- result
- The ezcWebdavDisplayInformation instance representing the data to send to the client.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
parseUnknownRequest
If ezcWebdavTransport receives a request with an unknown request method, this hook is announced. The first ezcWebdavRequest object (or ezcWebdavErrorResponse on error) returned from any of the assigned callbacks will be used for further proceeding and no more callbacks will be performed.
The parameters send by this hook are:
- path
- The path contained in the request URI, already transformed by an ezcWebdavPathFactory, as a string.
- body
- The body contained in the request as a string.
- requestMethod
- The request method as provided by $_SERVER.
Both parameters are submitted by reference, so any changes made to them will have effects on other mechanisms accessing those. Therefore, all manipulations must be performed very carefully.
A return value is only expected, if the request was parsed successfully by the plugin or if the plugin wants to take care about the unknown request, but was not able to parse it. In the first (success) case the callback must return an instance of ezcWebdavRequest, in the second an instance of ezcWebdavErrorResponse. If a plugin returns any value beside null, the processing of callbacks is stopped and the return value is taken for further processing.
handleUnknownResponse
This special hook is announced, if ezcWebdavTransport receives an instance of ezcWebdavResponse that it can not handle. The first callback that reacts on this hook and returns a value beside null will be chosen to handle the response. The reacting callback must return an instance of ezcWebdavDisplayInformation that contains the information to be send to the client.
Parameters send by this hook are:
- response
- The instance of ezcWebdavResponse that shall be serialized.
A return value is only expected, if the response was handled successfully by the plugin or if the plugin wants to take care about the unknown response, but was not able to handle it. In any case, if the plugin feels responsible for the request, it must return an instance of ezcWebdavDisplayInformation which is then taken to send information to the client. If a plugin returns any value beside null, the processing of callbacks is stopped and the return value is taken for further processing.
ezcWebdavPropertyHandler
While the hooks offered by the ezcWebdavTransport class are related to parsing and processing ezcWebdavRequest/ezcWebdavResponse objects, the hooks offere by ezcWebdavPropertyHandler are related to parsing and processing properties. The class offers classes related to dead and live properties as detailed below:
beforeExtractLiveProperty
Live properties are such properties that are validated and taken care of by the server instance, in contrast to dead properties which are only stored by the server but not validated or even processed.
This hook is announced right before whenever the component attempts to parse a live property. This might be either that a request contained the XML representation of the property or that a backend needs to restore the property from a stored XML representation.
Parameters submitted by this hook are:
- domElement
- The DOM element that contains the live property to parse.
- xmlTool
- The instance of ezcWebdavXmlTool that must be used for any XML related operations.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterExtractLiveProperty
Live properties are such properties that are validated and taken care of by the server instance, in contrast to dead properties which are only stored by the server but not validated or even processed.
This hook is announced right after whenever the component has parsed a live property. This might be either that a request contained the XML representation of the property or that a backend needs to restore the property from a stored XML representation.
Parameters submitted by this hook are:
- property
- The property object that was just parsed (ezcWebdavLiveProperty).
- xmlTool
- The instance of ezcWebdavXmlTool that must be used for any XML related operations.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeExtractDeadProperty
A dead property in WebDAV terms is a named container that contains any arbitrary XML data, being attached to a resource. The server will not take any care about the contents of a dead property, but just store and restore it on request.
This hook is announced right before whenever the component attempts to parse a dead property. This might be either that a request contained the XML representation of the property or that a backend needs to restore the property from a stored XML representation.
Parameters submitted by this hook are:
- domElement
- The DOM element that contains the live property to parse.
- xmlTool
- The instance of ezcWebdavXmlTool that must be used for any XML related operations.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterExtractDeadProperty
A dead property in WebDAV terms is a named container that contains any arbitrary XML data, being attached to a resource. The server will not take any care about the contents of a dead property, but just store and restore it on request.
This hook is announced right after whenever the component has parsed a dead property. This might be either that a request contained the XML representation of the property or that a backend needs to restore the property from a stored XML representation.
Parameters submitted by this hook are:
- property
- The property object that was just parsed (ezcWebdavDeadProperty).
- xmlTool
- The instance of ezcWebdavXmlTool that must be used for any XML related operations.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeSerializeLiveProperty
Live properties are such properties that are validated and taken care of by the server instance, in contrast to dead properties which are only stored by the server but not validated or even processed.
This hook is announced right before whenever the component attempts serialize an instance of ezcWebdavLiveProperty to its XML representation. This might happen if a property is to be send in a response or if a backend is going to store the property in its XML representation.
Parameters submitted by this hook are:
- property
- The property object that is to be serialized (ezcWebdavLiveProperty).
- xmlTool
- The instance of ezcWebdavXmlTool that must be used for any XML related operations.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterSerializeLiveProperty
Live properties are such properties that are validated and taken care of by the server instance, in contrast to dead properties which are only stored by the server but not validated or even processed.
This hook is announced right after whenever the component has serialized an instance of ezcWebdavLiveProperty to its XML representation. This might happen if a property is to be send in a response or if a backend is going to store the property in its XML representation.
Parameters submitted by this hook are:
- domElement
- The DOMElement instance representing the property in XML (ezcWebdavLiveProperty).
- xmlTool
- The instance of ezcWebdavXmlTool that must be used for any XML related operations.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
beforeSerializeDeadProperty
A dead property in WebDAV terms is a named container that contains any arbitrary XML data, being attached to a resource. The server will not take any care about the contents of a dead property, but just store and restore it on request.
This hook is announced right before whenever the component attempts serialize an instance of ezcWebdavDeadProperty to its XML representation. This might happen if a property is to be send in a response or if a backend is going to store the property in its XML representation.
Parameters submitted by this hook are:
- property
- The property object that is to be serialized (ezcWebdavDeadProperty).
- xmlTool
- The instance of ezcWebdavXmlTool that must be used for any XML related operations.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
afterSerializeDeadProperty
A dead property in WebDAV terms is a named container that contains any arbitrary XML data, being attached to a resource. The server will not take any care about the contents of a dead property, but just store and restore it on request.
This hook is announced right after whenever the component has serialized an instance of ezcWebdavDeadProperty to its XML representation. This might happen if a property is to be send in a response or if a backend is going to store the property in its XML representation.
Parameters submitted by this hook are:
- domElement
- The DOMElement instance representing the property in XML (ezcWebdavDeadProperty).
- xmlTool
- The instance of ezcWebdavXmlTool that must be used for any XML related operations.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
The return value of callbacks assigned to this hook will be ignored and therefore may not occur, since processing of additional callbacks will be stopped as soon as a return value is send.
extractUnknownLiveProperty
Live properties are such properties that are validated and taken care of by the server instance, in contrast to dead properties which are only stored by the server but not validated or even processed.
If the ezcWebdavPropertyHandler attempts to parse a live property from XML, which it does not know by itself, this hook is announced. As soon as the first callback returns an instance of ezcWebdavLiveProperty, the hook announcement is ended and the returned object will be used.
Parameters submitted by this hook are:
- domElement
- The DOMElement instance representing the property in XML (ezcWebdavDeadProperty).
- xmlTool
- The instance of ezcWebdavXmlTool that must be used for any XML related operations.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
A return value from a callback is only expected, if the callback was able to parse the live property. In this case, it must return the created instance of ezcWebdavLiveProperty, containing the property data. If a callback returned a value, no further callbacks will be dispatched.
If a plugin decides to assign a callback to this hook to parse custom live properties, it must also assign to the serializeUnknownLiveProperty hook, to ensure that the property object can also be serialized back to an XML representation.
serializeUnknownLiveProperty
Live properties are such properties that are validated and taken care of by the server instance, in contrast to dead properties which are only stored by the server but not validated or even processed.
If the ezcWebdavPropertyHandler attempts to serialize a live property to XML, which it does not know by itself, this hook is announced. As soon as the first callback returns an instance of ezcWebdavLiveProperty, the hook announcement is ended and the returned object will be used.
Parameters submitted by this hook are:
- property
- The property object that is to be serialized (ezcWebdavDeadProperty).
- xmlTool
- The instance of ezcWebdavXmlTool that must be used for any XML related operations.
- parentElement
- This instance of DOMElement will contaoin the returned DOMElement later. Its ownerDocument must be used to create or import the nodes returned, so that they can be appended to the parentElement. The appending may not be handled by the callback itself.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
A return value from a callback is only expected, if the callback was able to serialize the live property. In this case, it must return the created instance of DOMElement, containing the property data as XML. If a callback returned a value, no further callbacks will be dispatched.
If a plugin decides to assign a callback to this hook to serialize custom live properties, it must also assign to the parseUnknownLiveProperty hook, to ensure that the property object can also be from an XML representation.
ezcWebdavServer
The main WebDAV server object receives any request that was parsed by ezcWebdavTransport and dispatches it to the backend to use. On the way back it receives a response from the backend to pass it to ezcWebdavTransport again for serializating the contained and sending it to the client.
To handle unknown requests and responses, as well as to react on certain requests or responses, the server object offers 2 important hooks.
receivedRequest
This hook is announced whenever a request is received by the server through ezcWebdavTransport. The hook should be used by plugins for 2 reasons:
React on request objects without affecting the further process.
React on request objects, but replacing the further process.
If a plugin just wants to be informed about certain requests, it must not return a value from its callback. If this is the case, further callbacks assigned to this hook will be processed.
In the second case, the plugin wants to take care for processing the request itself and must return an instance of ezcWebdavResponse afterwards. If this is the case, dispatching of callbacks for this hook is stopped and the generatedResponse hook is announced for the response, right before it is send to ezcWebdavTransport for being serialized and send. Note that the processing of the request by the backend will not take place in this case. If the backend should still take care about a request, no return value may be returned by any assigned callback.
A plugin may choose to handle a request completly on its own and may use any of the public API that is provided by the server, that is create new request objects and let them get processed by server and backend.
Parameters submitted to this hook are:
- request
- The instance of ezcWebdavRequest that was received from ezcWebavTransport.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
generatedResponse
Whenever the server receives an instance of ezcWebdavReponse from either the backend or from a plugin callback, this hook will be announced. The hook allows plugins to be informed about every response that is send to the client. Plugin callbacks can react on these responses or even replace them.
To replace a response, the plugin just needs to exchange the received parameter. The callback must not return any value. If it does, the processing of further callbacks will be stopped immediatelly, but the returned value will be ignored.
If a callback replaced the response object with a different instance of ezcWebdavResponse, all further callbacks are affected by this change and will receive the new response instead of the initial one.
Parameters submitted to this hook are:
- response
- The instance of ezcWebdavResponse that should be send by ezcWebavTransport.
Any changes made to the parameter will have effects on other mechanisms accessing it. Therefore all manipulations must be performed very carefully and should be avoided if possible.
API
Every plugin may access any public API elements of the Webdav component to perform any necessary tasks. To access the correct module for the right task, plugins should follow the following hints to ensure correct working.
Central server
The central entrance point of the Webdav component is the class ezcWebdavServer, which coordinates all other modules. The singleton instance of this class acts also as the central registry for all modules, which can be accessed through the servers properties, once it is initialized.
The singleton instance of the server can be access using ezcWebdavServer->getInstance() and offers the following attributes to be used by plugins:
- $pathFactory
- This attribute contains the instance of ezcWebdavPathFactory that has been configured by the user to be used. In most cases, a plugin will not need to access this one, since it only acts on processed pathes. Only if new request data is parsed or response data needs to be serialized, a plugin might need to access to path factory to parse an URI into a path or the other way around.
- $xmlTool
- The instance of eczWebdavXmlTool is used in the transport layer and while dealing with properties. When dealing with parsing/processing request or response data, this attribute of the server should be accessed for XML handling. In case of property related hooks, the XML tool to use will be provided as a parameter, which _must_ be used in this case.
- $propertyHandler
- The property handler object stored in this attribute is used to parse live and dead properties from XML and serialize them to XML. A plugin can also make use of this functionality. The attribute contains an instance of ezcWebdavPropertyHandler.
- $headerHandler
- Analogous to $propertyHandler, this attribute contains an instance of ezcWebdavHeaderHandler, which can be used by a plugin to access and parse headers sent with the request.
- $transport
- The main element of the transport layer is kept in this attribute: An instance of ezcWebdavTransport, which is responsible for parsing requests and for serializing and sending of responses. Normally, a plugin should not need to access this attribute.
- $backend
- The backend used by the server is hold in this attribute, an instance of ezcWebdavBackend. While a plugin could theoretically access the backends methods directly, it is recommended to interact with it using request and response objects. A newly created request object can be send to the backend using ezcWebdavBackend->performRequest() which will return a response object for evaluation. This will work with every backend, while non-standardized methods might be missing in certain backends, which might break the plugin.
Data transport
It often occurs, that a plugin needs to store data related to an infrastructural element of the component (request/response/property) and to access this data later during the request. To avoid that every plugin needs to implement a storage engine for this on its own, all infrastructual objects allow you to attach certain data to them and read this data later. Note that the data is not presistent between requests, but is only valid during the request.
Intfrastructural elements are all instances of
ezcWebdavRequest
ezcWebdavRepsonse
ezcWebdavProperty
and derived classes. All of these extend ezcWebdavInfrastructureBase, which offers the data storage mechanism for plugins.
To attach data to such an object, the method setPluginData() is used, expecting the namespace of the plugin a key for the data and the data itself. Later, the data can be restored from the same object, by using its getPluginData() with the namespace and key. The methods hasPluginData() and removePluginData() are also available to maintain the storage.