1<?php
2
3namespace Sabre\DAVACL\PrincipalBackend;
4
5/**
6 * Implement this interface to create your own principal backends.
7 *
8 * Creating backends for principals is entirely optional. You can also
9 * implement Sabre\DAVACL\IPrincipal directly. This interface is used solely by
10 * Sabre\DAVACL\AbstractPrincipalCollection.
11 *
12 * @copyright Copyright (C) fruux GmbH (https://fruux.com/)
13 * @author Evert Pot (http://evertpot.com/)
14 * @license http://sabre.io/license/ Modified BSD License
15 */
16interface BackendInterface {
17
18    /**
19     * Returns a list of principals based on a prefix.
20     *
21     * This prefix will often contain something like 'principals'. You are only
22     * expected to return principals that are in this base path.
23     *
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:
26     *   {DAV:}displayname
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.
30     *
31     * @param string $prefixPath
32     * @return array
33     */
34    function getPrincipalsByPrefix($prefixPath);
35
36    /**
37     * Returns a specific principal, specified by it's path.
38     * The returned structure should be the exact same as from
39     * getPrincipalsByPrefix.
40     *
41     * @param string $path
42     * @return array
43     */
44    function getPrincipalByPath($path);
45
46    /**
47     * Updates one ore more webdav properties on a principal.
48     *
49     * The list of mutations is stored in a Sabre\DAV\PropPatch object.
50     * To do the actual updates, you must tell this object which properties
51     * you're going to process with the handle() method.
52     *
53     * Calling the handle method is like telling the PropPatch object "I
54     * promise I can handle updating this property".
55     *
56     * Read the PropPatch documentation for more info and examples.
57     *
58     * @param string $path
59     * @param \Sabre\DAV\PropPatch $propPatch
60     * @return void
61     */
62    function updatePrincipal($path, \Sabre\DAV\PropPatch $propPatch);
63
64    /**
65     * This method is used to search for principals matching a set of
66     * properties.
67     *
68     * This search is specifically used by RFC3744's principal-property-search
69     * REPORT.
70     *
71     * The actual search should be a unicode-non-case-sensitive search. The
72     * keys in searchProperties are the WebDAV property names, while the values
73     * are the property values to search on.
74     *
75     * By default, if multiple properties are submitted to this method, the
76     * various properties should be combined with 'AND'. If $test is set to
77     * 'anyof', it should be combined using 'OR'.
78     *
79     * This method should simply return an array with full principal uri's.
80     *
81     * If somebody attempted to search on a property the backend does not
82     * support, you should simply return 0 results.
83     *
84     * You can also just return 0 results if you choose to not support
85     * searching at all, but keep in mind that this may stop certain features
86     * from working.
87     *
88     * @param string $prefixPath
89     * @param array $searchProperties
90     * @param string $test
91     * @return array
92     */
93    function searchPrincipals($prefixPath, array $searchProperties, $test = 'allof');
94
95    /**
96     * Finds a principal by its URI.
97     *
98     * This method may receive any type of uri, but mailto: addresses will be
99     * the most common.
100     *
101     * Implementation of this API is optional. It is currently used by the
102     * CalDAV system to find principals based on their email addresses. If this
103     * API is not implemented, some features may not work correctly.
104     *
105     * This method must return a relative principal path, or null, if the
106     * principal was not found or you refuse to find it.
107     *
108     * @param string $uri
109     * @param string $principalPrefix
110     * @return string
111     */
112    function findByUri($uri, $principalPrefix);
113
114    /**
115     * Returns the list of members for a group-principal
116     *
117     * @param string $principal
118     * @return array
119     */
120    function getGroupMemberSet($principal);
121
122    /**
123     * Returns the list of groups a principal is a member of
124     *
125     * @param string $principal
126     * @return array
127     */
128    function getGroupMembership($principal);
129
130    /**
131     * Updates the list of group members for a group principal.
132     *
133     * The principals should be passed as a list of uri's.
134     *
135     * @param string $principal
136     * @param array $members
137     * @return void
138     */
139    function setGroupMemberSet($principal, array $members);
140
141}
142