ValidatorAwareTrait.php

<?php
/**
 * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
 * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
 *
 * Licensed under The MIT License
 * For full copyright and license information, please see the LICENSE.txt
 * Redistributions of files must retain the above copyright notice.
 *
 * @copyright     Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
 * @link          https://cakephp.org CakePHP(tm) Project
 * @since         3.0.3
 * @license       https://opensource.org/licenses/mit-license.php MIT License
 */
namespace Cake\Validation;

use Cake\Event\EventDispatcherInterface;
use RuntimeException;

/**
 * A trait that provides methods for building and
 * interacting with Validators.
 *
 * This trait is useful when building ORM like features where
 * the implementing class wants to build and customize a variety
 * of validator instances.
 *
 * This trait expects that classes including it define three constants:
 *
 * - `DEFAULT_VALIDATOR` - The default validator name.
 * - `VALIDATOR_PROVIDER_NAME ` - The provider name the including class is assigned
 *   in validators.
 * - `BUILD_VALIDATOR_EVENT` - The name of the event to be triggred when validators
 *   are built.
 *
 * If the including class also implements events the `Model.buildValidator` event
 * will be triggered when validators are created.
 */
trait ValidatorAwareTrait
{

    /**
     * Validator class.
     *
     * @var string
     */
    protected $_validatorClass = '\Cake\Validation\Validator';

    /**
     * A list of validation objects indexed by name
     *
     * @var \Cake\Validation\Validator[]
     */
    protected $_validators = [];

    /**
     * Returns the validation rules tagged with $name. It is possible to have
     * multiple different named validation sets, this is useful when you need
     * to use varying rules when saving from different routines in your system.
     *
     * There are two different ways of creating and naming validation sets: by
     * creating a new method inside your own Table subclass, or by building
     * the validator object yourself and storing it using this method.
     *
     * For example, if you wish to create a validation set called 'forSubscription',
     * you will need to create a method in your Table subclass as follows:
     *
     * ```
     * public function validationForSubscription($validator)
     * {
     *  return $validator
     *  ->add('email', 'valid-email', ['rule' => 'email'])
     *  ->add('password', 'valid', ['rule' => 'notBlank'])
     *  ->requirePresence('username');
     * }
     * ```
     *
     * Otherwise, you can build the object by yourself and store it in the Table object:
     *
     * ```
     * $validator = new \Cake\Validation\Validator($table);
     * $validator
     *  ->add('email', 'valid-email', ['rule' => 'email'])
     *  ->add('password', 'valid', ['rule' => 'notBlank'])
     *  ->allowEmpty('bio');
     * $table->validator('forSubscription', $validator);
     * ```
     *
     * You can implement the method in `validationDefault` in your Table subclass
     * should you wish to have a validation set that applies in cases where no other
     * set is specified.
     *
     * @param string|null $name the name of the validation set to return
     * @param \Cake\Validation\Validator|null $validator The validator instance to store,
     *   use null to get a validator.
     * @return \Cake\Validation\Validator
     * @throws \RuntimeException
     * @deprecated 3.5.0 Use getValidator/setValidator instead.
     */
    public function validator($name = null, Validator $validator = null)
    {
        if ($validator !== null) {
            $name = $name ?: self::DEFAULT_VALIDATOR;
            $this->setValidator($name, $validator);
        }

        return $this->getValidator($name);
    }

    /**
     * Returns the validation rules tagged with $name. It is possible to have
     * multiple different named validation sets, this is useful when you need
     * to use varying rules when saving from different routines in your system.
     *
     * If a validator has not been set earlier, this method will build a valiator
     * using a method inside your class.
     *
     * For example, if you wish to create a validation set called 'forSubscription',
     * you will need to create a method in your Table subclass as follows:
     *
     * ```
     * public function validationForSubscription($validator)
     * {
     *  return $validator
     *  ->add('email', 'valid-email', ['rule' => 'email'])
     *  ->add('password', 'valid', ['rule' => 'notBlank'])
     *  ->requirePresence('username');
     * }
     * $validator = $this->getValidator('forSubscription');
     * ```
     *
     * You can implement the method in `validationDefault` in your Table subclass
     * should you wish to have a validation set that applies in cases where no other
     * set is specified.
     *
     * If a $name argument has not been provided, the default validator will be returned.
     * You can configure your default validator name in a `DEFAULT_VALIDATOR`
     * class constant.
     *
     * @param string|null $name The name of the validation set to return.
     * @return \Cake\Validation\Validator
     */
    public function getValidator($name = null)
    {
        $name = $name ?: self::DEFAULT_VALIDATOR;
        if (!isset($this->_validators[$name])) {
            $validator = $this->createValidator($name);
            $this->setValidator($name, $validator);
        }

        return $this->_validators[$name];
    }

    /**
     * Creates a validator using a custom method inside your class.
     *
     * This method is used only to build a new validator and it does not store
     * it in your object. If you want to build and reuse validators,
     * use getValidator() method instead.
     *
     * @param string $name The name of the validation set to create.
     * @return \Cake\Validation\Validator
     * @throws \RuntimeException
     */
    protected function createValidator($name)
    {
        $method = 'validation' . ucfirst($name);
        if (!$this->validationMethodExists($method)) {
            $message = sprintf('The %s::%s() validation method does not exists.', __CLASS__, $method);
            throw new RuntimeException($message);
        }

        $validator = new $this->_validatorClass;
        $validator = $this->$method($validator);
        if ($this instanceof EventDispatcherInterface) {
            $this->dispatchEvent(self::BUILD_VALIDATOR_EVENT, compact('validator', 'name'));
        }

        if (!$validator instanceof Validator) {
            throw new RuntimeException(sprintf('The %s::%s() validation method must return an instance of %s.', __CLASS__, $method, Validator::class));
        }

        return $validator;
    }

    /**
     * This method stores a custom validator under the given name.
     *
     * You can build the object by yourself and store it in your object:
     *
     * ```
     * $validator = new \Cake\Validation\Validator($table);
     * $validator
     *  ->add('email', 'valid-email', ['rule' => 'email'])
     *  ->add('password', 'valid', ['rule' => 'notBlank'])
     *  ->allowEmpty('bio');
     * $this->setValidator('forSubscription', $validator);
     * ```
     *
     * @param string $name The name of a validator to be set.
     * @param \Cake\Validation\Validator $validator Validator object to be set.
     * @return $this
     */
    public function setValidator($name, Validator $validator)
    {
        $validator->setProvider(self::VALIDATOR_PROVIDER_NAME, $this);
        $this->_validators[$name] = $validator;

        return $this;
    }

    /**
     * Checks whether or not a validator has been set.
     *
     * @param string $name The name of a validator.
     * @return bool
     */
    public function hasValidator($name)
    {
        $method = 'validation' . ucfirst($name);
        if ($this->validationMethodExists($method)) {
            return true;
        }

        return isset($this->_validators[$name]);
    }

    /**
     * Checks if validation method exists.
     *
     * @param string $name Validation method name.
     * @return bool
     */
    protected function validationMethodExists($name)
    {
        return method_exists($this, $name);
    }

    /**
     * Returns the default validator object. Subclasses can override this function
     * to add a default validation set to the validator object.
     *
     * @param \Cake\Validation\Validator $validator The validator that can be modified to
     * add some rules to it.
     * @return \Cake\Validation\Validator
     */
    public function validationDefault(Validator $validator)
    {
        return $validator;
    }
}