expressions.rst 5.6KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109
  1. Expression-based Authorization Language
  2. #######################################
  3. Introduction
  4. ------------
  5. The expression language is a very powerful alternative to the simple attributes
  6. of the security voting system. They allow to perform complex access decision
  7. checks, and because they are compiled down to raw PHP, they are much faster than
  8. the built-in voters. Also they are lazy-loading by nature, so you will also
  9. save some resources for example by not having to initialize the entire ACL system
  10. on each request.
  11. Usage
  12. -----
  13. Programmatic Usage
  14. ~~~~~~~~~~~~~~~~~~
  15. You can execute expressions programmatically by using the ``isGranted`` method
  16. of the SecurityContext. Some examples:
  17. .. code-block :: php
  18. <?php
  19. use JMS\SecurityExtraBundle\Security\Authorization\Expression\Expression;
  20. $securityContext->isGranted(array(new Expression('hasRole("A")')));
  21. $securityContext->isGranted(array(new Expression('hasRole("A") or (hasRole("B") and hasRole("C"))')));
  22. $securityContext->isGranted(array(new Expression('hasPermission(object, "VIEW")'), $object));
  23. $securityContext->isGranted(array(new Expression('token.getUsername() == "Johannes"')));
  24. Twig Usage
  25. ~~~~~~~~~~
  26. You can check expressions from Twig templates using the ``is_expr_granted``
  27. function. Some examples:
  28. .. code-block :: jinja
  29. is_expr_granted("hasRole('FOO')")
  30. is_expr_granted("hasPermission(object, 'VIEW')", object)
  31. Usage in Access Control
  32. ~~~~~~~~~~~~~~~~~~~~~~~
  33. You can also use expressions in the ``access_control``:
  34. .. configuration-block ::
  35. .. code-block :: yaml
  36. security:
  37. access_control:
  38. - { path: ^/foo, access: "hasRole('FOO') and hasRole('BAR')" }
  39. .. code-block :: xml
  40. <security>
  41. <rule path="^/foo" access="hasRole('FOO') and hasRole('BAR')" />
  42. </security>
  43. Annotation-based Usage
  44. ~~~~~~~~~~~~~~~~~~~~~~
  45. See @PreAuthorize in the annotation reference. Please also remember to enable expressions
  46. in your config, otherwise you will get an exception upon checking access.
  47. Reference
  48. ---------
  49. +-----------------------------------+--------------------------------------------+
  50. | Expression | Description |
  51. +===================================+============================================+
  52. | hasRole('ROLE') | Checks whether the token has a certain |
  53. | | role. |
  54. +-----------------------------------+--------------------------------------------+
  55. | hasAnyRole('ROLE1', 'ROLE2', ...) | Checks whether the token has any of the |
  56. | | given roles. |
  57. +-----------------------------------+--------------------------------------------+
  58. | isAnonymous() | Checks whether the token is anonymous. |
  59. +-----------------------------------+--------------------------------------------+
  60. | isRememberMe() | Checks whether the token is remember me. |
  61. +-----------------------------------+--------------------------------------------+
  62. | isFullyAuthenticated() | Checks whether the token is fully |
  63. | | authenticated. |
  64. +-----------------------------------+--------------------------------------------+
  65. | isAuthenticated() | Checks whether the token is not anonymous. |
  66. +-----------------------------------+--------------------------------------------+
  67. | hasPermission(*var*, 'PERMISSION')| Checks whether the token has the given |
  68. | | permission for the given object (requires |
  69. | | the ACL system). |
  70. +-----------------------------------+--------------------------------------------+
  71. | token | Variable that refers to the token |
  72. | | which is currently in the security context.|
  73. +-----------------------------------+--------------------------------------------+
  74. | user | Variable that refers to the user |
  75. | | which is currently in the security context.|
  76. +-----------------------------------+--------------------------------------------+
  77. | object | Variable that refers to the object for |
  78. | | which access is being requested. |
  79. +-----------------------------------+--------------------------------------------+
  80. | #*paramName* | Any identifier prefixed with # refers to |
  81. | | a parameter of the same name that is passed|
  82. | | to the method where the expression is used.|
  83. +-----------------------------------+--------------------------------------------+
  84. | and / && | Binary "and" operator |
  85. +-----------------------------------+--------------------------------------------+
  86. | or / || | Binary "or" operator |
  87. +-----------------------------------+--------------------------------------------+
  88. | == | Binary "is equal" operator |
  89. +-----------------------------------+--------------------------------------------+
  90. | not / ! | Negation operator |
  91. +-----------------------------------+--------------------------------------------+