Documentation

Sabre
DAV

Server
in package

Application

implements LoggerAwareInterface, EmitterInterface Uses WildcardEmitterTrait, LoggerAwareTrait

Main DAV server class.

Interfaces, Classes and Traits

LoggerAwareInterface: Describes a logger-aware instance.
EmitterInterface: Event Emitter Interface.

DEPTH_INFINITY = -1: Infinity is used for some request supporting the HTTP Depth header and indicates that the operation should traverse the entire tree.
NS_SABREDAV = 'http://sabredav.org/ns': XML namespace for all SabreDAV related elements.
$debugExceptions : bool: This is a flag that allow or not showing file, line and code of the exception in the returned XML.
$enablePropfindDepthInfinity : bool: This property allows the usage of Depth: infinity on PROPFIND requests.
$exposeVersion : bool: If this setting is turned off, SabreDAV's version number will be hidden from various places.
$httpRequest : Request: httpRequest.
$httpResponse : Response: httpResponse.
$protectedProperties : array<string|int, string>: This is a list of properties that are always server-controlled, and must not get modified with PROPPATCH.
$resourceTypeMapping : array<string|int, mixed>: This property allows you to automatically add the 'resourcetype' value based on a node's classname or interface.
$sapi : Sapi: PHP HTTP Sapi.
$streamMultiStatus : bool: If this setting is turned on, any multi status response on any PROPFIND will be streamed to the output buffer.
$transactionType : string: This property will be filled with a unique string that describes the transaction. This is useful for performance measuring and logging purposes.
$tree : Tree: The tree object.
$xml : Service: Reference to the XML utility object.
$baseUri : string: The base uri.
$listenerIndex : mixed: An index of listeners for a specific event name. This helps speeding up emitting events after all listeners have been set.
$listeners : mixed: The list of listeners.
$logger : LoggerInterface: The logger instance.
$plugins : array<string|int, mixed>: The list of plugins.
$wildcardListeners : mixed: The list of "wildcard listeners".
__construct() : mixed: Sets up the server.
addPlugin() : mixed: Adds a plugin to the server.
calculateUri() : string: Turns a URI such as the REQUEST_URI into a local path.
checkPreconditions() : bool: This method checks the main HTTP preconditions.
createCollection() : array<string|int, mixed>|null: Use this method to create a new collection.
createDirectory() : mixed: This method is invoked by sub-systems creating a new directory.
createFile() : bool: This method is invoked by sub-systems creating a new file.
emit() : bool: Emits an event.
exec() : mixed: Alias of start().
generateMultiStatus() : callable|string: Returns a callback generating a WebDAV propfind response body based on a list of nodes.
getAllowedMethods() : array<string|int, mixed>: Returns an array with all the supported HTTP methods for a specific uri.
getBaseUri() : string: Returns the base responding uri.
getCopyAndMoveInfo() : array<string|int, mixed>: Returns information about Copy and Move requests.
getHTTPDepth() : int: Returns the HTTP depth header.
getHTTPHeaders() : array<string|int, mixed>: Returns a list of HTTP headers for a particular resource.
getHTTPPrefer() : array<string|int, mixed>: Returns the HTTP Prefer header information.
getHTTPRange() : array<string|int, int>|null: Returns the HTTP range header.
getIfConditions() : array<string|int, mixed>: This method is created to extract information from the WebDAV HTTP 'If:' header.
getLogger() : LoggerInterface: Returns the PSR-3 logger object.
getPlugin() : ServerPlugin: Returns an initialized plugin by it's name.
getPlugins() : array<string|int, mixed>: Returns all plugins.
getProperties() : array<string|int, mixed>: Returns a list of properties for a path.
getPropertiesByNode() : bool: Determines all properties for a node.
getPropertiesForChildren() : array<string|int, mixed>: A kid-friendly way to fetch properties for a node's children.
getPropertiesForMultiplePaths() : array<string|int, mixed>: Returns a list of properties for a list of paths.
getPropertiesForPath() : array<string|int, mixed>: Returns a list of properties for a given path.
getPropertiesIteratorForPath() : Iterator: Returns a list of properties for a given path.
getRequestUri() : string: Gets the uri for the request, keeping the base uri into consideration.
getResourceTypeForNode() : array<string|int, mixed>: Returns an array with resourcetypes for a node.
guessBaseUri() : string: This method attempts to detect the base uri.
invokeMethod() : mixed: Handles a http request, and execute a method based on its name.
listeners() : array<string|int, callable>: Returns the list of listeners for an event.
on() : mixed: Subscribe to an event.
once() : mixed: Subscribe to an event exactly once.
removeAllListeners() : mixed: Removes all listeners.
removeListener() : bool: Removes a specific listener from an event.
setBaseUri() : mixed: Sets the base server uri.
setLogger() : mixed: Sets a logger.
start() : mixed: Starts the DAV Server.
updateFile() : bool: This method is invoked by sub-systems updating a file.
updateProperties() : array<string|int, mixed>: This method updates a resource's properties.
generatePathNodes() : Traversable: Small helper to support PROPFIND with DEPTH_INFINITY.
writeMultiStatus() : mixed

