Appendix B - Validators

Introduction

The symfony form framework comes bundled with a lot of useful validators. These validators cover the common needs of most projects. This chapter describes the default form validators bundled with symfony. We have also included the validators from the sfPropelPlugin, and sfDoctrinePlugin plugins, as these plugins are supported by the core team and contain some very useful validators.

Before diving into each validator details, let's see what validators have in common.

The sfValidatorBase Base Class

All symfony validators inherit from the sfValidator base class, which provides some default features available to all validators.

Validators have two goals: cleaning and validating a tainted value.

When creating a validator, you can optionally pass options and error messages as arguments:

$v = new sfValidatorString(
  array('required' => true),
  array('required' => 'This value is required.')
);

Options and error messages can also be set by using the setOptions() and setMessages() methods:

$v = new sfValidatorString();
$v->setOptions(array('required' => true));
$v->setMessages(array('required' => 'This value is required.'));

The setOption() and setMessage() methods allows to set an individual option or error message:

$v = new sfValidatorString();
$v->setOption('required', true);
$v->setMessage('required', 'This value is required.');

A tainted value can be validated by calling the clean() method:

$cleaned = $v->clean('name', 'value', array('class' => 'foo'));

The clean() method takes a tainted value as an argument and returns the cleaned up value. If a validation error occurs, a sfValidatorError is thrown.

The default options defined by sfValidatorBase are the following:

The default error messages defined by sfValidatorBase are the following:

You can change the default string used for the required and invalid error messages by calling the setDefaultMessage() method. These must be set before any base validators are loaded, for example by using the setup() method:

public function setup()
{
  sfValidatorBase::setDefaultMessage('required', 'This value is required.');
  sfValidatorBase::setDefaultMessage('invalid', 'This value is invalid.');
  parent::setup();
}

Error messages can contain placeholders. A placeholder is a string enclosed between %. The placeholder are replaced at runtime. All error messages have access to the tainted value with the %value% placeholder. Each error message can also define specific placeholders.

Some validators need to know the charset used by the tainted value. By default the charset is UTF-8, but it can be configured by calling the setCharset() method:

sfValidatorBase::setCharset('ISO-8859-1');

Validator Schema

A validator schema is a wrapper validator for one or several other validators.

When an error occurs, a validator schema throws a sfValidatorErrorSchema exception.

In the next sections, the validators have been regrouped into categories.

Validators

• sfValidatorString
• sfValidatorRegex
• sfValidatorEmail
• sfValidatorUrl
• sfValidatorInteger
• sfValidatorNumber
• sfValidatorBoolean
• sfValidatorChoice
• sfValidatorPass
• sfValidatorCallback
• sfValidatorDate
• sfValidatorTime
• sfValidatorDateTime
• sfValidatorDateRange
• sfValidatorFile
• sfValidatorAnd
• sfValidatorOr
• sfValidatorSchema
• sfValidatorSchemaCompare
• sfValidatorSchemaFilter
• sfValidatorI18nChoiceCountry
• sfValidatorI18nChoiceLanguage
• sfValidatorI18nTimezone
• sfValidatorPropelChoice
• sfValidatorPropelUnique
• sfValidatorDoctrineChoice
• sfValidatorDoctrineUnique

Simple Validators

sfValidatorString

Schema validator: No

The sfValidatorString validator validates a string and converts the tainted value to a string.

sfValidatorRegex

Schema validator: No

The sfValidatorRegex validator validates a string against a regular expression.

sfValidatorEmail

Schema validator: No

The sfValidatorEmail validator can validate emails. It inherits from sfValidatorRegex.

sfValidatorUrl

Schema validator: No

The sfValidatorUrl validator can validate HTTP and FTP URLs. It inherits from sfValidatorRegex.

sfValidatorInteger

Schema validator: No

The sfValidatorInteger validator validates an integer and converts the tainted value to an integer.

The default invalid error message is "%value%" is not an integer..

sfValidatorNumber

Schema validator: No

The sfValidatorNumber validator validates a number (a string that PHP is able to understand with the floatval() function) and converts the tainted value to a float.

The default invalid error message is "%value%" is not a number..

sfValidatorBoolean

Schema validator: No

The sfValidatorBoolean validator validates a Boolean and returns either true or false.

sfValidatorChoice

Schema validator: No

The sfValidatorChoice validator validates if the tainted value is among a list of expected values.

