1<?php
2
3namespace Sabre\DAVACL;
4
5use 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 */
17interface 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