Documentation

HomeCollection extends AbstractPrincipalCollection
in package

Application

implements IACL Uses ACLTrait

This collection contains a collection for every principal.

It is similar to /home on many unix systems.

The per-user collections can only be accessed by the user who owns the collection.

Interfaces, Classes and Traits

IACL: ACL-enabled node.

$collectionName : string: Name of this collection.
$disableListing : bool: If this value is set to true, it effectively disables listing of users it still allows user to find other users if they have an exact url.
$principalBackend : BackendInterface: Principal backend.
$principalPrefix : string: The path to the principals we're listing from.
$storagePath : string: Path to where the users' files are actually stored.
__construct() : mixed: Creates the home collection.
childExists() : bool: Checks is a child-node exists.
createDirectory() : mixed: Creates a new subdirectory.
createFile() : string|null: Creates a new file in the directory.
delete() : mixed: Deletes the current node.
findByUri() : string: Finds a principal by its URI.
getACL() : array<string|int, mixed>: Returns a list of ACE's for this node.
getChild() : INode: Returns a child object, by its name.
getChildForPrincipal() : INode: Returns a principals' collection of files.
getChildren() : array<string|int, mixed>: Return the list of users.
getGroup() : string|null: Returns a group principal.
getLastModified() : int: Returns the last modification time as a unix timestamp.
getName() : string: Returns the name of the node.
getOwner() : string|null: Returns the owner principal.
getSupportedPrivilegeSet() : array<string|int, mixed>|null: Returns the list of supported privileges for this node.
searchPrincipals() : array<string|int, mixed>: This method is used to search for principals matching a set of properties.
setACL() : mixed: Updates the ACL.
setName() : mixed: Renames the node.

$collectionName

Name of this collection.


    public
        string
    $collectionName
     = 'home'

$disableListing

If this value is set to true, it effectively disables listing of users it still allows user to find other users if they have an exact url.


    public
        bool
    $disableListing
     = false

$principalBackend

Principal backend.


    protected
        BackendInterface
    $principalBackend

$principalPrefix

The path to the principals we're listing from.


    protected
        string
    $principalPrefix

$storagePath

Path to where the users' files are actually stored.


    protected
        string
    $storagePath

__construct()

Creates the home collection.


    public
                __construct(BackendInterface $principalBackend, string $storagePath[, string $principalPrefix = 'principals' ]) : mixed

Parameters

$principalBackend : BackendInterface
$storagePath : string: where the actual files are stored
$principalPrefix : string = 'principals': list of principals to iterate

Return values

mixed —

childExists()

Checks is a child-node exists.


    public
                childExists(string $name) : bool

It is generally a good idea to try and override this. Usually it can be optimized.

Parameters

$name : string

Return values

bool —

createDirectory()

Creates a new subdirectory.


    public
                createDirectory(string $name) : mixed

Parameters

$name : string

Return values

mixed —

createFile()

Creates a new file in the directory.


    public
                createFile(string $name[, resource|string $data = null ]) : string|null

Data will either be supplied as a stream resource, or in certain cases as a string. Keep in mind that you may have to support either.

After successful creation of the file, you may choose to return the ETag of the new file here.

The returned ETag must be surrounded by double-quotes (The quotes should be part of the actual string).

If you cannot accurately determine the ETag, you should not return it. If you don't store the file exactly as-is (you're transforming it somehow) you should also not return an ETag.

This means that if a subsequent GET to this new file does not exactly return the same contents of what was submitted here, you are strongly recommended to omit the ETag.

Parameters

$name : string: Name of the file
$data : resource|string = null: Initial payload

Return values

string|null —

delete()

Deletes the current node.


    public
                delete() : mixed

Return values

mixed —

findByUri()

Finds a principal by its URI.


    public
                findByUri(string $uri) : string

This method may receive any type of uri, but mailto: addresses will be the most common.

Implementation of this API is optional. It is currently used by the CalDAV system to find principals based on their email addresses. If this API is not implemented, some features may not work correctly.

This method must return a relative principal path, or null, if the principal was not found or you refuse to find it.

Parameters

$uri : string

Return values

string —

getACL()

Returns a list of ACE's for this node.


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

Each ACE has the following properties:

'privilege', a string such as {DAV:}read or {DAV:}write. These are currently the only supported privileges
'principal', a url to the principal who owns the node
'protected' (optional), indicating that this ACE is not allowed to be updated.

Return values

array<string|int, mixed> —

getChild()

Returns a child object, by its name.


    public
                getChild(string $name) : INode

This method makes use of the getChildren method to grab all the child nodes, and compares the name. Generally its wise to override this, as this can usually be optimized

This method must throw Sabre\DAV\Exception\NotFound if the node does not exist.

Parameters

$name : string

Return values

INode —

getChildForPrincipal()

Returns a principals' collection of files.


    public
                getChildForPrincipal(array<string|int, mixed> $principalInfo) : INode

The passed array contains principal information, and is guaranteed to at least contain a uri item. Other properties may or may not be supplied by the authentication backend.

Parameters

$principalInfo : array<string|int, mixed>

Return values

INode —

getChildren()

Return the list of users.


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

Return values

array<string|int, mixed> —

getGroup()

Returns a group principal.


    public
                getGroup() : string|null

This must be a url to a principal, or null if there's no owner

Return values

string|null —

getLastModified()

Returns the last modification time as a unix timestamp.


    public
                getLastModified() : int

If the information is not available, return null.

Return values

int —

getName()

Returns the name of the node.


    public
                getName() : string

This is used to generate the url.

Return values

string —

getOwner()

Returns the owner principal.


    public
                getOwner() : string|null

This must be a url to a principal, or null if there's no owner

Return values

string|null —

getSupportedPrivilegeSet()

Returns the list of supported privileges for this node.


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

The returned data structure is a list of nested privileges. See Sabre\DAVACL\Plugin::getDefaultSupportedPrivilegeSet for a simple standard structure.

If null is returned from this method, the default privilege set is used, which is fine for most common usecases.

Return values

array<string|int, mixed>|null —

searchPrincipals()

This method is used to search for principals matching a set of properties.


    public
                searchPrincipals(array<string|int, mixed> $searchProperties[, string $test = 'allof' ]) : array<string|int, mixed>

This search is specifically used by RFC3744's principal-property-search REPORT. You should at least allow searching on http://sabredav.org/ns}email-address.

The actual search should be a unicode-non-case-sensitive search. The keys in searchProperties are the WebDAV property names, while the values are the property values to search on.

By default, if multiple properties are submitted to this method, the various properties should be combined with 'AND'. If $test is set to 'anyof', it should be combined using 'OR'.

This method should simply return a list of 'child names', which may be used to call $this->getChild in the future.

Parameters

$searchProperties : array<string|int, mixed>
$test : string = 'allof'

Return values

array<string|int, mixed> —

setACL()

Updates the ACL.


    public
                setACL(array<string|int, mixed> $acl) : mixed

This method will receive a list of new ACE's as an array argument.

Parameters

$acl : array<string|int, mixed>

Return values

mixed —

setName()

Renames the node.


    public
                setName(string $name) : mixed

Parameters

$name : string: The new name

Return values

mixed —