1<?php
2
3namespace Sabre\DAVACL;
4
5use Sabre\DAV;
6use Sabre\HTTP\URLUtil;
7
8/**
9 * Principals Collection
10 *
11 * This is a helper class that easily allows you to create a collection that
12 * has a childnode for every principal.
13 *
14 * To use this class, simply implement the getChildForPrincipal method.
15 *
16 * @copyright Copyright (C) 2007-2015 fruux GmbH (https://fruux.com/).
17 * @author Evert Pot (http://evertpot.com/)
18 * @license http://sabre.io/license/ Modified BSD License
19 */
20abstract class AbstractPrincipalCollection extends DAV\Collection implements IPrincipalCollection {
21
22    /**
23     * Principal backend
24     *
25     * @var PrincipalBackend\BackendInterface
26     */
27    protected $principalBackend;
28
29    /**
30     * The path to the principals we're listing from.
31     *
32     * @var string
33     */
34    protected $principalPrefix;
35
36    /**
37     * If this value is set to true, it effectively disables listing of users
38     * it still allows user to find other users if they have an exact url.
39     *
40     * @var bool
41     */
42    public $disableListing = false;
43
44    /**
45     * Creates the object
46     *
47     * This object must be passed the principal backend. This object will
48     * filter all principals from a specified prefix ($principalPrefix). The
49     * default is 'principals', if your principals are stored in a different
50     * collection, override $principalPrefix
51     *
52     *
53     * @param PrincipalBackend\BackendInterface $principalBackend
54     * @param string $principalPrefix
55     */
56    function __construct(PrincipalBackend\BackendInterface $principalBackend, $principalPrefix = 'principals') {
57
58        $this->principalPrefix = $principalPrefix;
59        $this->principalBackend = $principalBackend;
60
61    }
62
63    /**
64     * This method returns a node for a principal.
65     *
66     * The passed array contains principal information, and is guaranteed to
67     * at least contain a uri item. Other properties may or may not be
68     * supplied by the authentication backend.
69     *
70     * @param array $principalInfo
71     * @return IPrincipal
72     */
73    abstract function getChildForPrincipal(array $principalInfo);
74
75    /**
76     * Returns the name of this collection.
77     *
78     * @return string
79     */
80    function getName() {
81
82        list(, $name) = URLUtil::splitPath($this->principalPrefix);
83        return $name;
84
85    }
86
87    /**
88     * Return the list of users
89     *
90     * @return array
91     */
92    function getChildren() {
93
94        if ($this->disableListing)
95            throw new DAV\Exception\MethodNotAllowed('Listing members of this collection is disabled');
96
97        $children = [];
98        foreach ($this->principalBackend->getPrincipalsByPrefix($this->principalPrefix) as $principalInfo) {
99
100            $children[] = $this->getChildForPrincipal($principalInfo);
101
102
103        }
104        return $children;
105
106    }
107
108    /**
109     * Returns a child object, by its name.
110     *
111     * @param string $name
112     * @throws DAV\Exception\NotFound
113     * @return IPrincipal
114     */
115    function getChild($name) {
116
117        $principalInfo = $this->principalBackend->getPrincipalByPath($this->principalPrefix . '/' . $name);
118        if (!$principalInfo) throw new DAV\Exception\NotFound('Principal with name ' . $name . ' not found');
119        return $this->getChildForPrincipal($principalInfo);
120
121    }
122
123    /**
124     * This method is used to search for principals matching a set of
125     * properties.
126     *
127     * This search is specifically used by RFC3744's principal-property-search
128     * REPORT. You should at least allow searching on
129     * http://sabredav.org/ns}email-address.
130     *
131     * The actual search should be a unicode-non-case-sensitive search. The
132     * keys in searchProperties are the WebDAV property names, while the values
133     * are the property values to search on.
134     *
135     * By default, if multiple properties are submitted to this method, the
136     * various properties should be combined with 'AND'. If $test is set to
137     * 'anyof', it should be combined using 'OR'.
138     *
139     * This method should simply return a list of 'child names', which may be
140     * used to call $this->getChild in the future.
141     *
142     * @param array $searchProperties
143     * @param string $test
144     * @return array
145     */
146    function searchPrincipals(array $searchProperties, $test = 'allof') {
147
148        $result = $this->principalBackend->searchPrincipals($this->principalPrefix, $searchProperties, $test);
149        $r = [];
150
151        foreach ($result as $row) {
152            list(, $r[]) = URLUtil::splitPath($row);
153        }
154
155        return $r;
156
157    }
158
159    /**
160     * Finds a principal by its URI.
161     *
162     * This method may receive any type of uri, but mailto: addresses will be
163     * the most common.
164     *
165     * Implementation of this API is optional. It is currently used by the
166     * CalDAV system to find principals based on their email addresses. If this
167     * API is not implemented, some features may not work correctly.
168     *
169     * This method must return a relative principal path, or null, if the
170     * principal was not found or you refuse to find it.
171     *
172     * @param string $uri
173     * @return string
174     */
175    function findByUri($uri) {
176
177        return $this->principalBackend->findByUri($uri, $this->principalPrefix);
178
179    }
180
181}
182