DEPTH_INFINITY

Infinity is used for some request supporting the HTTP Depth header and indicates that the operation should traverse the entire tree.


    public
    mixed
    DEPTH_INFINITY
    = -1

NS_SABREDAV

XML namespace for all SabreDAV related elements.


    public
    mixed
    NS_SABREDAV
    = 'http://sabredav.org/ns'

$debugExceptions

This is a flag that allow or not showing file, line and code of the exception in the returned XML.


    public
        bool
    $debugExceptions
     = false

$enablePropfindDepthInfinity

This property allows the usage of Depth: infinity on PROPFIND requests.


    public
        bool
    $enablePropfindDepthInfinity
     = false

By default Depth: infinity is treated as Depth: 1. Allowing Depth: infinity is potentially risky, as it allows a single client to do a full index of the webdav server, which is an easy DoS attack vector.

Only turn this on if you know what you're doing.

$exposeVersion

If this setting is turned off, SabreDAV's version number will be hidden from various places.


    public
    static    bool
    $exposeVersion
     = true

Some people feel this is a good security measure.

$httpRequest

httpRequest.


    public
        Request
    $httpRequest

$httpResponse

httpResponse.


    public
        Response
    $httpResponse

$protectedProperties

This is a list of properties that are always server-controlled, and must not get modified with PROPPATCH.


    public
        array<string|int, string>
    $protectedProperties
     = [
    // RFC4918
    '{DAV:}getcontentlength',
    '{DAV:}getetag',
    '{DAV:}getlastmodified',
    '{DAV:}lockdiscovery',
    '{DAV:}supportedlock',
    // RFC4331
    '{DAV:}quota-available-bytes',
    '{DAV:}quota-used-bytes',
    // RFC3744
    '{DAV:}supported-privilege-set',
    '{DAV:}current-user-privilege-set',
    '{DAV:}acl',
    '{DAV:}acl-restrictions',
    '{DAV:}inherited-acl-set',
    // RFC3253
    '{DAV:}supported-method-set',
    '{DAV:}supported-report-set',
    // RFC6578
    '{DAV:}sync-token',
    // calendarserver.org extensions
    '{http://calendarserver.org/ns/}ctag',
    // sabredav extensions
    '{http://sabredav.org/ns}sync-token',
]

Plugins may add to this list.

$resourceTypeMapping

This property allows you to automatically add the 'resourcetype' value based on a node's classname or interface.


    public
        array<string|int, mixed>
    $resourceTypeMapping
     = ['Sabre\DAV\ICollection' => '{DAV:}collection']

The preset ensures that {DAV:}collection is automatically added for nodes implementing Sabre\DAV\ICollection.

$sapi

PHP HTTP Sapi.


    public
        Sapi
    $sapi

$streamMultiStatus

If this setting is turned on, any multi status response on any PROPFIND will be streamed to the output buffer.


    public
    static    bool
    $streamMultiStatus
     = false

This will be beneficial for large result sets which will no longer consume a large amount of memory as well as send back data to the client earlier.

$transactionType

This property will be filled with a unique string that describes the transaction. This is useful for performance measuring and logging purposes.


    public
        string
    $transactionType

