1. sfValidatorBase.class.php
  2. /**
 * sfValidatorBase is the base class for all validators.
 *
 * It also implements the required option for all validators.
 *
 * @package    symfony
 * @subpackage validator
 * @author     Fabien Potencier 
 * @version    SVN: $Id: sfValidatorBase.class.php 23922 2009-11-14 14:58:38Z fabien $
 */
  3. abstract class sfValidatorBase
  4. {
  5.   protected static
  6.     $charset = 'UTF-8',
  7.     $globalDefaultMessages = array('invalid' => 'Invalid.', 'required' => 'Required.');
  9.   protected
  10.     $requiredOptions = array(),
  11.     $defaultMessages = array(),
  12.     $defaultOptions  = array(),
  13.     $messages        = array(),
  14.     $options         = array();
  16.   /**
  17.    * Constructor.
  18.    *
  19.    * Available options:
  20.    *
  21.    *  * required:    true if the value is required, false otherwise (default to true)
  22.    *  * trim:        true if the value must be trimmed, false otherwise (default to false)
  23.    *  * empty_value: empty value when value is not required
  24.    *
  25.    * Available error codes:
  26.    *
  27.    *  * required
  28.    *  * invalid
  29.    *
  30.    * @param array $options   An array of options
  31.    * @param array $messages  An array of error messages
  32.    */
  33.   public function __construct($options = array(), $messages = array())
  34.   {
  35.     $this->options  = array_merge(array('required' => true, 'trim' => false, 'empty_value' => null), $this->options);
  36.     $this->messages = array_merge(array('required' => self::$globalDefaultMessages['required'], 'invalid' => self::$globalDefaultMessages['invalid']), $this->messages);
  38.     $this->configure($options, $messages);
  40.     $this->setDefaultOptions($this->getOptions());
  41.     $this->setDefaultMessages($this->getMessages());
  43.     $currentOptionKeys = array_keys($this->options);
  44.     $optionKeys = array_keys($options);
  46.     // check option names
  47.     if ($diff = array_diff($optionKeys, array_merge($currentOptionKeys, $this->requiredOptions)))
  48.     {
  49.       throw new InvalidArgumentException(sprintf('%s does not support the following options: \'%s\'.', get_class($this), implode('\', \'', $diff)));
  50.     }
  52.     // check error code names
  53.     if ($diff = array_diff(array_keys($messages), array_keys($this->messages)))
  54.     {
  55.       throw new InvalidArgumentException(sprintf('%s does not support the following error codes: \'%s\'.', get_class($this), implode('\', \'', $diff)));
  56.     }
  58.     // check required options
  59.     if ($diff = array_diff($this->requiredOptions, array_merge($currentOptionKeys, $optionKeys)))
  60.     {
  61.       throw new RuntimeException(sprintf('%s requires the following options: \'%s\'.', get_class($this), implode('\', \'', $diff)));
  62.     }
  64.     $this->options  = array_merge($this->options, $options);
  65.     $this->messages = array_merge($this->messages, $messages);
  66.   }
  68.   /**
  69.    * Configures the current validator.
  70.    *
  71.    * This method allows each validator to add options and error messages
  72.    * during validator creation.
  73.    *
  74.    * If some options and messages are given in the sfValidatorBase constructor
  75.    * they will take precedence over the options and messages you configure
  76.    * in this method.
  77.    *
  78.    * @param array $options   An array of options
  79.    * @param array $messages  An array of error messages
  80.    *
  81.    * @see __construct()
  82.    */
  83.   protected function configure($options = array(), $messages = array())
  84.   {
  85.   }
  87.   /**
  88.    * Returns an error message given an error code.
  89.    *
  90.    * @param  string $name  The error code
  91.    *
  92.    * @return string The error message, or the empty string if the error code does not exist
  93.    */
  94.   public function getMessage($name)
  95.   {
  96.     return isset($this->messages[$name]) ? $this->messages[$name] : '';
  97.   }
  99.   /**
  100.    * Adds a new error code with a default error message.
  101.    *
  102.    * @param string $name   The error code
  103.    * @param string $value  The error message
  104.    *
  105.    * @return sfValidatorBase The current validator instance
  106.    */
  107.   public function addMessage($name, $value)
  108.   {
  109.     $this->messages[$name] = isset(self::$globalDefaultMessages[$name]) ? self::$globalDefaultMessages[$name] : $value;
  111.     return $this;
  112.   }
  114.   /**
  115.    * Changes an error message given the error code.
  116.    *
  117.    * @param string $name   The error code
  118.    * @param string $value  The error message
  119.    *
  120.    * @return sfValidatorBase The current validator instance
  121.    */
  122.   public function setMessage($name, $value)
  123.   {
  124.     if (!in_array($name, array_keys($this->messages)))
  125.     {
  126.       throw new InvalidArgumentException(sprintf('%s does not support the following error code: \'%s\'.', get_class($this), $name));
  127.     }
  129.     $this->messages[$name] = $value;
  131.     return $this;
  132.   }
  134.   /**
  135.    * Returns an array of current error messages.
  136.    *
  137.    * @return array An array of messages
  138.    */
  139.   public function getMessages()
  140.   {
  141.     return $this->messages;
  142.   }
  144.   /**
  145.    * Changes all error messages.
  146.    *
  147.    * @param array $values  An array of error messages
  148.    *
  149.    * @return sfValidatorBase The current validator instance
  150.    */
  151.   public function setMessages($values)
  152.   {
  153.     $this->messages = $values;
  155.     return $this;
  156.   }
  158.   /**
  159.    * Gets an option value.
  160.    *
  161.    * @param  string $name  The option name
  162.    *
  163.    * @return mixed  The option value
  164.    */
  165.   public function getOption($name)
  166.   {
  167.     return isset($this->options[$name]) ? $this->options[$name] : null;
  168.   }
  170.   /**
  171.    * Adds a new option value with a default value.
  172.    *
  173.    * @param string $name   The option name
  174.    * @param mixed  $value  The default value
  175.    *
  176.    * @return sfValidatorBase The current validator instance
  177.    */
  178.   public function addOption($name, $value = null)
  179.   {
  180.     $this->options[$name] = $value;
  182.     return $this;
  183.   }
  185.   /**
  186.    * Changes an option value.
  187.    *
  188.    * @param string $name   The option name
  189.    * @param mixed  $value  The value
  190.    *
  191.    * @return sfValidatorBase The current validator instance
  192.    */
  193.   public function setOption($name, $value)
  194.   {
  195.     if (!in_array($name, array_merge(array_keys($this->options), $this->requiredOptions)))
  196.     {
  197.       throw new InvalidArgumentException(sprintf('%s does not support the following option: \'%s\'.', get_class($this), $name));
  198.     }
  200.     $this->options[$name] = $value;
  202.     return $this;
  203.   }
  205.   /**
  206.    * Returns true if the option exists.
  207.    *
  208.    * @param  string $name  The option name
  209.    *
  210.    * @return bool true if the option exists, false otherwise
  211.    */
  212.   public function hasOption($name)
  213.   {
  214.     return isset($this->options[$name]);
  215.   }
  217.   /**
  218.    * Returns all options.
  219.    *
  220.    * @return array An array of options
  221.    */
  222.   public function getOptions()
  223.   {
  224.     return $this->options;
  225.   }
  227.   /**
  228.    * Changes all options.
  229.    *
  230.    * @param array $values  An array of options
  231.    *
  232.    * @return sfValidatorBase The current validator instance
  233.    */
  234.   public function setOptions($values)
  235.   {
  236.     $this->options = $values;
  238.     return $this;
  239.   }
  241.   /**
  242.    * Adds a required option.
  243.    *
  244.    * @param string $name  The option name
  245.    *
  246.    * @return sfValidatorBase The current validator instance
  247.    */
  248.   public function addRequiredOption($name)
  249.   {
  250.     $this->requiredOptions[] = $name;
  252.     return $this;
  253.   }
  255.   /**
  256.    * Returns all required option names.
  257.    *
  258.    * @return array An array of required option names
  259.    */
  260.   public function getRequiredOptions()
  261.   {
  262.     return $this->requiredOptions;
  263.   }
  265.   /**
  266.    * Sets the default message for a given name.
  267.    *
  268.    * @param string $name    The name of the message
  269.    * @param string $message The default message string
  270.    */
  271.   static public function setDefaultMessage($name, $message)
  272.   {
  273.     self::$globalDefaultMessages[$name] = $message;
  274.   }
  276.   /**
  277.    * Cleans the input value.
  278.    *
  279.    * This method is also responsible for trimming the input value
  280.    * and checking the required option.
  281.    *
  282.    * @param  mixed $value  The input value
  283.    *
  284.    * @return mixed The cleaned value
  285.    *
  286.    * @throws sfValidatorError
  287.    */
  288.   public function clean($value)
  289.   {
  290.     $clean = $value;
  292.     if ($this->options['trim'] && is_string($clean))
  293.     {
  294.       $clean = trim($clean);
  295.     }
  297.     // empty value?
  298.     if ($this->isEmpty($clean))
  299.     {
  300.       // required?
  301.       if ($this->options['required'])
  302.       {
  303.         throw new sfValidatorError($this, 'required');
  304.       }
  306.       return $this->getEmptyValue();
  307.     }
  309.     return $this->doClean($clean);
  310.   }
  312.   /**
  313.    * Cleans the input value.
  314.    *
  315.    * Every subclass must implements this method.
  316.    *
  317.    * @param  mixed $value  The input value
  318.    *
  319.    * @return mixed The cleaned value
  320.    *
  321.    * @throws sfValidatorError
  322.    */
  323.   abstract protected function doClean($value);
  325.   /**
  326.    * Sets the charset to use when validating strings.
  327.    *
  328.    * @param string $charset  The charset
  329.    */
  330.   static public function setCharset($charset)
  331.   {
  332.     self::$charset = $charset;
  333.   }
  335.   /**
  336.    * Returns the charset to use when validating strings.
  337.    *
  338.    * @return string The charset (default to UTF-8)
  339.    */
  340.   static public function getCharset()
  341.   {
  342.     return self::$charset;
  343.   }
  345.   /**
  346.    * Returns true if the value is empty.
  347.    *
  348.    * @param  mixed $value  The input value
  349.    *
  350.    * @return bool true if the value is empty, false otherwise
  351.    */
  352.   protected function isEmpty($value)
  353.   {
  354.     return in_array($value, array(null, '', array()), true);
  355.   }
  357.   /**
  358.    * Returns an empty value for this validator.
  359.    *
  360.    * @return mixed The empty value for this validator
  361.    */
  362.   protected function getEmptyValue()
  363.   {
  364.     return $this->getOption('empty_value');
  365.   }
  367.   /**
  368.    * Returns an array of all error codes for this validator.
  369.    *
  370.    * @return array An array of possible error codes
  371.    *
  372.    * @see getDefaultMessages()
  373.    */
  374.   final public function getErrorCodes()
  375.   {
  376.     return array_keys($this->getDefaultMessages());
  377.   }
  379.   /**
  380.    * Returns default messages for all possible error codes.
  381.    *
  382.    * @return array An array of default error codes and messages
  383.    */
  384.   public function getDefaultMessages()
  385.   {
  386.     return $this->defaultMessages;
  387.   }
  389.   /**
  390.    * Sets default messages for all possible error codes.
  391.    *
  392.    * @param array $messages  An array of default error codes and messages
  393.    */
  394.   protected function setDefaultMessages($messages)
  395.   {
  396.     $this->defaultMessages = $messages;
  397.   }
  399.   /**
  400.    * Returns default option values.
  401.    *
  402.    * @return array An array of default option values
  403.    */
  404.   public function getDefaultOptions()
  405.   {
  406.     return $this->defaultOptions;
  407.   }
  409.   /**
  410.    * Sets default option values.
  411.    *
  412.    * @param array $options  An array of default option values
  413.    */
  414.   protected function setDefaultOptions($options)
  415.   {
  416.     $this->defaultOptions = $options;
  417.   }
  419.   /**
  420.    * Returns a string representation of this validator.
  421.    *
  422.    * @param  int $indent  Indentation (number of spaces before each line)
  423.    *
  424.    * @return string The string representation of the validator
  425.    */
  426.   public function asString($indent = 0)
  427.   {
  428.     $options = $this->getOptionsWithoutDefaults();
  429.     $messages = $this->getMessagesWithoutDefaults();
  431.     return sprintf('%s%s(%s%s)',
  432.       str_repeat(' ', $indent),
  433.       str_replace('sfValidator', '', get_class($this)),
  434.       $options ? sfYamlInline::dump($options) : ($messages ? '{}' : ''),
  435.       $messages ? ', '.sfYamlInline::dump($messages) : ''
  436.     );
  437.   }
  439.   /**
  440.    * Returns all error messages with non default values.
  441.    *
  442.    * @return string A string representation of the error messages
  443.    */
  444.   protected function getMessagesWithoutDefaults()
  445.   {
  446.     $messages = $this->messages;
  448.     // remove default option values
  449.     foreach ($this->getDefaultMessages() as $key => $value)
  450.     {
  451.       if (array_key_exists($key, $messages) && $messages[$key] === $value)
  452.       {
  453.         unset($messages[$key]);
  454.       }
  455.     }
  457.     return $messages;
  458.   }
  460.   /**
  461.    * Returns all options with non default values.
  462.    *
  463.    * @return string  A string representation of the options
  464.    */
  465.   protected function getOptionsWithoutDefaults()
  466.   {
  467.     $options = $this->options;
  469.     // remove default option values
  470.     foreach ($this->getDefaultOptions() as $key => $value)
  471.     {
  472.       if (array_key_exists($key, $options) && $options[$key] === $value)
  473.       {
  474.         unset($options[$key]);
  475.       }
  476.     }
  478.     return $options;
  479.   }
  480. }
Debug toolbar