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