Documentation

Sabre
DAVACL

Plugin extends ServerPlugin
in package

Application

SabreDAV ACL Plugin.

This plugin provides functionality to enforce ACL permissions. ACL is defined in RFC3744.

In addition it also provides support for the {DAV:}current-user-principal property, defined in RFC5397 and the {DAV:}expand-property report, as defined in RFC3253.

R_PARENT

Recursion constants.


    public
    mixed
    R_PARENT
    = 1

This only checks the base node

R_RECURSIVE

Recursion constants.


    public
    mixed
    R_RECURSIVE
    = 2

This checks every node in the tree

R_RECURSIVEPARENTS

Recursion constants.


    public
    mixed
    R_RECURSIVEPARENTS
    = 3

This checks every parentnode in the tree, but not leaf-nodes.

$adminPrincipals

Any principal uri's added here, will automatically be added to the list of ACL's. They will effectively receive {DAV:}all privileges, as a protected privilege.


    public
        array<string|int, mixed>
    $adminPrincipals
     = []

$allowUnauthenticatedAccess

The ACL plugin allows privileges to be assigned to users that are not logged in. To facilitate that, it modifies the auth plugin's behavior to only require login when a privileged operation was denied.


    public
        bool
    $allowUnauthenticatedAccess
     = true

Unauthenticated access can be considered a security concern, so it's possible to turn this feature off to harden the server's security.

$hideNodesFromListings

By default nodes that are inaccessible by the user, can still be seen in directory listings (PROPFIND on parent with Depth: 1).


    public
        bool
    $hideNodesFromListings
     = false

In certain cases it's desirable to hide inaccessible nodes. Setting this to true will cause these nodes to be hidden from directory listings.

$principalCollectionSet

List of urls containing principal collections.


    public
        array<string|int, mixed>
    $principalCollectionSet
     = ['principals']

Modify this if your principals are located elsewhere.

$principalSearchPropertySet

This list of properties are the properties a client can search on using the {DAV:}principal-property-search report.


    public
        array<string|int, mixed>
    $principalSearchPropertySet
     = ['{DAV:}displayname' => 'Display name', '{http://sabredav.org/ns}email-address' => 'Email address']

The keys are the property names, values are descriptions.

$defaultAcl

The default ACL rules.


    protected
        array<string|int, mixed>
    $defaultAcl
     = [['principal' => '{DAV:}authenticated', 'protected' => true, 'privilege' => '{DAV:}all']]

These rules are used for nodes that don't implement IACL. These default set of rules allow anyone to do anything, as long as they are authenticated.

$principalMembershipCache

This array holds a cache for all the principals that are associated with a single principal.


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

$server

Reference to server object.


    protected
        Server
    $server

beforeBind()

Triggered before a new node is created.


    public
                beforeBind(string $uri) : mixed

This allows us to check permissions for any operation that creates a new node, such as PUT, MKCOL, MKCALENDAR, LOCK, COPY and MOVE.

Parameters

$uri : string

Return values

mixed —

beforeMethod()

Triggered before any method is handled.


    public
                beforeMethod(RequestInterface $request, ResponseInterface $response) : mixed

Parameters

$request : RequestInterface
$response : ResponseInterface

Return values

mixed —

beforeUnbind()

Triggered before a node is deleted.


    public
                beforeUnbind(string $uri) : mixed

This allows us to check permissions for any operation that will delete an existing node.

Parameters

$uri : string

Return values

mixed —

beforeUnlock()

Triggered before a node is unlocked.


    public
                beforeUnlock(string $uri, LockInfo $lock) : mixed

Parameters

$uri : string
$lock : LockInfo

Return values

mixed —

checkPrivileges()

Checks if the current user has the specified privilege(s).


    public
                checkPrivileges(string $uri, array<string|int, mixed>|string $privileges[, int $recursion = self::R_PARENT ][, bool $throwExceptions = true ]) : bool

You can specify a single privilege, or a list of privileges. This method will throw an exception if the privilege is not available and return true otherwise.

Parameters

$uri : string
$privileges : array<string|int, mixed>|string
$recursion : int = self::R_PARENT
$throwExceptions : bool = true: if set to false, this method won't throw exceptions

Return values

bool —

getAcl()

Returns the full ACL list.


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

Either a uri or a INode may be passed.

null will be returned if the node doesn't support ACLs.

Parameters

$node : string|INode

Return values

array<string|int, mixed> —

getCurrentUserPrincipal()

Returns the standard users' principal.


    public
                getCurrentUserPrincipal() : string|null

