Annexe B - Validateurs

Introduction

Le framework de formulaire de symfony est livré avec un lot de validateurs utiles. Ces validateurs couvrent les besoins communs de la plupart des projets. Ce chapitre décrit les validateurs de formulaire par défaut fournis avec symfony. Nous avons également inclus les validateurs des plugins sfPropelPlugin et sfDoctrinePlugin, ces plugins sont pris en charge par l'équipe de base et contiennent quelques uns des validateurs les plus utiles.

Avant de plonger dans les détails de chaque validateur, voyons ce que les validateurs ont en commun.

La classe de base sfValidatorBase

Tous les validateurs symfony héritent de la classe de base sfValidator, qui fournit des fonctionnalités disponibles par défaut à tous les validateurs.

Les validateurs ont deux objectifs : le nettoyage et la validation d'une valeur saisie.

Lors de la création d'un validateur, vous pouvez éventuellement passer des options et des messages d'erreur comme arguments :

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

Les options et les messages d'erreur peuvent également être configurés en utilisant les méthodes setOptions() et setMessages() :

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

Les méthodes setOption() et setMessage() permettent d'attribuer une option ou un message d'erreur individuellement :

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

Une valeur saisie peut être validée en appelant la méthode clean() :

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

La méthode clean() prend une valeur saisie comme argument et retourne la valeur nettoyée. Si une erreur de validation se produit, une exception sfValidatorError est levée.

Les options par défaut définies par sfValidatorBase sont les suivantes :

Les messages d'erreur par défaut définis par sfValidatorBase sont les suivants :

Vous pouvez changer la chaîne par défaut utilisée pour les messages d'erreur required et invalid en appelant la méthode setDefaultMessage(). Celle-ci doit être définie avant que les validateurs de base soient chargés, par exemple en utilisant la méthode setup() :

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

Les messages d'erreur peuvent contenir des espaces réservés. Un espace réservé est une chaîne entre %. L'espace réservé est remplacé à l'exécution. Tous les messages d'erreur ont accès à la valeur saisie avec l'espace réservé %value%. Chaque message d'erreur peut également définir des espaces réservés spécifiques.

Quelques validateurs ont besoin de connaître le jeu de caractères utilisé par la valeur saisie. Par défaut le jeu de caractères est UTF-8, mais il peut être configuré en appelant la méthode setCharset() :

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

Schéma de validateur

Un schéma de validateur est un validateur qui enveloppe un ou plusieurs autres validateurs.

Quand une erreur survient, un schéma de validateur lève une exception sfValidatorErrorSchema.

Dans les sections suivantes, les validateurs ont été regroupés en catégories.

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

Validateurs simples

sfValidatorString

Schéma de validateur : Non

Le validateur sfValidatorString valide une chaine et convertie la valeur saisie en une chaine.

sfValidatorRegex

Schéma de validateur : Non

Le validateur sfValidatorRegex valide une chaîne par rapport à une expression régulière.

sfValidatorEmail

Schéma de validateur : Non

Le validateur sfValidatorEmail peut valider les emails. Il hérite de sfValidatorRegex.

sfValidatorUrl

Schéma de validateur : Non

Le validateur sfValidatorUrl peut valider les URL HTTP et FTP. Il hérite de sfValidatorRegex.

sfValidatorInteger

Schéma de validateur : Non

Le validateur sfValidatorInteger valide un entier et convertit la valeur saisie en un entier.

Le message d'erreur par défaut invalid est "%value%" is not an integer..

sfValidatorNumber

Schéma de validateur : Non

Le validateur sfValidatorNumber valide un nombre (une chaîne que PHP est capable de comprendre avec la fonction floatval()) et convertit la valeur saisie en un type float.

Le message d'erreur par défaut invalid est "%value%" is not a number..

sfValidatorBoolean

Schéma de validateur : Non

Le validateur sfValidatorBoolean valide et renvoie une valeur booléenne true ou false.

sfValidatorChoice

Schéma de validateur : Non

Le validateur sfValidatorChoice valide si la valeur saisie fait partie d'une liste des valeurs attendues.

