1 <?php
2 
3 namespace Sabre\DAVACL;
4 
5 use Sabre\DAV;
6 
7 /**
8  * Principal Collection interface.
9  *
10  * Implement this interface to ensure that your principal collection can be
11  * searched using the principal-property-search REPORT.
12  *
13  * @copyright Copyright (C) fruux GmbH (https://fruux.com/)
14  * @author Evert Pot (http://evertpot.com/)
15  * @license http://sabre.io/license/ Modified BSD License
16  */
17 interface IPrincipalCollection extends DAV\ICollection {
18 
19     /**
20      * This method is used to search for principals matching a set of
21      * properties.
22      *
23      * This search is specifically used by RFC3744's principal-property-search
24      * REPORT. You should at least allow searching on
25      * http://sabredav.org/ns}email-address.
26      *
27      * The actual search should be a unicode-non-case-sensitive search. The
28      * keys in searchProperties are the WebDAV property names, while the values
29      * are the property values to search on.
30      *
31      * By default, if multiple properties are submitted to this method, the
32      * various properties should be combined with 'AND'. If $test is set to
33      * 'anyof', it should be combined using 'OR'.
34      *
35      * This method should simply return a list of 'child names', which may be
36      * used to call $this->getChild in the future.
37      *
38      * @param array $searchProperties
39      * @param string $test
40      * @return array
41      */
42     function searchPrincipals(array $searchProperties, $test = 'allof');
43 
44     /**
45      * Finds a principal by its URI.
46      *
47      * This method may receive any type of uri, but mailto: addresses will be
48      * the most common.
49      *
50      * Implementation of this API is optional. It is currently used by the
51      * CalDAV system to find principals based on their email addresses. If this
52      * API is not implemented, some features may not work correctly.
53      *
54      * This method must return a relative principal path, or null, if the
55      * principal was not found or you refuse to find it.
56      *
57      * @param string $uri
58      * @return string
59      */
60     function findByUri($uri);
61 
62 }
63