This is one authoritative principal url for the current user. This method will return null if the user wasn't logged in.

Return values

string|null —

getCurrentUserPrincipals()

Returns a list of principals that's associated to the current user, either directly or through group membership.


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

Return values

array<string|int, mixed> —

getCurrentUserPrivilegeSet()

Returns a list of privileges the current user has on a particular node.


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

Either a uri or a DAV\INode may be passed.

null will be returned if the node doesn't support ACLs.

Parameters

$node : string|INode

Return values

array<string|int, mixed> —

getDefaultAcl()

Returns the default ACL rules.


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

These rules are used for all nodes that don't implement the IACL interface.

Return values

array<string|int, mixed> —

getFeatures()

Returns a list of features added by this plugin.


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

This list is used in the response of a HTTP OPTIONS request.

Return values

array<string|int, mixed> —

getFlatPrivilegeSet()

Returns the supported privilege set as a flat list.


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

This is much easier to parse.

The returned list will be index by privilege name. The value is a struct containing the following properties:

aggregates
abstract
concrete

Parameters

$node : string|INode

Return values

array<string|int, mixed> —

getHTTPMethods()

Use this method to tell the server this plugin defines additional HTTP methods.


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

This method is passed a uri. It should only return HTTP methods that are available for the specified uri.

Parameters

$path : string

Return values

array<string|int, mixed> —

getMethods()

Returns a list of available methods for a given url.


    public
                getMethods(string $uri) : array<string|int, mixed>

Parameters

$uri : string

Return values

array<string|int, mixed> —

getPluginInfo()

Returns a bunch of meta-data about the plugin.


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

Providing this information is optional, and is mainly displayed by the Browser plugin.

The description key in the returned array may contain html and will not be sanitized.

Return values

array<string|int, mixed> —

getPluginName()

Returns a plugin name.


    public
                getPluginName() : string

Using this name other plugins will be able to access other plugins using Sabre\DAV\Server::getPlugin

Return values

string —

getPrincipalByUri()

Returns a principal based on its uri.


    public
                getPrincipalByUri(string $uri) : string|null

Returns null if the principal could not be found.

Parameters

$uri : string

Return values

string|null —

getPrincipalMembership()

Returns all the principal groups the specified principal is a member of.


    public
                getPrincipalMembership(string $mainPrincipal) : array<string|int, mixed>

Parameters

$mainPrincipal : string

Return values

array<string|int, mixed> —

getSupportedPrivilegeSet()

Returns a tree of supported privileges for a resource.


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

The returned array structure should be in this form:

[ [ 'privilege' => '{DAV:}read', 'abstract' => false, 'aggregates' => [] ] ]

Privileges can be nested using "aggregates". Doing so means that if you assign someone the aggregating privilege, all the sub-privileges will automatically be granted.

Marking a privilege as abstract means that the privilege cannot be directly assigned, but must be assigned via the parent privilege.

So a more complex version might look like this:

[ [ 'privilege' => '{DAV:}read', 'abstract' => false, 'aggregates' => [ [ 'privilege' => '{DAV:}read-acl', 'abstract' => false, 'aggregates' => [], ] ] ] ]

Parameters

$node : string|INode

Return values

array<string|int, mixed> —

getSupportedReportSet()

Returns a list of reports this plugin supports.


    public
                getSupportedReportSet(string $uri) : array<string|int, mixed>

This will be used in the {DAV:}supported-report-set property. Note that you still need to subscribe to the 'report' event to actually implement them

Parameters

$uri : string

Return values

array<string|int, mixed> —

htmlActionsPanel()

This method is used to generate HTML output for the DAV\Browser\Plugin. This allows us to generate an interface users can use to create new calendars.


    public
                htmlActionsPanel(INode $node, string &$output) : bool

Parameters

$node : INode
$output : string

Return values

bool —

httpAcl()

This method is responsible for handling the 'ACL' event.


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

Parameters

$request : RequestInterface
$response : ResponseInterface

Return values

bool —

initialize()

Sets up the plugin.


    public
                initialize(Server $server) : mixed

This method is automatically called by the server class.

Parameters

$server : Server

Return values

mixed —

principalMatchesPrincipal()

Find out of a principal equals another principal.


    public
                principalMatchesPrincipal(string $checkPrincipal[, string $currentPrincipal = null ]) : bool

This is a quick way to find out whether a principal URI is part of a group, or any subgroups.