sfValidatorPass

Schéma de validateur : Non

Le validateur sfValidatorPass est un validateur fictif et retourne la valeur saisie telle quelle.

sfValidatorCallback

Schéma de validateur : Non

Le validateur sfValidatorCallback délègue la validation actuelle à un callback PHP.

Le callback est passé à l'instance du validateur actuel, la valeur saisie et un tableau d'arguments (à partir de l'option arguments) comme 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'),
));

Validateurs de date

sfValidatorDate

Schéma de validateur : Non

Le sfValidatorDate valide les dates et les dates/heures (dates/heures sont supportés par l'application de l'option with_time). Outre la validation du format d'une date, il peut appliquer une date valide minimum et maximum.

Le validateur accepte plusieurs types d'entrées :

• un tableau composé des clés suivantes : year, month, day, hour, minute et second
• une chaîne correspondante à l'expression régulière date_format si fournie (par exemple ~(?P<day>\d{2})/(?P<month>\d{2})/(?P<year>\d{4})~)
• une chaîne qui peut être analysée par la fonction PHP strtotime()
• un entier, représentant un timestamp

La valeur saisie est convertie en une date en appliquant les formats date_output ou datetime_output.

sfValidatorTime

Schéma de validateur : Non

Le sfValidatorTime valide une heure.

Le validateur accepte plusieurs types d'entrée :

• un tableau composé des clés suivantes : hour, minute et second
• une chaîne correspondante à l'expression régulière time_format si fournie
• une chaîne qui peut être analysée par la fonction PHP strtotime()
• un entier, représentant un timestamp

La valeur saisie est convertie en une heure en appliquant le format time_output.

sfValidatorDateTime

Schéma de validateur : Non

Le sfValidatorDateTime valide les dates avec l'heure.

C'est un raccourci de :

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

sfValidatorDateRange

Schéma de validateur : Non

Le sfValidatorDateTime valide une fourchette de dates.

Les validateurs from_date et to_date doivent être une instance de la classe sfValidatorDate.

Le message d'erreur invalid est "%value%" does not match the time format (%time_format%)..

Validateur de fichier

sfValidatorFile

Schéma de validateur : Non

Le validateur sfValidatorFile valide un fichier téléchargé.

Le validateur convertit le fichier téléchargé en une instance de la classe sfValidatedFile ou de l'option validated_file_class si elle est définie.

La catégorie mime-type web_images contient les mime-types suivants :

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

Si l'option mime_types est définie, le validateur a besoin d'un moyen pour tester le mime-type du fichier téléchargé. Le validateur est livré avec trois d'entre eux:

• guessFromFileinfo: Utilise la fonction finfo_open() (depuis l'extension PECL Fileinfo)
• guessFromMimeContentType: Utilise la fonction mime_content_type() (dépréciée)
• guessFromFileBinary: Utilise le fichier binaire (fonctionne seulement sur les systèmes *nix)

Le validateur fait correspondre les erreurs PHP comme suit :

• 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

Validateurs de logique

sfValidatorAnd

Schéma de validateur : Non

Le validateur sfValidatorAnd valide une valeur saisie si elle passe une liste de validateurs.

Le constructeur de sfValidatorAnd prend une liste de validateurs comme premier 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.')
);

Par défaut, le validateur lève un tableau de messages d'erreur émis par tous les validateurs intégrés. Il peut aussi lancer un message d'erreur unique si le message d'erreur invalid est défini comme une chaîne non vide, comme le montre l'exemple ci-dessus.

L'ordre des validateurs est significatif si l'option halt_on_error est définie sur true.

La liste des validateurs intégrés peut aussi être gérées à l'aide des méthodes getValidators() et addValidator().

sfValidatorOr

Schéma de validateur : Non

Le validateur sfValidatorOr valide une valeur saisie si elle passe au moins un validateur dans une liste.

Le constructeur de sfValidatorOr prend une liste de validateurs comme premier 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.')
);

Par défaut, le validateur lève un tableau de messages d'erreur émis par tous les validateurs intégrés. Il peut aussi lancer un message d'erreur unique si le message d'erreur invalid est défini comme une chaîne non vide, comme le montre l'exemple ci-dessus.

