4 * Implement this interface to create your own principal backends.
6 * Creating backends for principals is entirely optional. You can also
7 * implement Sabre_DAVACL_IPrincipal directly. This interface is used solely by
8 * Sabre_DAVACL_AbstractPrincipalCollection.
12 * @copyright Copyright (C) 2007-2012 Rooftop Solutions. All rights reserved.
13 * @author Evert Pot (http://www.rooftopsolutions.nl/)
14 * @license http://code.google.com/p/sabredav/wiki/License Modified BSD License
16 interface Sabre_DAVACL_IPrincipalBackend {
19 * Returns a list of principals based on a prefix.
21 * This prefix will often contain something like 'principals'. You are only
22 * expected to return principals that are in this base path.
24 * You are expected to return at least a 'uri' for every user, you can
25 * return any additional properties if you wish so. Common properties are:
27 * {http://sabredav.org/ns}email-address - This is a custom SabreDAV
28 * field that's actually injected in a number of other properties. If
29 * you have an email address, use this property.
31 * @param string $prefixPath
34 function getPrincipalsByPrefix($prefixPath);
37 * Returns a specific principal, specified by it's path.
38 * The returned structure should be the exact same as from
39 * getPrincipalsByPrefix.
44 function getPrincipalByPath($path);
47 * Updates one ore more webdav properties on a principal.
49 * The list of mutations is supplied as an array. Each key in the array is
50 * a propertyname, such as {DAV:}displayname.
52 * Each value is the actual value to be updated. If a value is null, it
55 * This method should be atomic. It must either completely succeed, or
56 * completely fail. Success and failure can simply be returned as 'true' or
59 * It is also possible to return detailed failure information. In that case
60 * an array such as this should be returned:
64 * '{DAV:}prop1' => null,
67 * '{DAV:}prop2' => null,
70 * '{DAV:}prop3' => null,
73 * '{DAV:}prop4' => null,
77 * In this previous example prop1 was successfully updated or deleted, and
78 * prop2 was succesfully created.
80 * prop3 failed to update due to '403 Forbidden' and because of this prop4
81 * also could not be updated with '424 Failed dependency'.
83 * This last example was actually incorrect. While 200 and 201 could appear
84 * in 1 response, if there's any error (403) the other properties should
85 * always fail with 423 (failed dependency).
87 * But anyway, if you don't want to scratch your head over this, just
88 * return true or false.
91 * @param array $mutations
94 function updatePrincipal($path, $mutations);
97 * This method is used to search for principals matching a set of
100 * This search is specifically used by RFC3744's principal-property-search
101 * REPORT. You should at least allow searching on
102 * http://sabredav.org/ns}email-address.
104 * The actual search should be a unicode-non-case-sensitive search. The
105 * keys in searchProperties are the WebDAV property names, while the values
106 * are the property values to search on.
108 * If multiple properties are being searched on, the search should be
111 * This method should simply return an array with full principal uri's.
113 * If somebody attempted to search on a property the backend does not
114 * support, you should simply return 0 results.
116 * You can also just return 0 results if you choose to not support
117 * searching at all, but keep in mind that this may stop certain features
120 * @param string $prefixPath
121 * @param array $searchProperties
124 function searchPrincipals($prefixPath, array $searchProperties);
127 * Returns the list of members for a group-principal
129 * @param string $principal
132 function getGroupMemberSet($principal);
135 * Returns the list of groups a principal is a member of
137 * @param string $principal
140 function getGroupMembership($principal);
143 * Updates the list of group members for a group principal.
145 * The principals should be passed as a list of uri's.
147 * @param string $principal
148 * @param array $members
151 function setGroupMemberSet($principal, array $members);