sfValidatorPass

Schema validator: No

The sfValidatorPass validator is a no-op validator, and returns the tainted value as is.

sfValidatorCallback

Schema validator: No

The sfValidatorCallback validator delegate the actual validation to a PHP callback.

The callback is passed the current validator instance, the tainted value and an array of arguments (from the arguments option) as arguments:

function constant_validator_callback($validator, $value, $arguments)
{
  if ($value != $arguments['constant'])
  {
    throw new sfValidatorError($validator, 'invalid');
  }
 
  return $value;
}
 
$v = new sfValidatorCallback(array(
  'callback'  => 'constant_validator_callback',
  'arguments' => array('constant' => 'foo'),
));

Date Validators

sfValidatorDate

Schema validator: No

The sfValidatorDate validates dates and date times (date times are supported by setting the with_time option). Apart from validating the format of a date, it can enforce a minimum and a maximum valid date.

The validator accepts several type of inputs:

• an array composed of the following keys: year, month, day, hour, minute, and second
• a string matching the date_format regular expression if provided (for instance ~(?P<day>\d{2})/(?P<month>\d{2})/(?P<year>\d{4})~)
• a string that can be parsed by the strtotime() PHP function
• an integer representing a timestamp

The tainted value is converted to a date by applying the date_output or datetime_output format.

sfValidatorTime

Schema validator: No

The sfValidatorTime validates a time.

The validator accepts several type of inputs:

• an array composed of the following keys: hour, minute, and second
• a string matching the time_format regular expression if provided
• a string that can be parsed by the strtotime() PHP function
• an integer representing a timestamp

The tainted value is converted to a time by applying the time_output format.

sfValidatorDateTime

Schema validator: No

The sfValidatorDateTime validates dates with a time.

It is a shortcut for:

$v = new sfValidatorDate(array('with_time' => true));

sfValidatorDateRange

Schema validator: No

The sfValidatorDateTime validates a range of dates.

The from_date and to_date validators must be instances of the sfValidatorDate class.

The invalid error message is "%value%" does not match the time format (%time_format%)..

File Validator

sfValidatorFile

Schema validator: No

The sfValidatorFile validator validates an uploaded file.

The validator converts the uploaded file to an instance of the sfValidatedFile class, or of the validated_file_class option if it is set.

The web_images mime-type category contains the following mime-types:

• image/jpeg
• image/pjpeg
• image/png
• image/x-png
• image/gif

If the mime_types option is set, the validator need a way to test the mime-type of the uploaded file. The validator comes bundled with three of them:

• guessFromFileinfo: Uses the finfo_open() function (from the Fileinfo PECL extension)
• guessFromMimeContentType: Uses the mime_content_type() function (deprecated)
• guessFromFileBinary: Uses the file binary (only works on *nix system)

The validator maps PHP errors as follows:

• UPLOAD_ERR_INI_SIZE: max_size
• UPLOAD_ERR_FORM_SIZE: max_size
• UPLOAD_ERR_PARTIAL: partial
• UPLOAD_ERR_NO_TMP_DIR: no_tmp_dir
• UPLOAD_ERR_CANT_WRITE: cant_write
• UPLOAD_ERR_EXTENSION: extension

Logical Validators

sfValidatorAnd

Schema validator: No

The sfValidatorAnd validator validates a tainted value if it passes a list of validators.

The sfValidatorAnd constructor takes a list of validators as its first argument:

$v = new sfValidatorAnd(
  array(
    new sfValidatorString(array('max_length' => 255)),
    new sfValidatorEmail(),
  ),
  array('halt_on_error' => true),
  array('invalid' => 'The input value must be an email with less than 255 characters.')
);

By default, the validator throws an array of error messages thrown by all the embedded validators. It can also throw a single error message if the invalid error message is set to a not-empty string, like shown in the above example.

The order of validators is significant if the halt_on_error option is set to true.

The embedded list of validators can also be managed by using the getValidators() and addValidator() methods.

sfValidatorOr

Schema validator: No

The sfValidatorOr validator validates a tainted value if it passes at least one validator from a list.

The sfValidatorOr constructor takes a list of validators as its first argument:

$v = new sfValidatorOr(
  array(
    new sfValidatorRegex(array('pattern' => '/\.com$/')),
    new sfValidatorEmail(),
  ),
  array(),
  array('invalid' => 'The input value a .com domain or a valid email address.')
);