La liste des validateurs intégrés peut aussi être gérées à l'aide des méthodes getValidators() et addValidator().

sfValidatorSchema

Schéma de validateur : Oui

Le validateur sfValidatorSchema représente un validateur qui est composé de plusieurs champs. Un champ est tout simplement un validateur nommé :

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

Ce validateur accepte seulement un tableau comme valeur d'entrée et lève une InvalidArgumentException si ce n'est pas le cas.

Le validateur peut avoir un pré-validateur, qui est exécuté avant tous les autres validateurs, et un post-validateur, qui est exécuté sur le nettoyage des valeurs après tous les autres validateurs.

Le pré-validateur et le post-validateur sont eux-mêmes des schémas de validateur qui reçoivent toutes les valeurs. Ils peuvent être définis avec les méthodes setPreValidator() et setPostValidator() :

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

Le sfValidatorSchema peut être utilisé comme un tableau pour accéder aux validateurs intégrés :

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

Vous pouvez accéder à des validateurs intégrés du schéma de validateur en utilisant la notation de tableau :

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

L'erreur post_max_size est levée si la quantité de données soumises à un formulaire excède la valeur post_max_size du fichier php.ini.

sfValidatorSchemaCompare

Schéma de validateur : Oui

Le validateur sfValidatorSchemaCompare compare plusieurs valeurs à partir du tableau donné des valeurs saisies :

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

Les opérateurs disponibles sont les suivants :

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

Par défaut, le validateur génère une erreur globale. Si le throw_global_error est à true, une erreur pour le champ gauche est levée.

Les messages d'erreur invalid accepte les valeurs suivantes : %left_field%, %right_field%, et %operator%.

sfValidatorSchemaFilter

Schéma de validateur : Oui

Le validateur sfValidatorSchemaFilter convertit un non-validateur de schéma en un validateur de schéma. Il est parfois utile dans un contexte de post-validateur :

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

Validateurs I18n

sfValidatorI18nChoiceCountry

Schéma de validateur : Non

Le sfValidatorI18nChoiceCountry valide la valeur saisie si le code ISO 3166 du pays est valide.

sfValidatorI18nChoiceLanguage

Schéma de validateur : Non

Le sfValidatorI18nChoiceLanguage valide la valeur saisie si la langue est valide.

sfValidatorI18nChoiceTimezone

Schéma de validateur : Non

Le sfValidatorI18nChoiceTimezone valide la valeur saisie si le fuseau horaire est valide.

Validateurs Propel

sfValidatorPropelChoice

Schéma de validateur : Non

Le validateur sfValidatorPropelChoice valide la valeur saisie si elle est parmi la liste des enregistrements d'un modèle de Propel donné.

La liste des enregistrements peut être restreint en utilisant l'option criteria.

La valeur saisie doit être la clé primaire des enregistrements. Ceci peut être changé en passant l'option column.

sfValidatorPropelUnique

Schéma de validateur : Oui

Le validateur sfValidatorPropelUnique valide l'unicité d'une colonne ou d'un groupe de colonnes (option column) pour un modèle Propel.

Si l'unicité est sur plusieurs colonnes, l'erreur peut être lancée au niveau global en mettant l'option throw_global_error.

Doctrine Validators

sfValidatorDoctrineChoice

Schéma de validateur : Non

Le validateur sfValidatorDoctrineChoice valide la valeur saisie si elle est parmi la liste des enregistrements d'un modèle de Doctrine donné.

La liste des enregistrements peut être restreint en utilisant l'option query.

La valeur saisie doit être la clé primaire des enregistrements. Ceci peut être changé en passant l'option column.

sfValidatorDoctrineUnique

Schéma de validateur : Oui

Le validateur sfValidatorDoctrineUnique valide l'unicité d'une colonne ou d'un groupe de colonnes (option column) pour un modèle Doctrine.

Si l'unicité est sur plusieurs colonnes, l'erreur peut être lancée au niveau global en mettant l'option throw_global_error.