By default it will just fill it with a lowercased HTTP method name, but plugins override this. For example, the WebDAV-Sync sync-collection report will set this to 'report-sync-collection'.

$tree

The tree object.


    public
        Tree
    $tree

$xml

Reference to the XML utility object.


    public
        Service
    $xml

$baseUri

The base uri.


    protected
        string
    $baseUri
     = null

$listenerIndex

An index of listeners for a specific event name. This helps speeding up emitting events after all listeners have been set.


    protected
        mixed
    $listenerIndex
     = []

If the list of listeners changes though, the index clears.

$listeners

The list of listeners.


    protected
        mixed
    $listeners
     = []

$logger

The logger instance.


    protected
        LoggerInterface
    $logger

$plugins

The list of plugins.


    protected
        array<string|int, mixed>
    $plugins
     = []

$wildcardListeners

The list of "wildcard listeners".


    protected
        mixed
    $wildcardListeners
     = []

__construct()

Sets up the server.


    public
                __construct([Tree|INode|array<string|int, mixed>|null $treeOrNode = null ]) : mixed

If a Sabre\DAV\Tree object is passed as an argument, it will use it as the directory tree. If a Sabre\DAV\INode is passed, it will create a Sabre\DAV\Tree and use the node as the root.

If nothing is passed, a Sabre\DAV\SimpleCollection is created in a Sabre\DAV\Tree.

If an array is passed, we automatically create a root node, and use the nodes in the array as top-level children.

Parameters

$treeOrNode : Tree|INode|array<string|int, mixed>|null = null: The tree object

Return values

mixed —

addPlugin()

Adds a plugin to the server.


    public
                addPlugin(ServerPlugin $plugin) : mixed

For more information, console the documentation of Sabre\DAV\ServerPlugin

Parameters

$plugin : ServerPlugin

Return values

mixed —

calculateUri()

Turns a URI such as the REQUEST_URI into a local path.


    public
                calculateUri(string $uri) : string

This method:

strips off the base path
normalizes the path
uri-decodes the path

Parameters

$uri : string

Return values

string —

checkPreconditions()

This method checks the main HTTP preconditions.


    public
                checkPreconditions(RequestInterface $request, ResponseInterface $response) : bool

Currently these are:

If-Match
If-None-Match
If-Modified-Since
If-Unmodified-Since

The method will return true if all preconditions are met The method will return false, or throw an exception if preconditions failed. If false is returned the operation should be aborted, and the appropriate HTTP response headers are already set.

Normally this method will throw 412 Precondition Failed for failures related to If-None-Match, If-Match and If-Unmodified Since. It will set the status to 304 Not Modified for If-Modified_since.

Parameters

$request : RequestInterface
$response : ResponseInterface

Return values

bool —

createCollection()

Use this method to create a new collection.


    public
                createCollection(string $uri, MkCol $mkCol) : array<string|int, mixed>|null

Parameters

$uri : string: The new uri
$mkCol : MkCol

Return values

array<string|int, mixed>|null —

createDirectory()

This method is invoked by sub-systems creating a new directory.


    public
                createDirectory(string $uri) : mixed

Parameters

$uri : string

Return values

mixed —

createFile()

This method is invoked by sub-systems creating a new file.


    public
                createFile(string $uri, resource $data[, string &$etag = null ]) : bool

Currently this is done by HTTP PUT and HTTP LOCK (in the Locks_Plugin). It was important to get this done through a centralized function, allowing plugins to intercept this using the beforeCreateFile event.

This method will return true if the file was actually created

Parameters

$uri : string
$data : resource
$etag : string = null

Return values

bool —

emit()

Emits an event.


    public
                emit(string $eventName[, array<string|int, mixed> $arguments = [] ][, callable $continueCallBack = null ]) : bool

This method will return true if 0 or more listeners were successfully handled. false is returned if one of the events broke the event chain.

If the continueCallBack is specified, this callback will be called every time before the next event handler is called.

If the continueCallback returns false, event propagation stops. This allows you to use the eventEmitter as a means for listeners to implement functionality in your application, and break the event loop as soon as some condition is fulfilled.