By default, the validator throws an array of error messages thrown by all the embedded validators. It can also throw a single error message if the invalid error message is set to a not-empty string, like shown in the above example.

The embedded list of validators can also be managed by using the getValidators() and addValidator() methods.

sfValidatorSchema

Schema validator: Yes

The sfValidatorSchema validator represents a validator which is composed of several fields. A field is simply a named validator:

$v = new sfValidatorSchema(array(
  'name'    => new sfValidatorString(),
  'country' => new sfValidatorI18nChoiceCountry(),
));

This validator only accepts an array as an input value and throws a InvalidArgumentException if this is not the case.

The validator can have a pre-validator, which is executed before all other validators, and a post-validator, which is executed on the cleaned-up values after all other validators.

The pre-validator and the post-validator are validator schema themselves that receive all values. They can be set with the setPreValidator() and setPostValidator() methods:

$v->setPostValidator(
  new sfValidatorSchemaCompare('password', '==', 'password_again')
);

The sfValidatorSchema can be used as an array to access the embedded validators:

$vs = new sfValidatorSchema(array('name' => new sfValidatorString()));
 
$nameValidator = $vs['name'];
 
unset($vs['name']);

You can access embedded validator schema validators by using the array notation:

$vs['author']['first_name']->setMessage('invalid', 'The first name is invalid.');

The post_max_size error is thrown if the amount of data submitted for a form exceeds the post_max_size value from the php.ini file.

sfValidatorSchemaCompare

Schema validator: Yes

The sfValidatorSchemaCompare validator compares several values from the given tainted value array:

$v = new sfValidatorSchemaCompare('password', '==', 'password_again');

The available operators are the followings:

• sfValidatorSchemaCompare::EQUAL or ==
• sfValidatorSchemaCompare::IDENTICAL or ===
• sfValidatorSchemaCompare::NOT_EQUAL or !=
• sfValidatorSchemaCompare::NOT_IDENTICAL or !==
• sfValidatorSchemaCompare::LESS_THAN or <
• sfValidatorSchemaCompare::LESS_THAN_EQUAL or <=
• sfValidatorSchemaCompare::GREATER_THAN or >
• sfValidatorSchemaCompare::GREATER_THAN_EQUAL or >=

By default, the validator throws a global error. If the throw_global_error is set to true, an error for the left field is thrown.

The invalid error messages accepts the following values: %left_field%, %right_field%, and %operator%.

sfValidatorSchemaFilter

Schema validator: Yes

The sfValidatorSchemaFilter validator converts a non-schema validator to a schema validator. It is sometimes useful in a post validator context:

$v = new sfValidatorSchema();
$v->setPostValidator(
  new sfValidatorSchemaFilter('email', new sfValidatorEmail())
);

I18n Validators

sfValidatorI18nChoiceCountry

Schema validator: No

The sfValidatorI18nChoiceCountry validates that the tainted value is a valid country ISO 3166 code.

sfValidatorI18nChoiceLanguage

Schema validator: No

The sfValidatorI18nChoiceLanguage validates that the tainted value is a valid language.

sfValidatorI18nChoiceTimezone

Schema validator: No

The sfValidatorI18nChoiceTimezone validates that the tainted value is a valid timezone.

Propel Validators

sfValidatorPropelChoice

Schema validator: No

The sfValidatorPropelChoice validator validates that the tainted value is among the list of records of a given Propel model.

The list of records can be restricted by using the criteria option.

The tainted value must be the primary key of records. This can be changed by passing the column option.

sfValidatorPropelUnique

Schema validator: Yes

The sfValidatorPropelUnique validator validates the uniqueness of a column or a group of columns (column option) for a Propel model.

If the uniqueness is on several columns, the error can be thrown globally by setting the throw_global_error option.

Doctrine Validators

sfValidatorDoctrineChoice

Schema validator: No

The sfValidatorDoctrineChoice validator validates that the tainted value is among the list of records of a given Doctrine model.

The list of records can be restricted by using the query option.

The tainted value must be the primary key of records. This can be changed by passing the column option.

sfValidatorDoctrineUnique

Schema validator: Yes

The sfValidatorDoctrineUnique validator validates the uniqueness of a column or a group of columns (column option) for a Doctrine model.

If the uniqueness is on several columns, the error can be thrown globally by setting the throw_global_error option.