annotate core/lib/Drupal/Core/Access/AccessResultInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 4c8ae668cc8c
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Core\Access;
Chris@0 4
Chris@0 5 /**
Chris@0 6 * Interface for access result value objects.
Chris@0 7 *
Chris@0 8 * IMPORTANT NOTE: You have to call isAllowed() when you want to know whether
Chris@0 9 * someone has access. Just using
Chris@0 10 * @code
Chris@0 11 * if ($access_result) {
Chris@0 12 * // The user has access!
Chris@0 13 * }
Chris@0 14 * else {
Chris@0 15 * // The user doesn't have access!
Chris@0 16 * }
Chris@0 17 * @endcode
Chris@0 18 * would never enter the else-statement and hence introduce a critical security
Chris@0 19 * issue.
Chris@0 20 */
Chris@0 21 interface AccessResultInterface {
Chris@0 22
Chris@0 23 /**
Chris@0 24 * Checks whether this access result indicates access is explicitly allowed.
Chris@0 25 *
Chris@0 26 * @return bool
Chris@0 27 * When TRUE then isForbidden() and isNeutral() are FALSE.
Chris@0 28 */
Chris@0 29 public function isAllowed();
Chris@0 30
Chris@0 31 /**
Chris@0 32 * Checks whether this access result indicates access is explicitly forbidden.
Chris@0 33 *
Chris@0 34 * This is a kill switch — both orIf() and andIf() will result in
Chris@0 35 * isForbidden() if either results are isForbidden().
Chris@0 36 *
Chris@0 37 * @return bool
Chris@0 38 * When TRUE then isAllowed() and isNeutral() are FALSE.
Chris@0 39 */
Chris@0 40 public function isForbidden();
Chris@0 41
Chris@0 42 /**
Chris@0 43 * Checks whether this access result indicates access is not yet determined.
Chris@0 44 *
Chris@0 45 * @return bool
Chris@0 46 * When TRUE then isAllowed() and isForbidden() are FALSE.
Chris@0 47 */
Chris@0 48 public function isNeutral();
Chris@0 49
Chris@0 50 /**
Chris@0 51 * Combine this access result with another using OR.
Chris@0 52 *
Chris@0 53 * When OR-ing two access results, the result is:
Chris@0 54 * - isForbidden() in either ⇒ isForbidden()
Chris@0 55 * - otherwise if isAllowed() in either ⇒ isAllowed()
Chris@0 56 * - otherwise both must be isNeutral() ⇒ isNeutral()
Chris@0 57 *
Chris@0 58 * Truth table:
Chris@0 59 * @code
Chris@0 60 * |A N F
Chris@0 61 * --+-----
Chris@0 62 * A |A A F
Chris@0 63 * N |A N F
Chris@0 64 * F |F F F
Chris@0 65 * @endcode
Chris@0 66 *
Chris@0 67 * @param \Drupal\Core\Access\AccessResultInterface $other
Chris@0 68 * The other access result to OR this one with.
Chris@0 69 *
Chris@0 70 * @return static
Chris@0 71 */
Chris@0 72 public function orIf(AccessResultInterface $other);
Chris@0 73
Chris@0 74 /**
Chris@0 75 * Combine this access result with another using AND.
Chris@0 76 *
Chris@0 77 * When AND-ing two access results, the result is:
Chris@0 78 * - isForbidden() in either ⇒ isForbidden()
Chris@0 79 * - otherwise, if isAllowed() in both ⇒ isAllowed()
Chris@0 80 * - otherwise, one of them is isNeutral() ⇒ isNeutral()
Chris@0 81 *
Chris@0 82 * Truth table:
Chris@0 83 * @code
Chris@0 84 * |A N F
Chris@0 85 * --+-----
Chris@0 86 * A |A N F
Chris@0 87 * N |N N F
Chris@0 88 * F |F F F
Chris@0 89 * @endcode
Chris@0 90 *
Chris@0 91 * @param \Drupal\Core\Access\AccessResultInterface $other
Chris@0 92 * The other access result to AND this one with.
Chris@0 93 *
Chris@0 94 * @return static
Chris@0 95 */
Chris@0 96 public function andIf(AccessResultInterface $other);
Chris@0 97
Chris@0 98 }