Note that returning false from an event subscriber breaks propagation and returns false, but if the continue-callback stops propagation, this is still considered a 'successful' operation and returns true.

Lastly, if there are 5 event handlers for an event. The continueCallback will be called at most 4 times.

Parameters

$eventName : string
$arguments : array<string|int, mixed> = []
$continueCallBack : callable = null

Return values

bool —

exec()

Alias of start().


    public
                exec() : mixed

Return values

mixed —

generateMultiStatus()

Returns a callback generating a WebDAV propfind response body based on a list of nodes.


    public
                generateMultiStatus(array<string|int, mixed>|Traversable $fileProperties[, bool $strip404s = false ]) : callable|string

If 'strip404s' is set to true, all 404 responses will be removed.

Parameters

$fileProperties : array<string|int, mixed>|Traversable: The list with nodes
$strip404s : bool = false

Return values

callable|string —

getAllowedMethods()

Returns an array with all the supported HTTP methods for a specific uri.


    public
                getAllowedMethods(string $path) : array<string|int, mixed>

Parameters

$path : string

Return values

array<string|int, mixed> —

getBaseUri()

Returns the base responding uri.


    public
                getBaseUri() : string

Return values

string —

getCopyAndMoveInfo()

Returns information about Copy and Move requests.


    public
                getCopyAndMoveInfo(RequestInterface $request) : array<string|int, mixed>

This function is created to help getting information about the source and the destination for the WebDAV MOVE and COPY HTTP request. It also validates a lot of information and throws proper exceptions

The returned value is an array with the following keys:

destination - Destination path
destinationExists - Whether or not the destination is an existing url (and should therefore be overwritten)

Parameters

$request : RequestInterface

Return values

array<string|int, mixed> —

getHTTPDepth()

Returns the HTTP depth header.


    public
                getHTTPDepth([mixed $default = self::DEPTH_INFINITY ]) : int

This method returns the contents of the HTTP depth request header. If the depth header was 'infinity' it will return the Sabre\DAV\Server::DEPTH_INFINITY object It is possible to supply a default depth value, which is used when the depth header has invalid content, or is completely non-existent

Parameters

$default : mixed = self::DEPTH_INFINITY

Return values

int —

getHTTPHeaders()

Returns a list of HTTP headers for a particular resource.


    public
                getHTTPHeaders(string $path) : array<string|int, mixed>

The generated http headers are based on properties provided by the resource. The method basically provides a simple mapping between DAV property and HTTP header.

The headers are intended to be used for HEAD and GET requests.

Parameters

$path : string

Return values

array<string|int, mixed> —

getHTTPPrefer()

Returns the HTTP Prefer header information.


    public
                getHTTPPrefer() : array<string|int, mixed>

The prefer header is defined in: http://tools.ietf.org/html/draft-snell-http-prefer-14

This method will return an array with options.

Currently, the following options may be returned: [ 'return-asynch' => true, 'return-minimal' => true, 'return-representation' => true, 'wait' => 30, 'strict' => true, 'lenient' => true, ]

This method also supports the Brief header, and will also return 'return-minimal' if the brief header was set to 't'.

For the boolean options, false will be returned if the headers are not specified. For the integer options it will be 'null'.

Return values

array<string|int, mixed> —

getHTTPRange()

Returns the HTTP range header.


    public
                getHTTPRange() : array<string|int, int>|null

This method returns null if there is no well-formed HTTP range request header or array($start, $end).

The first number is the offset of the first byte in the range. The second number is the offset of the last byte in the range.

If the second offset is null, it should be treated as the offset of the last byte of the entity If the first offset is null, the second offset should be used to retrieve the last x bytes of the entity

Return values

array<string|int, int>|null —

getIfConditions()

This method is created to extract information from the WebDAV HTTP 'If:' header.


    public
                getIfConditions(RequestInterface $request) : array<string|int, mixed>

The If header can be quite complex, and has a bunch of features. We're using a regex to extract all relevant information The function will return an array, containing structs with the following keys

uri - the uri the condition applies to.
tokens - The lock token. another 2 dimensional array containing 3 elements

Example 1:

If: (opaquelocktoken:181d4fae-7d8c-11d0-a765-00a0c91e6bf2)