The first argument is the principal URI you want to check against. For example the principal group, and the second argument is the principal of which you want to find out of it is the same as the first principal, or in a member of the first principal's group or subgroups.

So the arguments are not interchangeable. If principal A is in group B, passing 'B', 'A' will yield true, but 'A', 'B' is false.

If the second argument is not passed, we will use the current user principal.

Parameters

$checkPrincipal : string
$currentPrincipal : string = null

Return values

bool —

principalSearch()

Principal property search.


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

This method can search for principals matching certain values in properties.

This method will return a list of properties for the matched properties.

Parameters

$searchProperties : array<string|int, mixed>: The properties to search on. This is a key-value list. The keys are property names, and the values the strings to match them on.
$requestedProperties : array<string|int, mixed>: this is the list of properties to return for every match
$collectionUri : string = null: the principal collection to search on. If this is ommitted, the standard principal collection-set will be used
$test : string = 'allof': "allof" to use AND to search the properties. 'anyof' for OR.

Return values

array<string|int, mixed> —

This method returns an array structure similar to Sabre\DAV\Server::getPropertiesForPath. Returned properties are index by a HTTP status code.

propFind()

Triggered before properties are looked up in specific nodes.


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

Parameters

$propFind : PropFind
$node : INode

Return values

bool —

propPatch()

This method intercepts PROPPATCH methods and make sure the group-member-set is updated correctly.


    public
                propPatch(string $path, PropPatch $propPatch) : mixed

Parameters

$path : string
$propPatch : PropPatch

Return values

mixed —

report()

This method handles HTTP REPORT requests.


    public
                report(string $reportName, mixed $report, mixed $path) : bool

Parameters

$reportName : string
$report : mixed
$path : mixed

Return values

bool —

setDefaultAcl()

Sets the default ACL rules.


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

These rules are used for all nodes that don't implement the IACL interface.

Parameters

$acl : array<string|int, mixed>

Return values

mixed —

aclPrincipalPropSetReport()

aclPrincipalPropSet REPORT.


    protected
                aclPrincipalPropSetReport(string $path, AclPrincipalPropSetReport $report) : mixed

This method is responsible for handling the {DAV:}acl-principal-prop-set REPORT, as defined in:

https://tools.ietf.org/html/rfc3744#section-9.2

This REPORT allows a user to quickly fetch information about all principals specified in the access control list. Most commonly this is used to for example generate a UI with ACL rules, allowing you to show names for principals for every entry.

Parameters

$path : string
$report : AclPrincipalPropSetReport

Return values

mixed —

expandProperties()

This method expands all the properties and returns a list with property values.


    protected
                expandProperties(array<string|int, mixed> $path, array<string|int, mixed> $requestedProperties, int $depth) : array<string|int, mixed>

Parameters

$path : array<string|int, mixed>
$requestedProperties : array<string|int, mixed>: the list of required properties
$depth : int

Return values

array<string|int, mixed> —

expandPropertyReport()

The expand-property report is defined in RFC3253 section 3.8.


    protected
                expandPropertyReport(string $path, ExpandPropertyReport $report) : mixed

This report is very similar to a standard PROPFIND. The difference is that it has the additional ability to look at properties containing a {DAV:}href element, follow that property and grab additional elements there.

Other rfc's, such as ACL rely on this report, so it made sense to put it in this plugin.

Parameters

$path : string
$report : ExpandPropertyReport

Return values

mixed —

principalMatchReport()

The principal-match report is defined in RFC3744, section 9.3.


    protected
                principalMatchReport(string $path, PrincipalMatchReport $report) : mixed

This report allows a client to figure out based on the current user, or a principal URL, the principal URL and principal URLs of groups that principal belongs to.

Parameters

$path : string
$report : PrincipalMatchReport

Return values

mixed —

principalPropertySearchReport()

principalPropertySearchReport.


    protected
                principalPropertySearchReport(string $path, PrincipalPropertySearchReport $report) : mixed

This method is responsible for handing the {DAV:}principal-property-search report. This report can be used for clients to search for groups of principals, based on the value of one or more properties.

Parameters

$path : string
$report : PrincipalPropertySearchReport

Return values

mixed —

principalSearchPropertySetReport()

principalSearchPropertySetReport.


    protected
                principalSearchPropertySetReport(string $path, PrincipalSearchPropertySetReport $report) : mixed

This method responsible for handing the {DAV:}principal-search-property-set report. This report returns a list of properties the client may search on, using the {DAV:}principal-property-search report.

Parameters

$path : string
$report : PrincipalSearchPropertySetReport

Return values

mixed —