PageRenderTime 128ms CodeModel.GetById 21ms RepoModel.GetById 1ms app.codeStats 0ms

/engine/lib/access.php

https://github.com/blacktooth/Elgg
PHP | 280 lines | 67 code | 19 blank | 194 comment | 5 complexity | 39a06e66368418845e72aa5298078d23 MD5 | raw file
Possible License(s): GPL-2.0, MIT, LGPL-2.1, BSD-3-Clause
  1. <?php
  2. /**
  3. * Functions for Elgg's access system for entities, metadata, and annotations.
  4. *
  5. * Access is generally saved in the database as access_id. This corresponds to
  6. * one of the ACCESS_* constants defined in {@link elgglib.php} or the ID of an
  7. * access collection.
  8. */
  9. /**
  10. * Get current ignore access setting.
  11. *
  12. * @return bool
  13. * @since 1.7.0
  14. */
  15. function elgg_get_ignore_access(): bool {
  16. return _elgg_services()->session->getIgnoreAccess();
  17. }
  18. /**
  19. * Returns an array of access IDs a user is permitted to see.
  20. *
  21. * Can be overridden with the 'access:collections:read', 'user' plugin hook.
  22. * @warning A callback for that plugin hook needs to either not retrieve data
  23. * from the database that would use the access system (triggering the plugin again)
  24. * or ignore the second call. Otherwise, an infinite loop will be created.
  25. *
  26. * This returns a list of all the collection ids a user owns or belongs
  27. * to plus public and logged in access levels. If the user is an admin, it includes
  28. * the private access level.
  29. *
  30. * @see get_write_access_array() for the access levels that a user can write to.
  31. *
  32. * @param int $user_guid User ID; defaults to currently logged in user
  33. *
  34. * @return array An array of access collections ids
  35. */
  36. function get_access_array(int $user_guid = 0): array {
  37. return _elgg_services()->accessCollections->getAccessArray($user_guid);
  38. }
  39. /**
  40. * Gets the default access permission.
  41. *
  42. * This returns the default access level for the site or optionally of the user.
  43. * If want you to change the default access based on group of other information,
  44. * use the 'default', 'access' plugin hook.
  45. *
  46. * @param ElggUser $user The user for whom we're getting default access. Defaults to logged in user.
  47. * @param array $input_params Parameters passed into an input/access view
  48. *
  49. * @return int default access id (see ACCESS defines in elgglib.php)
  50. */
  51. function get_default_access(ElggUser $user = null, array $input_params = []): int {
  52. // site default access
  53. $default_access = _elgg_services()->config->default_access;
  54. // user default access if enabled
  55. if (_elgg_services()->config->allow_user_default_access) {
  56. $user = $user ? $user : _elgg_services()->session->getLoggedInUser();
  57. if ($user) {
  58. $user_access = $user->getPrivateSetting('elgg_default_access');
  59. if ($user_access !== null) {
  60. $default_access = $user_access;
  61. }
  62. }
  63. }
  64. $params = [
  65. 'user' => $user,
  66. 'default_access' => $default_access,
  67. 'input_params' => $input_params,
  68. ];
  69. return _elgg_services()->hooks->trigger('default', 'access', $params, $default_access);
  70. }
  71. /**
  72. * Can a user access an entity.
  73. *
  74. * @warning If a logged in user doesn't have access to an entity, the
  75. * core engine will not load that entity.
  76. *
  77. * @tip This is mostly useful for checking if a user other than the logged in
  78. * user has access to an entity that is currently loaded.
  79. *
  80. * @todo This function would be much more useful if we could pass the guid of the
  81. * entity to test access for. We need to be able to tell whether the entity exists
  82. * and whether the user has access to the entity.
  83. *
  84. * @param \ElggEntity $entity The entity to check access for.
  85. * @param \ElggUser $user Optionally user to check access for. Defaults to logged in user (which is a useless default).
  86. *
  87. * @return bool
  88. */
  89. function has_access_to_entity(\ElggEntity $entity, \ElggUser $user = null): bool {
  90. return _elgg_services()->accessCollections->hasAccessToEntity($entity, $user);
  91. }
  92. /**
  93. * Returns an array of access permissions that the user is allowed to save content with.
  94. * Permissions returned are of the form (id => 'name').
  95. *
  96. * Example return value in English:
  97. * array(
  98. * 0 => 'Private',
  99. * -2 => 'Friends',
  100. * 1 => 'Logged in users',
  101. * 2 => 'Public',
  102. * 34 => 'My favorite friends',
  103. * );
  104. *
  105. * Plugin hook of 'access:collections:write', 'user'
  106. *
  107. * @warning this only returns access collections that the user owns plus the
  108. * standard access levels. It does not return access collections that the user
  109. * belongs to such as the access collection for a group.
  110. *
  111. * @param int $user_guid The user's GUID.
  112. * @param int $ignored Ignored parameter
  113. * @param bool $flush If this is set to true, this will ignore a cached access array
  114. * @param array $input_params Some parameters passed into an input/access view
  115. *
  116. * @return array List of access permissions
  117. */
  118. function get_write_access_array(int $user_guid = 0, $ignored = 0, bool $flush = false, array $input_params = []): array {
  119. return _elgg_services()->accessCollections->getWriteAccessArray($user_guid, $flush, $input_params);
  120. }
  121. /**
  122. * Can the user change this access collection?
  123. *
  124. * Use the plugin hook of 'access:collections:write', 'user' to change this.
  125. * @see get_write_access_array() for details on the hook.
  126. *
  127. * Respects access control disabling for admin users and {@link elgg_call()}
  128. *
  129. * @see get_write_access_array()
  130. *
  131. * @param int $collection_id The collection id
  132. * @param mixed $user_guid The user GUID to check for. Defaults to logged in user.
  133. * @return bool
  134. */
  135. function can_edit_access_collection(int $collection_id, int $user_guid = null): bool {
  136. return _elgg_services()->accessCollections->canEdit($collection_id, $user_guid);
  137. }
  138. /**
  139. * Creates a new access collection.
  140. *
  141. * Access colletions allow plugins and users to create granular access
  142. * for entities.
  143. *
  144. * Triggers plugin hook 'access:collections:addcollection', 'collection'
  145. *
  146. * @note Internal: Access collections are stored in the access_collections table.
  147. * Memberships to collections are in access_collections_membership.
  148. *
  149. * @param string $name The name of the collection.
  150. * @param int $owner_guid The GUID of the owner (default: currently logged in user).
  151. * @param string $subtype The subtype indicates the usage of the acl
  152. *
  153. * @return int|false The collection ID if successful and false on failure.
  154. * @see delete_access_collection()
  155. */
  156. function create_access_collection(string $name, int $owner_guid = 0, $subtype = null) {
  157. return _elgg_services()->accessCollections->create($name, $owner_guid, $subtype);
  158. }
  159. /**
  160. * Deletes a specified access collection and its membership.
  161. *
  162. * @param int $collection_id The collection ID
  163. *
  164. * @return bool
  165. * @see create_access_collection()
  166. */
  167. function delete_access_collection(int $collection_id): bool {
  168. return _elgg_services()->accessCollections->delete($collection_id);
  169. }
  170. /**
  171. * Get a specified access collection
  172. *
  173. * @note This doesn't return the members of an access collection,
  174. * just the database row of the actual collection.
  175. *
  176. * @see get_members_of_access_collection()
  177. *
  178. * @param int $collection_id The collection ID
  179. *
  180. * @return ElggAccessCollection|false
  181. */
  182. function get_access_collection(int $collection_id) {
  183. return _elgg_services()->accessCollections->get($collection_id);
  184. }
  185. /**
  186. * Adds a user to an access collection.
  187. *
  188. * Triggers the 'access:collections:add_user', 'collection' plugin hook.
  189. *
  190. * @param int $user_guid The GUID of the user to add
  191. * @param int $collection_id The ID of the collection to add them to
  192. *
  193. * @return bool
  194. */
  195. function add_user_to_access_collection(int $user_guid, int $collection_id): bool {
  196. return _elgg_services()->accessCollections->addUser($user_guid, $collection_id);
  197. }
  198. /**
  199. * Removes a user from an access collection.
  200. *
  201. * Triggers the 'access:collections:remove_user', 'collection' plugin hook.
  202. *
  203. * @param int $user_guid The user GUID
  204. * @param int $collection_id The access collection ID
  205. *
  206. * @return bool
  207. */
  208. function remove_user_from_access_collection(int $user_guid, int $collection_id): bool {
  209. return _elgg_services()->accessCollections->removeUser($user_guid, $collection_id);
  210. }
  211. /**
  212. * Returns access collections
  213. *
  214. * @param array $options array of options to get access collections by
  215. *
  216. * @return \ElggAccessCollection[]
  217. */
  218. function elgg_get_access_collections(array $options = []) {
  219. return _elgg_services()->accessCollections->getEntityCollections($options);
  220. }
  221. /**
  222. * Get all of members of an access collection
  223. *
  224. * @param int $collection_id The collection's ID
  225. * @param bool $guids_only If set to true, will only return the members' GUIDs (default: false)
  226. * @param array $options ege* options
  227. *
  228. * @return \ElggData[]|int|int[]|mixed guids or entities if successful, false if not
  229. */
  230. function get_members_of_access_collection(int $collection_id, bool $guids_only = false, array $options = []) {
  231. if (!isset($options['limit'])) {
  232. $options['limit'] = false;
  233. }
  234. if (!$guids_only) {
  235. return _elgg_services()->accessCollections->getMembers($collection_id, $options);
  236. }
  237. $options['callback'] = function($row) {
  238. return (int) $row->guid;
  239. };
  240. return _elgg_services()->accessCollections->getMembers($collection_id, $options);
  241. }
  242. /**
  243. * Return the name of an ACCESS_* constant or an access collection,
  244. * but only if the logged in user has write access to it.
  245. * Write access requirement prevents us from exposing names of access collections
  246. * that current user has been added to by other members and may contain
  247. * sensitive classification of the current user (e.g. close friends vs acquaintances).
  248. *
  249. * Returns a string in the language of the user for global access levels, e.g.'Public, 'Friends', 'Logged in', 'Public';
  250. * or a name of the owned access collection, e.g. 'My work colleagues';
  251. * or a name of the group or other access collection, e.g. 'Group: Elgg technical support';
  252. * or 'Limited' if the user access is restricted to read-only, e.g. a friends collection the user was added to
  253. *
  254. * @param int $entity_access_id The entity's access id
  255. *
  256. * @return string
  257. * @since 1.7.0
  258. */
  259. function get_readable_access_level(int $entity_access_id): string {
  260. return _elgg_services()->accessCollections->getReadableAccessLevel($entity_access_id);
  261. }