Would result in:

[ [ 'uri' => '/request/uri', 'tokens' => [ [ [ 'negate' => false, 'token' => 'opaquelocktoken:181d4fae-7d8c-11d0-a765-00a0c91e6bf2', 'etag' => "" ] ] ], ] ]

Example 2:

If: </path/> (Not opaquelocktoken:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 ["Im An ETag"]) (["Another ETag"]) </path2/> (Not ["Path2 ETag"])

Would result in:

[ [ 'uri' => 'path', 'tokens' => [ [ [ 'negate' => true, 'token' => 'opaquelocktoken:181d4fae-7d8c-11d0-a765-00a0c91e6bf2', 'etag' => '"Im An ETag"' ], [ 'negate' => false, 'token' => '', 'etag' => '"Another ETag"' ] ] ], ], [ 'uri' => 'path2', 'tokens' => [ [ [ 'negate' => true, 'token' => '', 'etag' => '"Path2 ETag"' ] ] ], ], ]

Parameters

$request : RequestInterface

Return values

array<string|int, mixed> —

getLogger()

Returns the PSR-3 logger object.


    public
                getLogger() : LoggerInterface

Return values

LoggerInterface —

getPlugin()

Returns an initialized plugin by it's name.


    public
                getPlugin(string $name) : ServerPlugin

This function returns null if the plugin was not found.

Parameters

$name : string

Return values

ServerPlugin —

getPlugins()

Returns all plugins.


    public
                getPlugins() : array<string|int, mixed>

Return values

array<string|int, mixed> —

getProperties()

Returns a list of properties for a path.


    public
                getProperties(string $path, array<string|int, mixed> $propertyNames) : array<string|int, mixed>

This is a simplified version getPropertiesForPath. If you aren't interested in status codes, but you just want to have a flat list of properties, use this method.

Please note though that any problems related to retrieving properties, such as permission issues will just result in an empty array being returned.

Parameters

$path : string
$propertyNames : array<string|int, mixed>

Return values

array<string|int, mixed> —

getPropertiesByNode()

Determines all properties for a node.


    public
                getPropertiesByNode(PropFind $propFind, INode $node) : bool

This method tries to grab all properties for a node. This method is used internally getPropertiesForPath and a few others.

It could be useful to call this, if you already have an instance of your target node and simply want to run through the system to get a correct list of properties.

Parameters

$propFind : PropFind
$node : INode

Return values

bool —

getPropertiesForChildren()

A kid-friendly way to fetch properties for a node's children.


    public
                getPropertiesForChildren(string $path, array<string|int, mixed> $propertyNames) : array<string|int, mixed>

The returned array will be indexed by the path of the of child node. Only properties that are actually found will be returned.

The parent node will not be returned.

Parameters

$path : string
$propertyNames : array<string|int, mixed>

Return values

array<string|int, mixed> —

getPropertiesForMultiplePaths()

Returns a list of properties for a list of paths.


    public
                getPropertiesForMultiplePaths(array<string|int, mixed> $paths[, array<string|int, mixed> $propertyNames = [] ]) : array<string|int, mixed>

The path that should be supplied should have the baseUrl stripped out The list of properties should be supplied in Clark notation. If the list is empty 'allprops' is assumed.

The result is returned as an array, with paths for it's keys. The result may be returned out of order.

Parameters

$paths : array<string|int, mixed>
$propertyNames : array<string|int, mixed> = []

Return values

array<string|int, mixed> —

getPropertiesForPath()

Returns a list of properties for a given path.


    public
                getPropertiesForPath(string $path[, array<string|int, mixed> $propertyNames = [] ], int $depth) : array<string|int, mixed>

The path that should be supplied should have the baseUrl stripped out The list of properties should be supplied in Clark notation. If the list is empty 'allprops' is assumed.

If a depth of 1 is requested child elements will also be returned.

Parameters

$path : string
$propertyNames : array<string|int, mixed> = []
$depth : int

Return values

array<string|int, mixed> —

getPropertiesIteratorForPath()

Returns a list of properties for a given path.


    public
                getPropertiesIteratorForPath(string $path[, array<string|int, mixed> $propertyNames = [] ], int $depth) : Iterator

