|
| 1 | +# Expression Assertions |
| 2 | + |
| 3 | +- Since 2.7.0 |
| 4 | + |
| 5 | +Many custom assertions are doing basic comparisons: |
| 6 | + |
| 7 | +- Equality of a role property to a value or property of the resource. |
| 8 | +- Other comparisons (`>`, `<`, `in_array`, etc.) of a role property to a value |
| 9 | + or values (potentially a property of the resource). |
| 10 | +- Regular expressions. |
| 11 | + |
| 12 | +While these can be easily accommodated by the `CallbackAssertion`, such |
| 13 | +assertions have one notable problem: they cannot be easily serialized. |
| 14 | + |
| 15 | +To facilitate such assertions, we now provide |
| 16 | +`Zend\Permissions\Acl\Assertion\ExpressionAssertion`. This class provides two |
| 17 | +static factory methods for creating an instance, each expecting the following: |
| 18 | + |
| 19 | +- The left operand |
| 20 | +- An operator |
| 21 | +- The right operand |
| 22 | + |
| 23 | +When the assertion is executed, it uses the operator to determine how to compare |
| 24 | +the two operands, and thus answer the assertion. |
| 25 | + |
| 26 | +## Operands |
| 27 | + |
| 28 | +The operands can be any PHP value. |
| 29 | + |
| 30 | +Additionally, they can be an associative array containing the key |
| 31 | +`ExpressionAssertion::OPERAND_CONTEXT_PROPERTY` (`__context`), with a string |
| 32 | +value. |
| 33 | + |
| 34 | +That value can be one of the following: |
| 35 | + |
| 36 | +- A string matching the values "acl", "privilege", "role", or "resource", with |
| 37 | + the latter two being most common. When one of these is provided, the |
| 38 | + corresponding argument to the `assert()` method will be used. |
| 39 | + |
| 40 | +- A dot-separated string with the first segment being one of the above values, |
| 41 | + and the second being a property or field of that object. The |
| 42 | + `ExpressionAssertion` will test for: |
| 43 | + |
| 44 | + - a method matching `get<field>()` |
| 45 | + - a method matching `is<field>()` |
| 46 | + - a public property named `<field>` |
| 47 | + |
| 48 | + in that specific order. In the first two cases, `<field>` will be normalized |
| 49 | + to WordCase when creating the method name to test. |
| 50 | + |
| 51 | +## Operators |
| 52 | + |
| 53 | +`ExpressionAssertion` supports the following operators: |
| 54 | + |
| 55 | +```php |
| 56 | + const OPERATOR_EQ = '='; |
| 57 | + const OPERATOR_NEQ = '!='; |
| 58 | + const OPERATOR_LT = '<'; |
| 59 | + const OPERATOR_LTE = '<='; |
| 60 | + const OPERATOR_GT = '>'; |
| 61 | + const OPERATOR_GTE = '>='; |
| 62 | + const OPERATOR_IN = 'in'; |
| 63 | + const OPERATOR_NIN = '!in'; |
| 64 | + const OPERATOR_REGEX = 'regex'; |
| 65 | + const OPERATOR_NREGEX = '!regex'; |
| 66 | + const OPERATOR_SAME = '==='; |
| 67 | + const OPERATOR_NSAME = '!=='; |
| 68 | +``` |
| 69 | + |
| 70 | +In most cases, these will operate using the operators as listed above, with the |
| 71 | +following exceptions: |
| 72 | + |
| 73 | +- `OPERATOR_EQ` will use `==` as the comparison operator; `OPERATOR_NEQ` will |
| 74 | + likewise use `!=`. |
| 75 | +- `OPERATOR_IN` and `OPERATOR_NIN` use `in_array()` (with the latter negating |
| 76 | + the result), both doing strict comparisons. The right hand operand is expected |
| 77 | + to be the array in which to look for results, and the left hand operand is |
| 78 | + expected to be the needle to look for. |
| 79 | +- `OPERATOR_REGEX` and `OPERATOR_NREGEX` will perform a `preg_match()` |
| 80 | + operation, using the right hand operand as the regular expression, and the |
| 81 | + left hand operand as the value to compare. |
| 82 | + |
| 83 | +## Constructors |
| 84 | + |
| 85 | +The constructor of `ExpressionAssertion` is private. Instead, you will use one |
| 86 | +of two static methods in order to create instances: |
| 87 | + |
| 88 | +- `fromProperties($left, $operator, $right)` |
| 89 | +- `fromArray(array $expression)` (expects keys for "left", "operator", and "right") |
| 90 | + |
| 91 | +When creating expressions manually, the first is generally the best choice. When |
| 92 | +storing expressions in configuration or a database, the latter is useful, as you |
| 93 | +can pass a row of data at a time to the method to get expression instances. |
| 94 | + |
| 95 | +## Examples |
| 96 | + |
| 97 | +First, we'll define both a role and a resource: |
| 98 | + |
| 99 | +```php |
| 100 | +namespace Blog\Entity; |
| 101 | + |
| 102 | +use Zend\Permissions\Acl\Resource\ResourceInterface; |
| 103 | +use Zend\Permissions\Acl\Role\RoleInterface; |
| 104 | + |
| 105 | +class BlogPost implements ResourceInterface |
| 106 | +{ |
| 107 | + public $title; |
| 108 | + |
| 109 | + public $shortDescription; |
| 110 | + |
| 111 | + public $content; |
| 112 | + |
| 113 | + public $author; |
| 114 | + |
| 115 | + public function __construct(array $data = []) |
| 116 | + { |
| 117 | + foreach ($data as $property => $value) { |
| 118 | + $this->$property = $value; |
| 119 | + } |
| 120 | + } |
| 121 | + |
| 122 | + public function getResourceId() |
| 123 | + { |
| 124 | + return 'blogPost'; |
| 125 | + } |
| 126 | + |
| 127 | + public function getShortDescription() |
| 128 | + { |
| 129 | + return $this->shortDescription; |
| 130 | + } |
| 131 | + |
| 132 | + public function getAuthorName() |
| 133 | + { |
| 134 | + return $this->author ? $this->author->username : ''; |
| 135 | + } |
| 136 | +} |
| 137 | + |
| 138 | +class User implements RoleInterface |
| 139 | +{ |
| 140 | + public $username; |
| 141 | + |
| 142 | + public $role = 'guest'; |
| 143 | + |
| 144 | + public $age; |
| 145 | + |
| 146 | + public function __construct(array $data = []) |
| 147 | + { |
| 148 | + foreach ($data as $property => $value) { |
| 149 | + $this->$property = $value; |
| 150 | + } |
| 151 | + } |
| 152 | + |
| 153 | + public function getRoleId() |
| 154 | + { |
| 155 | + return $this->role; |
| 156 | + } |
| 157 | + |
| 158 | + public function isAdult() |
| 159 | + { |
| 160 | + return $this->age >= 18; |
| 161 | + } |
| 162 | +} |
| 163 | +``` |
| 164 | + |
| 165 | +Next, let's define some assertions. |
| 166 | + |
| 167 | +```php |
| 168 | +use Zend\Permissions\Acl\Assertion\ExpressionAssertion; |
| 169 | + |
| 170 | +// Username of role must be "test": |
| 171 | +// Will access $username property on the role instance. |
| 172 | +$isTestUser = ExpressionAssertion::fromProperties( |
| 173 | + [ExpressionAssertion::OPERAND_CONTEXT_PROPERTY => 'role.username'], |
| 174 | + '===', |
| 175 | + 'test' |
| 176 | +); |
| 177 | + |
| 178 | + |
| 179 | +// Role must be at least 18 years old: |
| 180 | +// Will execute `isAdult()` on the role instance. |
| 181 | +$isOfLegalAge = ExpressionAssertion::fromProperties( |
| 182 | + [ExpressionAssertion::OPERAND_CONTEXT_PROPERTY => 'role.adult'], |
| 183 | + '===', |
| 184 | + true |
| 185 | +); |
| 186 | + |
| 187 | +// Must have edited text: |
| 188 | +// Will do a regex comparison on the shortDescription of the blog post |
| 189 | +// to ensure we do not have filler text. |
| 190 | +$isEditedDescription = ExpressionAssertion::fromArray([ |
| 191 | + 'left' => [ExpressionAssertion::OPERAND_CONTEXT_PROPERTY => 'resource.shortDescription'], |
| 192 | + 'operator' => '!regex', |
| 193 | + 'right' => '/lorem ipsum/i', |
| 194 | +]); |
| 195 | +``` |
0 commit comments