1: <?php
2: /**
3: * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
4: * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
5: *
6: * Licensed under The MIT License
7: * For full copyright and license information, please see the LICENSE.txt
8: * Redistributions of files must retain the above copyright notice.
9: *
10: * @copyright Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
11: * @link https://cakephp.org CakePHP(tm) Project
12: * @since 3.0.7
13: * @license https://opensource.org/licenses/mit-license.php MIT License
14: */
15: namespace Cake\Datasource;
16:
17: use InvalidArgumentException;
18:
19: /**
20: * Contains logic for storing and checking rules on entities
21: *
22: * RulesCheckers are used by Table classes to ensure that the
23: * current entity state satisfies the application logic and business rules.
24: *
25: * RulesCheckers afford different rules to be applied in the create and update
26: * scenario.
27: *
28: * ### Adding rules
29: *
30: * Rules must be callable objects that return true/false depending on whether or
31: * not the rule has been satisfied. You can use RulesChecker::add(), RulesChecker::addCreate(),
32: * RulesChecker::addUpdate() and RulesChecker::addDelete to add rules to a checker.
33: *
34: * ### Running checks
35: *
36: * Generally a Table object will invoke the rules objects, but you can manually
37: * invoke the checks by calling RulesChecker::checkCreate(), RulesChecker::checkUpdate() or
38: * RulesChecker::checkDelete().
39: */
40: class RulesChecker
41: {
42: /**
43: * Indicates that the checking rules to apply are those used for creating entities
44: *
45: * @var string
46: */
47: const CREATE = 'create';
48:
49: /**
50: * Indicates that the checking rules to apply are those used for updating entities
51: *
52: * @var string
53: */
54: const UPDATE = 'update';
55:
56: /**
57: * Indicates that the checking rules to apply are those used for deleting entities
58: *
59: * @var string
60: */
61: const DELETE = 'delete';
62:
63: /**
64: * The list of rules to be checked on both create and update operations
65: *
66: * @var callable[]
67: */
68: protected $_rules = [];
69:
70: /**
71: * The list of rules to check during create operations
72: *
73: * @var callable[]
74: */
75: protected $_createRules = [];
76:
77: /**
78: * The list of rules to check during update operations
79: *
80: * @var callable[]
81: */
82: protected $_updateRules = [];
83:
84: /**
85: * The list of rules to check during delete operations
86: *
87: * @var callable[]
88: */
89: protected $_deleteRules = [];
90:
91: /**
92: * List of options to pass to every callable rule
93: *
94: * @var array
95: */
96: protected $_options = [];
97:
98: /**
99: * Whether or not to use I18n functions for translating default error messages
100: *
101: * @var bool
102: */
103: protected $_useI18n = false;
104:
105: /**
106: * Constructor. Takes the options to be passed to all rules.
107: *
108: * @param array $options The options to pass to every rule
109: */
110: public function __construct(array $options = [])
111: {
112: $this->_options = $options;
113: $this->_useI18n = function_exists('__d');
114: }
115:
116: /**
117: * Adds a rule that will be applied to the entity both on create and update
118: * operations.
119: *
120: * ### Options
121: *
122: * The options array accept the following special keys:
123: *
124: * - `errorField`: The name of the entity field that will be marked as invalid
125: * if the rule does not pass.
126: * - `message`: The error message to set to `errorField` if the rule does not pass.
127: *
128: * @param callable $rule A callable function or object that will return whether
129: * the entity is valid or not.
130: * @param string|null $name The alias for a rule.
131: * @param array $options List of extra options to pass to the rule callable as
132: * second argument.
133: * @return $this
134: */
135: public function add(callable $rule, $name = null, array $options = [])
136: {
137: $this->_rules[] = $this->_addError($rule, $name, $options);
138:
139: return $this;
140: }
141:
142: /**
143: * Adds a rule that will be applied to the entity on create operations.
144: *
145: * ### Options
146: *
147: * The options array accept the following special keys:
148: *
149: * - `errorField`: The name of the entity field that will be marked as invalid
150: * if the rule does not pass.
151: * - `message`: The error message to set to `errorField` if the rule does not pass.
152: *
153: * @param callable $rule A callable function or object that will return whether
154: * the entity is valid or not.
155: * @param string|null $name The alias for a rule.
156: * @param array $options List of extra options to pass to the rule callable as
157: * second argument.
158: * @return $this
159: */
160: public function addCreate(callable $rule, $name = null, array $options = [])
161: {
162: $this->_createRules[] = $this->_addError($rule, $name, $options);
163:
164: return $this;
165: }
166:
167: /**
168: * Adds a rule that will be applied to the entity on update operations.
169: *
170: * ### Options
171: *
172: * The options array accept the following special keys:
173: *
174: * - `errorField`: The name of the entity field that will be marked as invalid
175: * if the rule does not pass.
176: * - `message`: The error message to set to `errorField` if the rule does not pass.
177: *
178: * @param callable $rule A callable function or object that will return whether
179: * the entity is valid or not.
180: * @param string|null $name The alias for a rule.
181: * @param array $options List of extra options to pass to the rule callable as
182: * second argument.
183: * @return $this
184: */
185: public function addUpdate(callable $rule, $name = null, array $options = [])
186: {
187: $this->_updateRules[] = $this->_addError($rule, $name, $options);
188:
189: return $this;
190: }
191:
192: /**
193: * Adds a rule that will be applied to the entity on delete operations.
194: *
195: * ### Options
196: *
197: * The options array accept the following special keys:
198: *
199: * - `errorField`: The name of the entity field that will be marked as invalid
200: * if the rule does not pass.
201: * - `message`: The error message to set to `errorField` if the rule does not pass.
202: *
203: * @param callable $rule A callable function or object that will return whether
204: * the entity is valid or not.
205: * @param string|null $name The alias for a rule.
206: * @param array $options List of extra options to pass to the rule callable as
207: * second argument.
208: * @return $this
209: */
210: public function addDelete(callable $rule, $name = null, array $options = [])
211: {
212: $this->_deleteRules[] = $this->_addError($rule, $name, $options);
213:
214: return $this;
215: }
216:
217: /**
218: * Runs each of the rules by passing the provided entity and returns true if all
219: * of them pass. The rules to be applied are depended on the $mode parameter which
220: * can only be RulesChecker::CREATE, RulesChecker::UPDATE or RulesChecker::DELETE
221: *
222: * @param \Cake\Datasource\EntityInterface $entity The entity to check for validity.
223: * @param string $mode Either 'create, 'update' or 'delete'.
224: * @param array $options Extra options to pass to checker functions.
225: * @return bool
226: * @throws \InvalidArgumentException if an invalid mode is passed.
227: */
228: public function check(EntityInterface $entity, $mode, array $options = [])
229: {
230: if ($mode === self::CREATE) {
231: return $this->checkCreate($entity, $options);
232: }
233:
234: if ($mode === self::UPDATE) {
235: return $this->checkUpdate($entity, $options);
236: }
237:
238: if ($mode === self::DELETE) {
239: return $this->checkDelete($entity, $options);
240: }
241:
242: throw new InvalidArgumentException('Wrong checking mode: ' . $mode);
243: }
244:
245: /**
246: * Runs each of the rules by passing the provided entity and returns true if all
247: * of them pass. The rules selected will be only those specified to be run on 'create'
248: *
249: * @param \Cake\Datasource\EntityInterface $entity The entity to check for validity.
250: * @param array $options Extra options to pass to checker functions.
251: * @return bool
252: */
253: public function checkCreate(EntityInterface $entity, array $options = [])
254: {
255: return $this->_checkRules($entity, $options, array_merge($this->_rules, $this->_createRules));
256: }
257:
258: /**
259: * Runs each of the rules by passing the provided entity and returns true if all
260: * of them pass. The rules selected will be only those specified to be run on 'update'
261: *
262: * @param \Cake\Datasource\EntityInterface $entity The entity to check for validity.
263: * @param array $options Extra options to pass to checker functions.
264: * @return bool
265: */
266: public function checkUpdate(EntityInterface $entity, array $options = [])
267: {
268: return $this->_checkRules($entity, $options, array_merge($this->_rules, $this->_updateRules));
269: }
270:
271: /**
272: * Runs each of the rules by passing the provided entity and returns true if all
273: * of them pass. The rules selected will be only those specified to be run on 'delete'
274: *
275: * @param \Cake\Datasource\EntityInterface $entity The entity to check for validity.
276: * @param array $options Extra options to pass to checker functions.
277: * @return bool
278: */
279: public function checkDelete(EntityInterface $entity, array $options = [])
280: {
281: return $this->_checkRules($entity, $options, $this->_deleteRules);
282: }
283:
284: /**
285: * Used by top level functions checkDelete, checkCreate and checkUpdate, this function
286: * iterates an array containing the rules to be checked and checks them all.
287: *
288: * @param \Cake\Datasource\EntityInterface $entity The entity to check for validity.
289: * @param array $options Extra options to pass to checker functions.
290: * @param array $rules The list of rules that must be checked.
291: * @return bool
292: */
293: protected function _checkRules(EntityInterface $entity, array $options = [], array $rules = [])
294: {
295: $success = true;
296: $options += $this->_options;
297: foreach ($rules as $rule) {
298: $success = $rule($entity, $options) && $success;
299: }
300:
301: return $success;
302: }
303:
304: /**
305: * Utility method for decorating any callable so that if it returns false, the correct
306: * property in the entity is marked as invalid.
307: *
308: * @param callable $rule The rule to decorate
309: * @param string $name The alias for a rule.
310: * @param array $options The options containing the error message and field.
311: * @return callable
312: */
313: protected function _addError($rule, $name, $options)
314: {
315: if (is_array($name)) {
316: $options = $name;
317: $name = null;
318: }
319:
320: if (!($rule instanceof RuleInvoker)) {
321: $rule = new RuleInvoker($rule, $name, $options);
322: } else {
323: $rule->setOptions($options)->setName($name);
324: }
325:
326: return $rule;
327: }
328: }
329: