1
0

ContactsManager.php 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217
  1. <?php
  2. /**
  3. * @copyright Copyright (c) 2016, ownCloud, Inc.
  4. *
  5. * @author Bart Visscher <bartv@thisnet.nl>
  6. * @author Joas Schilling <coding@schilljs.com>
  7. * @author John Molakvoæ <skjnldsv@protonmail.com>
  8. * @author Morris Jobke <hey@morrisjobke.de>
  9. * @author Thomas Citharel <nextcloud@tcit.fr>
  10. * @author Thomas Müller <thomas.mueller@tmit.eu>
  11. * @author Tobia De Koninck <tobia@ledfan.be>
  12. *
  13. * @license AGPL-3.0
  14. *
  15. * This code is free software: you can redistribute it and/or modify
  16. * it under the terms of the GNU Affero General Public License, version 3,
  17. * as published by the Free Software Foundation.
  18. *
  19. * This program is distributed in the hope that it will be useful,
  20. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  22. * GNU Affero General Public License for more details.
  23. *
  24. * You should have received a copy of the GNU Affero General Public License, version 3,
  25. * along with this program. If not, see <http://www.gnu.org/licenses/>
  26. *
  27. */
  28. namespace OC;
  29. use OCP\Constants;
  30. use OCP\Contacts\IManager;
  31. use OCP\IAddressBook;
  32. class ContactsManager implements IManager {
  33. /**
  34. * This function is used to search and find contacts within the users address books.
  35. * In case $pattern is empty all contacts will be returned.
  36. *
  37. * @param string $pattern which should match within the $searchProperties
  38. * @param array $searchProperties defines the properties within the query pattern should match
  39. * @param array $options = array() to define the search behavior
  40. * - 'types' boolean (since 15.0.0) If set to true, fields that come with a TYPE property will be an array
  41. * example: ['id' => 5, 'FN' => 'Thomas Tanghus', 'EMAIL' => ['type => 'HOME', 'value' => 'g@h.i']]
  42. * - 'escape_like_param' - If set to false wildcards _ and % are not escaped
  43. * - 'limit' - Set a numeric limit for the search results
  44. * - 'offset' - Set the offset for the limited search results
  45. * - 'enumeration' - (since 23.0.0) Whether user enumeration on system address book is allowed
  46. * - 'fullmatch' - (since 23.0.0) Whether matching on full detail in system address book is allowed
  47. * - 'strict_search' - (since 23.0.0) Whether the search pattern is full string or partial search
  48. * @psalm-param array{types?: bool, escape_like_param?: bool, limit?: int, offset?: int, enumeration?: bool, fullmatch?: bool, strict_search?: bool} $options
  49. * @return array an array of contacts which are arrays of key-value-pairs
  50. */
  51. public function search($pattern, $searchProperties = [], $options = []) {
  52. $this->loadAddressBooks();
  53. $result = [];
  54. foreach ($this->addressBooks as $addressBook) {
  55. $searchOptions = $options;
  56. $strictSearch = array_key_exists('strict_search', $options) && $options['strict_search'] === true;
  57. if ($addressBook->isSystemAddressBook()) {
  58. $enumeration = !\array_key_exists('enumeration', $options) || $options['enumeration'] !== false;
  59. $fullMatch = !\array_key_exists('fullmatch', $options) || $options['fullmatch'] !== false;
  60. if (!$enumeration && !$fullMatch) {
  61. // No access to system address book AND no full match allowed
  62. continue;
  63. }
  64. if ($strictSearch) {
  65. $searchOptions['wildcard'] = false;
  66. } else {
  67. $searchOptions['wildcard'] = $enumeration;
  68. }
  69. } else {
  70. $searchOptions['wildcard'] = !$strictSearch;
  71. }
  72. $r = $addressBook->search($pattern, $searchProperties, $searchOptions);
  73. $contacts = [];
  74. foreach ($r as $c) {
  75. $c['addressbook-key'] = $addressBook->getKey();
  76. $contacts[] = $c;
  77. }
  78. $result = array_merge($result, $contacts);
  79. }
  80. return $result;
  81. }
  82. /**
  83. * This function can be used to delete the contact identified by the given id
  84. *
  85. * @param int $id the unique identifier to a contact
  86. * @param string $address_book_key identifier of the address book in which the contact shall be deleted
  87. * @return bool successful or not
  88. */
  89. public function delete($id, $address_book_key) {
  90. $addressBook = $this->getAddressBook($address_book_key);
  91. if (!$addressBook) {
  92. return null;
  93. }
  94. if ($addressBook->getPermissions() & Constants::PERMISSION_DELETE) {
  95. return $addressBook->delete($id);
  96. }
  97. return null;
  98. }
  99. /**
  100. * This function is used to create a new contact if 'id' is not given or not present.
  101. * Otherwise the contact will be updated by replacing the entire data set.
  102. *
  103. * @param array $properties this array if key-value-pairs defines a contact
  104. * @param string $address_book_key identifier of the address book in which the contact shall be created or updated
  105. * @return array representing the contact just created or updated
  106. */
  107. public function createOrUpdate($properties, $address_book_key) {
  108. $addressBook = $this->getAddressBook($address_book_key);
  109. if (!$addressBook) {
  110. return null;
  111. }
  112. if ($addressBook->getPermissions() & Constants::PERMISSION_CREATE) {
  113. return $addressBook->createOrUpdate($properties);
  114. }
  115. return null;
  116. }
  117. /**
  118. * Check if contacts are available (e.g. contacts app enabled)
  119. *
  120. * @return bool true if enabled, false if not
  121. */
  122. public function isEnabled() {
  123. return !empty($this->addressBooks) || !empty($this->addressBookLoaders);
  124. }
  125. /**
  126. * @param IAddressBook $addressBook
  127. */
  128. public function registerAddressBook(IAddressBook $addressBook) {
  129. $this->addressBooks[$addressBook->getKey()] = $addressBook;
  130. }
  131. /**
  132. * @param IAddressBook $addressBook
  133. */
  134. public function unregisterAddressBook(IAddressBook $addressBook) {
  135. unset($this->addressBooks[$addressBook->getKey()]);
  136. }
  137. /**
  138. * Return a list of the user's addressbooks
  139. *
  140. * @return IAddressBook[]
  141. * @since 16.0.0
  142. */
  143. public function getUserAddressBooks(): array {
  144. $this->loadAddressBooks();
  145. return $this->addressBooks;
  146. }
  147. /**
  148. * removes all registered address book instances
  149. */
  150. public function clear() {
  151. $this->addressBooks = [];
  152. $this->addressBookLoaders = [];
  153. }
  154. /**
  155. * @var IAddressBook[] which holds all registered address books
  156. */
  157. private $addressBooks = [];
  158. /**
  159. * @var \Closure[] to call to load/register address books
  160. */
  161. private $addressBookLoaders = [];
  162. /**
  163. * In order to improve lazy loading a closure can be registered which will be called in case
  164. * address books are actually requested
  165. *
  166. * @param \Closure $callable
  167. */
  168. public function register(\Closure $callable) {
  169. $this->addressBookLoaders[] = $callable;
  170. }
  171. /**
  172. * Get (and load when needed) the address book for $key
  173. *
  174. * @param string $addressBookKey
  175. * @return IAddressBook
  176. */
  177. protected function getAddressBook($addressBookKey) {
  178. $this->loadAddressBooks();
  179. if (!array_key_exists($addressBookKey, $this->addressBooks)) {
  180. return null;
  181. }
  182. return $this->addressBooks[$addressBookKey];
  183. }
  184. /**
  185. * Load all address books registered with 'register'
  186. */
  187. protected function loadAddressBooks() {
  188. foreach ($this->addressBookLoaders as $callable) {
  189. $callable($this);
  190. }
  191. $this->addressBookLoaders = [];
  192. }
  193. }