The path that should be supplied should have the baseUrl stripped out The list of properties should be supplied in Clark notation. If the list is empty 'allprops' is assumed.

If a depth of 1 is requested child elements will also be returned.

Parameters

$path : string
$propertyNames : array<string|int, mixed> = []
$depth : int

Return values

Iterator —

getRequestUri()

Gets the uri for the request, keeping the base uri into consideration.


    public
                getRequestUri() : string

Return values

string —

getResourceTypeForNode()

Returns an array with resourcetypes for a node.


    public
                getResourceTypeForNode(INode $node) : array<string|int, mixed>

Parameters

$node : INode

Return values

array<string|int, mixed> —

guessBaseUri()

This method attempts to detect the base uri.


    public
                guessBaseUri() : string

Only the PATH_INFO variable is considered.

If this variable is not set, the root (/) is assumed.

Return values

string —

invokeMethod()

Handles a http request, and execute a method based on its name.


    public
                invokeMethod(RequestInterface $request, ResponseInterface $response[, bool $sendResponse = true ]) : mixed

Parameters

$request : RequestInterface
$response : ResponseInterface
$sendResponse : bool = true: whether to send the HTTP response to the DAV client

Return values

mixed —

listeners()

Returns the list of listeners for an event.


    public
                listeners(string $eventName) : array<string|int, callable>

The list is returned as an array, and the list of events are sorted by their priority.

Parameters

$eventName : string

Return values

array<string|int, callable> —

on()

Subscribe to an event.


    public
                on(string $eventName, callable $callBack[, int $priority = 100 ]) : mixed

Parameters

$eventName : string
$callBack : callable
$priority : int = 100

Return values

mixed —

once()

Subscribe to an event exactly once.


    public
                once(string $eventName, callable $callBack[, int $priority = 100 ]) : mixed

Parameters

$eventName : string
$callBack : callable
$priority : int = 100

Return values

mixed —

removeAllListeners()

Removes all listeners.


    public
                removeAllListeners([string $eventName = null ]) : mixed

If the eventName argument is specified, all listeners for that event are removed. If it is not specified, every listener for every event is removed.

Parameters

$eventName : string = null

Return values

mixed —

removeListener()

Removes a specific listener from an event.


    public
                removeListener(string $eventName, callable $listener) : bool

If the listener could not be found, this method will return false. If it was removed it will return true.

Parameters

$eventName : string
$listener : callable

Return values

bool —

setBaseUri()

Sets the base server uri.


    public
                setBaseUri(string $uri) : mixed

Parameters

$uri : string

Return values

mixed —

setLogger()

Sets a logger.


    public
                setLogger(LoggerInterface $logger) : mixed

Parameters

$logger : LoggerInterface

Return values

mixed —

start()

Starts the DAV Server.


    public
                start() : mixed

Return values

mixed —

updateFile()

This method is invoked by sub-systems updating a file.


    public
                updateFile(string $uri, resource $data[, string &$etag = null ]) : bool

This method will return true if the file was actually updated

Parameters

$uri : string
$data : resource
$etag : string = null

Return values

bool —

updateProperties()

This method updates a resource's properties.


    public
                updateProperties(string $path, array<string|int, mixed> $properties) : array<string|int, mixed>

The properties array must be a list of properties. Array-keys are property names in clarknotation, array-values are it's values. If a property must be deleted, the value should be null.

Note that this request should either completely succeed, or completely fail.

The response is an array with properties for keys, and http status codes as their values.

Parameters

$path : string
$properties : array<string|int, mixed>

Return values

array<string|int, mixed> —

generatePathNodes()

Small helper to support PROPFIND with DEPTH_INFINITY.


    private
                generatePathNodes(PropFind $propFind[, array<string|int, mixed> $yieldFirst = null ]) : Traversable

Parameters

$propFind : PropFind
$yieldFirst : array<string|int, mixed> = null

Return values

Traversable —

writeMultiStatus()


    private
                writeMultiStatus(Writer $w,  $fileProperties, bool $strip404s) : mixed

Parameters

$w : Writer
$fileProperties :
$strip404s : bool

Return values

mixed —