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 ArrayObject;
 18: use Cake\Event\EventDispatcherInterface;
 19: 
 20: /**
 21:  * A trait that allows a class to build and apply application.
 22:  * rules.
 23:  *
 24:  * If the implementing class also implements EventAwareTrait, then
 25:  * events will be emitted when rules are checked.
 26:  *
 27:  * The implementing class is expected to define the `RULES_CLASS` constant
 28:  * if they need to customize which class is used for rules objects.
 29:  */
 30: trait RulesAwareTrait
 31: {
 32: 
 33:     /**
 34:      * The domain rules to be applied to entities saved by this table
 35:      *
 36:      * @var \Cake\Datasource\RulesChecker
 37:      */
 38:     protected $_rulesChecker;
 39: 
 40:     /**
 41:      * Returns whether or not the passed entity complies with all the rules stored in
 42:      * the rules checker.
 43:      *
 44:      * @param \Cake\Datasource\EntityInterface $entity The entity to check for validity.
 45:      * @param string $operation The operation being run. Either 'create', 'update' or 'delete'.
 46:      * @param \ArrayObject|array|null $options The options To be passed to the rules.
 47:      * @return bool
 48:      */
 49:     public function checkRules(EntityInterface $entity, $operation = RulesChecker::CREATE, $options = null)
 50:     {
 51:         $rules = $this->rulesChecker();
 52:         $options = $options ?: new ArrayObject();
 53:         $options = is_array($options) ? new ArrayObject($options) : $options;
 54:         $hasEvents = ($this instanceof EventDispatcherInterface);
 55: 
 56:         if ($hasEvents) {
 57:             $event = $this->dispatchEvent(
 58:                 'Model.beforeRules',
 59:                 compact('entity', 'options', 'operation')
 60:             );
 61:             if ($event->isStopped()) {
 62:                 return $event->getResult();
 63:             }
 64:         }
 65: 
 66:         $result = $rules->check($entity, $operation, $options->getArrayCopy());
 67: 
 68:         if ($hasEvents) {
 69:             $event = $this->dispatchEvent(
 70:                 'Model.afterRules',
 71:                 compact('entity', 'options', 'result', 'operation')
 72:             );
 73: 
 74:             if ($event->isStopped()) {
 75:                 return $event->getResult();
 76:             }
 77:         }
 78: 
 79:         return $result;
 80:     }
 81: 
 82:     /**
 83:      * Returns the RulesChecker for this instance.
 84:      *
 85:      * A RulesChecker object is used to test an entity for validity
 86:      * on rules that may involve complex logic or data that
 87:      * needs to be fetched from relevant datasources.
 88:      *
 89:      * @see \Cake\Datasource\RulesChecker
 90:      * @return \Cake\Datasource\RulesChecker
 91:      */
 92:     public function rulesChecker()
 93:     {
 94:         if ($this->_rulesChecker !== null) {
 95:             return $this->_rulesChecker;
 96:         }
 97:         $class = defined('static::RULES_CLASS') ? static::RULES_CLASS : 'Cake\Datasource\RulesChecker';
 98:         $this->_rulesChecker = $this->buildRules(new $class(['repository' => $this]));
 99:         $this->dispatchEvent('Model.buildRules', ['rules' => $this->_rulesChecker]);
100: 
101:         return $this->_rulesChecker;
102:     }
103: 
104:     /**
105:      * Returns a RulesChecker object after modifying the one that was supplied.
106:      *
107:      * Subclasses should override this method in order to initialize the rules to be applied to
108:      * entities saved by this instance.
109:      *
110:      * @param \Cake\Datasource\RulesChecker $rules The rules object to be modified.
111:      * @return \Cake\Datasource\RulesChecker
112:      */
113:     public function buildRules(RulesChecker $rules)
114:     {
115:         return $rules;
116:     }
117: }
118: