permissions-check.rst 3.0 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788
  1. Permissions Check
  2. =================
  3. .. warning::
  4. As stated in the page, this method works **only** for granting **write** access to entities. You **cannot** use this method to retrieve or view entities for which the user does not have read access.
  5. Elgg provides a mechanism of overriding write permissions check through the :ref:`permissions_check plugin hook <guides/hooks-list#permission-hooks>` . This is useful for allowing plugin write to all accessible entities regardless of access settings. Entities that are hidden, however, will still be unavailable to the plugin.
  6. Hooking permissions_check
  7. -------------------------
  8. In your plugin, you must register the plugin hook for ``permissions_check``.
  9. .. code:: php
  10. elgg_register_plugin_hook_handler('permissions_check', 'all', 'myplugin_permissions_check');
  11. The override function
  12. ---------------------
  13. Now create the function that will be called by the permissions check hook. In this function we determine if the entity (in parameters) has write access. Since it is important to keep Elgg secure, write access should be given only after checking a variety of situations including page context, logged in user, etc.
  14. Note that this function can return 3 values: true if the entity has write access, false if the entity does not, and null if this plugin doesn't care and the security system should consult other plugins.
  15. .. code:: php
  16. function myplugin_permissions_check($hook_name, $entity_type, $return_value, $parameters) {
  17. $has_access = determine_access_somehow();
  18. if ($has_access === true) {
  19. return true;
  20. } else if ($has_access === false) {
  21. return false;
  22. }
  23. return null;
  24. }
  25. Full Example
  26. ------------
  27. This is a full example using the context to determine if the entity has write access.
  28. .. code:: php
  29. <?php
  30. function myaccess_init() {
  31. // Register cron hook
  32. if (!elgg_get_plugin_setting('period', 'myaccess')) {
  33. elgg_set_plugin_setting('period', 'fiveminute', 'myaccess');
  34. }
  35. // override permissions for the myaccess context
  36. elgg_register_plugin_hook_handler('permissions_check', 'all', 'myaccess_permissions_check');
  37. elgg_register_plugin_hook_handler('cron', elgg_get_plugin_setting('period', 'myaccess'), 'myaccess_cron');
  38. }
  39. /**
  40. * Hook for cron event.
  41. */
  42. function myaccess_cron($event, $object_type, $object) {
  43. elgg_push_context('myaccess_cron');
  44. // returns all entities regardless of access permissions.
  45. // will NOT return hidden entities.
  46. $entities = get_entities();
  47. elgg_pop_context();
  48. }
  49. /**
  50. * Overrides default permissions for the myaccess context
  51. */
  52. function myaccess_permissions_check($hook_name, $entity_type, $return_value, $parameters) {
  53. if (elgg_in_context('myaccess_cron')) {
  54. return true;
  55. }
  56. return null;
  57. }
  58. // Initialise plugin
  59. register_elgg_event_handler('init', 'system', 'myaccess_init');
  60. ?>