Caution: You are browsing the legacy symfony 1.x part of this website.

Appendice B - Validatori

1.4
Symfony version
1.2
Language

Introduzione

Il framework dei form di symfony viene rilasciato con un gran numero di validatori utili. Questi validatori coprono la maggior parte delle necessità di molti progetti. Questo capitolo descrive i validatori standard distribuiti con symfony. Sono inclusi anche i validatori dei plugin sfPropelPlugin e sfDoctrinePlugin, in quanto questi plugin sono supportati dal team ufficiale e contengono alcuni validatori molto utili.

tip

Anche se non si usa il framework MVC di symfony, si possono usare i validatori definiti nei plugin sfFormExtraPlugin, sfPropelPlugin e sfDoctrinePlugin, inserendo le cartelle validator/ nel proprio progetto.

Prima di approfondire ogni validatore in dettaglio, vediamo cosa hanno tutti i validatori in comune.

La classe sfValidatorBase

Tutti i validatori di symfony ereditano dalla classe base sfValidator, che mette a disposizione alcune funzionalità standard.

I validatori hanno due scopi: pulire e validare un valore grezzo.

Quando si crea un validatore, opzionalmente si possono passare opzioni e messaggi di errore come parametri:

$v = new sfValidatorString(
  array('required' => true),
  array('required' => 'Questo valore è necessario.')
);

Opzioni e messaggi di errore possono essere anche impostati usando i metodi setOptions() e setMessages():

$v = new sfValidatorString();
$v->setOptions(array('required' => true));
$v->setMessages(array('required' => 'Questo valore è obbligatorio.'));

I metodi setOption() e setMessage() permettono di impostare una singola opzione o un singolo messaggio di errore:

$v = new sfValidatorString();
$v->setOption('required', true);
$v->setMessage('required', 'Questo valore è obbligatorio.');

Un valore grezzo può essere validato invocando il metodo clean():

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

Il metodo clean() accetta i valori grezzi come parametri e restituisce i valori ripuliti. Se avviene un errore di validazione, è restituito un errore di tipo sfValidatorError.

note

I validatori sono stateless, il che significa che una singola istanza di un validatore può controllare tutti i valori di input che si vuole.

Le opzioni definite di default da sfValidatorBase sono le seguenti:

Opzione Errore Descrizione
required required true se il valore è obbligatorio, false altrimenti (true di default)
trim n/a true se il valore deve essere privato di spazi, false altrimenti (false di default)
empty_value n/a restituisce una stringa vuota quando il valore non è obbligatorio

I messaggi di errore di default definiti da sfValidatorBase sono i seguenti:

Errore Descrizione
required Il messaggio di errore usato quando il valore grezzo è vuoto e obbligatorio (Required. di default).
invalid Un messaggio di errore generico restituito quando un errore viene riconosciuto (Invalid. di default).

Si possono cambiare le stringhe predefinite usate per gli errori di required e invalid, invocando il metodo setDefaultMessage(). Occorre farlo prima che qualsiasi validatore sia caricato, ad esempio nel metodo setup():

public function setup()
{
  sfValidatorBase::setDefaultMessage('require', 'Questo valore è obbligatorio.');
  sfValidatorBase::setDefaultMessage('invalid', 'Questo valore non è valido.');
  parent::setup();
}

I messaggi di errore possono contenere dei segnaposto. Questi sono delle stringhe di testo racchiuse tra il carattere %. I segnaposto sono sostituiti a runtime. Tutti i messaggi di errore hanno accesso alle variabili grezze usando il segnaposto %value%. Ogni messaggio di errore può, inoltre, definire un segnaposto specifico.

note

Nella seguente sezione, il segnaposto predefinito %value% non è menzionato in quanto è sempre disponibile.

Per alcuni validatori è necessario sapere qual è il set di caratteri utilizzato dai valori grezzi. Normalmente il set di caratteri usato è UTF-8, ma può essere sostituito usando il metodo setCharset():

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

note

Se si usano i validatori all'interno del framework MVC di symfony, il set di caratteri è configurato automaticamente con quello definito nel file settings.yml.

Validatori Schema

Un validatore schema è un contenitore di validatori che può ospitare uno o più validatori differenti.

Quando viene intercettato un errore, il validatore schema restituisce un'eccezione sfValidatorErrorSchema.

Nelle prossime sezioni i validatori saranno raggruppati in categorie.

Validatori

Validatori semplici

sfValidatorString

Validatore schema*: No

Il validatore sfValidatorString controlla che una variabile grezza sia una stringa e la restituisce come tale.

Opzione Errore Descrizione
max_length max_length La lunghezza massima della stringa
min_length min_length La lunghezza minima della stringa
Errore Segnaposti Valori predefiniti
max_length max_length "%value%" is too long (%max_length% characters max).
min_length min_length "%value%" is too short (%min_length% characters min).

warning

Questo validatore necessita che l'estensione di PHP mb_string sia installata per poter funzionare correttamente. Se installata, la lunghezza della stringa verrà calcolata usando la funzione mb_strlen(); altrimenti verrà utilizzata la funzione strlen(), che non restituisce la reale lunghezza se all'interno della stringa sono presenti caratteri non-ASCII.

sfValidatorRegex

Validatore schema*: No

Il validatore sfValidatorRegex controlla che una stringa verifichi una certa espressione regolare.

Opzione Errore Descrizione
pattern invalid Uno schema di espressione regolare PCRE o un'istanza di sfCallable che lo restituisca
must_match invalid Se false, l'espressione regolare non deve essere soddisfatta

sfValidatorEmail

Validatore schema*: No

Il validatore sfValidatorEmail può controllare gli indirizzi email ed eredita da sfValidatorRegex.

sfValidatorUrl

Validatore schema*: No

Il validatore sfValidatorUrl può validare indirizzi, URL HTTP e URL FTP. Eredita da sfValidatorRegex.

Opzione Errore Descrizione
protocols invalid Protocolli consentiti. Valore predefinito: array('http', 'https', 'ftp', 'ftps')

sfValidatorInteger

Validatore schema*: No

Il validatore sfValidatorInteger controlla che il valore immesso sia di tipo intero e lo converte come tale.

Opzione Errore Descrizione
max max Il massimo numero accettabile
min min Il minimo numero accettabile
Errore Segnaposti Valori predefiniti
max max "%value%" must be less than %max%.
min min "%value%" must be greater than %min%.

Il messaggio di errore predefinito per invalid è "%value%" is not an integer..

sfValidatorNumber

Validatore schema*: No

Il validatore sfValidatorNumber controlla un numero (o una stringa che PHP possa tradurre tramite la funzione floatval()) e lo converte in un tipo float.

Opzione Errore Descrizione
max max Il massimo numero da accettabile
min min Il minimo numero accettabile
Errore Segnaposti Valori predefiniti
max max "%value%" must be less than %max%.
min min "%value%" must be greater than %min%.

Il messaggio di errore predefinito per invalid è "%value%" is not a number..

sfValidatorBoolean

Validatore schema*: No

Il validatore sfValidatorBoolean controlla che il dato inserito sia di tipo booleano e restituisce i valori true o false.

Opzione Errore Descrizione
true_values n/a La lista dei valori considerati veri (di default: true, t, yes, y, on, 1)
false_values n/a La lista dei valori considerati falsi (di default: false, f, no, n, off, 0)

sfValidatorChoice

Validatore schema*: No

Il validatore sfValidatorChoice controlla se i valori inseriti appartengono a una lista di valori definiti.

Opzione Errore Descrizione
choices n/a L'array dei valori definiti (obbligatorio)
multiple n/a true se il tag select deve permettere la spunta di valori diversi contemporaneamente
min n/a Numero minimo di valori da selezionare (se multiple è true)
max n/a Numero massimo di valori da selezionare (se multiple è true)

note

Il confronto è fatto dopo che i valori grezzi sono stati trasformati in stringhe.

sfValidatorPass

Validatore schema*: No

Il validatore sfValidatorPass è un validatore fittizio che restituisce i valori di input così come sono.

sfValidatorCallback

Validatore schema*: No

Il validatore sfValidatorCallback delega il controllo a un callback di PHP.

Al callback sono passati come parametri l'istanza del validatore, i valori grezzi e un array di parametri (dall'opzione 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'),
));
Opzione Errore Descrizione
callback n/a Un callback valido di PHP (obbligatorio)
arguments n/a Un array di parametri da passare al callback

Validatori di date

sfValidatorDate

Validatore schema*: No

Il validatore sfValidatorDate controlla date semplici e con orari (le date con orari sono abilitate con l'opzione with_time). Oltre che controllare la validità del formato della data può forzare un intervallo di date su cui controllare.

Il validatore accetta diversi tipi di parametri:

  • un array composto dalle seguenti chiavi: year, month, day, hour, minute e second
  • una stringa che combacia con l'espressione regolare date_format, se passata
  • una stringa che può essere utilizzata dalla funzione strtotime() di PHP
  • un intero che rappresenta un timestamp

I valori grezzi sono convertiti in una data utilizzando il formato specificato nei parametri date_output o datetime_output.

Opzione Errore Descrizione
date_format bad_format Un'espressione regolare con cui le date inserite devono combaciare
with_time n/a true se il validatore deve restituire un orario, altrimenti false
date_output n/a Il formato da usare quando l'output deve essere una data (il valore predefinito è Y-m-d)
datetime_output n/a Il formato da usare quando l'output deve essere una data con orario (il valore predefinito è Y-m-d H:i:s)
date_format_error n/a Il formato data da utilizzare quando viene mostrato il messaggio d'errore bad_format (usa date_format se non specificato)
max max La massima data permessa (come timestamp)
min min La minima data permessa (come timestamp)
date_format_range_error n/a Il formato data da utilizzare quando viene mostrato il messaggio d'errore per min/max (il valore predefinito è d/m/Y H:i:s)

note

Le opzioni di date_output e datetime_output possono usare qualsiasi formato riconosciuto dalla funzione date() di PHP.

Errore Segnaposti Valori predefiniti
bad_format date_format "%value%" does not match the date format (%date_format%).
min min The date must be after %min%.
max max The date must be before %max%.

sfValidatorTime

Validatore schema*: No

Il validatore sfValidatorTime controlla i formati orario.

Il validatore accetta diverse tipologie di input:

  • un array composto dalle seguenti chiavi: hour, minute e second
  • una stringa che combacia con l'estpressione regolare time_format, se passata
  • una stringa che può essere utilizzata dalla funzione strtotime() di PHP
  • un intero che rappresenta un timestamp

I valori grezzi sono convertiti in una data utilizzando il formato specificato nei parametri date_output o datetime_output.

Opzione Errore Descrizione
time_format bad_format Un'espressione regolare con cui le date inserite devono combaciare
time_output n/a Il formato da usare quando l'output deve essere un orario (il valore predefinito è H:i:s)
time_format_error n/a Il formato data da utilizzare quando viene mostrato il messaggio d'errore bad_format (usa date_format se non specificato)

note

Le opzioni di time_output possono usare qualsiasi formato riconosciuto dalla funzione date() di PHP.

Errore Segnaposti Valori predefiniti
bad_format date_format "%value%" does not match the time format (%time_format%).

sfValidatorDateTime

Validatore schema*: No

Il validatore sfValidatorDateTime controlla le date con gli orari.

È una scorciatoia per:

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

sfValidatorDateRange

Validatore schema*: No

Il validatore sfValidatorDateTime controlla intervalli di date.

Opzione Errore Descrizione
from_date invalid Il validatore dalla data (obbligatorio)
to_date invalid Il validatore alla data (obbligatorio)

I validatori from_date e to_date devono essere istanze della classe sfValidatorDate.

Il messaggio di errore invalid è "%value%" does not match the time format (%time_format%)..

Validatore di file

sfValidatorFile

Validatore schema*: No

Il validatore sfValidatorFile controlla i file caricati.

Il validatore converte i file caricati in un'istanza della classe sfValidatedFile, o dell'opzione validated_file_class se è impostata.

Opzione Errore Descrizione
max_size max_size La dimensione massima del file
mime_types mime_types Array di mime types permessi o categoria (categorie disponibili: web_images)
mime_type_guessers n/a Un array di mime type guesser PHP callables (deve restituire un mime type o null)
mime_categories n/a Un array di categorie mime type (web_images è definita di default)
path n/a Il percorso dove salvare il file - come utilizzato dalla classe sfValidatedFile (opzionale)
validated_file_class n/a Nome della classe che gestisce il file caricato (opzionale)

La categoria mime-type web_images contiene i seguenti mime-types:

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

Se l'opzione mime_types è impostata, il validatore ha bisogno di un sistema per testare il mime-type del file caricato. Il validatore offre tre modi per fare questo:

  • guessFromFileinfo: Usa la funzione finfo_open() (dall'estensione PECL Fileinfo)
  • guessFromMimeContentType: Usa la funzione mime_content_type() (deprecata)
  • guessFromFileBinary: Usa il file binario (funziona solo sui sistemi *nix)
Errore Segnaposti Valori predefiniti
max_size %size%, %max_size% File is too large (maximum is %max_size% bytes)
mime_types %mime_types%, %mime_type% Invalid mime type (%mime_type%).
partial The uploaded file was only partially uploaded.
no_tmp_dir Missing a temporary folder.
cant_write Failed to write file to disk.
extension File upload stopped by extension.File upload stopped by extension.

Il validatore mappa gli errori PHP nel modo seguente:

  • 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

Validatori logici

sfValidatorAnd

Validatore schema*: No

Il validatore sfValidatorAnd controlla se un valore grezzo passa una lista di validatori.

Il costruttore di sfValidatorAnd accetta una lista di validatori come primo parametro:

$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.')
);

Di default, il validatore lancia un array di messaggi d'errore lanciati da tutti i validatori inclusi. Può inoltre lanciare un singolo messaggio d'errore se il messaggio d'errore invalid è impostato a una stringa non vuota, come mostrato nell'esempio precedente.

Opzione Errore Descrizione
halt_on_error n/a Indica se fermarsi al primo errore o meno (false di default)

L'ordine dei validatori è importante se l'opzione halt_on_error è impostata a true.

La lista di validatori inclusi può essere inoltre gestita usando i metodi getValidators() e addValidator().

sfValidatorOr

Validatore schema*: No

Il validatore sfValidatorOr controlla un valore grezzo se passa almeno un validatore in una lista.

Il costruttore sfValidatorOr accetta una lista di validatori come primo parametro:

$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.')
);

Di default il validatore lancia un array di messaggi d'errore lanciati da tutti i validatori inclusi. Può inoltre lanciare un singolo messaggio d'errore se il messaggio d'errore invalid è impostato a una stringa non vuota, come mostrato nell'esempio precedente.

La lista di validatori inclusi può essere inoltre gestita usando i metodi getValidators() e addValidator().

sfValidatorSchema

Validatore schema*: Sì

Il validatore sfValidatorSchema rappresenta un validatore composto da diversi campi. Un campo è semplicemente un validatore a cui è assegnato un nome:

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

note

Un form è definito dal validatore schema della classe sfValidatorSchema.

Questo validatore accetta solamente un array come valore di input e lancia una InvalidArgumentException se questo non si verifica.

Il validatore può avere un pre-validatore, che viene eseguito prima di tutti gli altri validatori, e un post-validatore, che viene eseguito sui valori puliti dopo tutti gli altri validatori.

I validatori pre-validatore e post-validatore sono a loro volta dei validatori schema che ricevono tutti i valori. Possono essere impostati con i metodi setPreValidator() e setPostValidator():

$v->setPostValidator(
  new sfValidatorCompare('password', '==', 'password_again')
);
Opzione Errore Descrizione
allow_extra_fields extra_fields se false, il validatore aggiunge un errore se campi extra vengono inseriti nell'array dei valori di input (default impostato a false)
filter_extra_fields n/a se true, il validatore filtra i campi extra dall'array restituito con i valori puliti (default impostato a true)
Errore Segnaposti Valori predefiniti
extra_fields %field% Unexpected extra form field named "%field%".
post_max_size The form submission cannot be processed. It probably means that you have uploaded a file that is too big.

Il validatore sfValidatorSchema può essere usato come un array per accedere ai validatori inclusi:

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

Si può accedere ai validatori schema contenuti usando la notazione degli array:

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

sfValidatorSchemaCompare

Validatore schema*: Sì

Il validatore sfValidatorSchemaCompare compara diversi valori dell'array di dati grezzi passato:

$v = new sfValidatorCompare('password', '==', 'password_again');
Opzione Errore Descrizione
left_field n/a Il nome del campo a sinistra
operator n/a L'operatore di comparazione
right_field n/a Il nome del campo a destra
throw_global_error n/a Se lanciare un errore globale (false di default) o un errore legato al campo a sinistra

Gli operatori disponibili sono i seguenti:

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

Di default il validatore lancia un errore globale. Se throw_global_error è impostato a true, viene lanciato un errore per il campo a sinistra.

Il messaggio di errore invalid accetta i seguenti valori: %left_field%, %right_field% e %operator%.

sfValidatorSchemaFilter

Validatore schema*: Sì

Il validatore sfValidatorSchemaFilter converte un validatore di tipo non-schema a un validatore di tipo schema. A volte è utile nell'ambito dei post validatori:

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

Validatori I18n

sfValidatorI18nChoiceCountry

Validatore schema*: No

Il validatore sfValidatorI18nChoiceCountry controlla che un valore grezzo rientri in un codice paese valido secondo ISO 3166.

Opzione Errore Descrizione
countries invalid Un array di codice paese da usare (ISO 3166)

sfValidatorI18nChoiceLanguage

Validatore schema*: No

Il validatore sfValidatorI18nChoiceLanguage controlla che un valore grezzo rientri tra le lingue valide.

Opzione Errore Descrizione
languages invalid Un array di lingue da usare

sfValidatorI18nChoiceTimezone

Validatore schema*: No

Il vadlidator sfValidatorI18nChoiceTimezone verifica che il valore grezzo sia un fuso orario valido.

Opzione Errore Descrizione
languages invalid Un array di lingue da usare

Validatori Propel

sfValidatorPropelChoice

Validatore schema*: No

Il validatore sfValidatorPropelChoice controlla che un valore grezzo sia nella lista di record di un dato modello Propel.

La lista di record può essere ristretta usando l'opzione criteria.

Il valore grezzo deve essere la chiave primaria dei record. Questo può essere cambiato utilizzando l'opzione column.

Opzione Errore Descrizione
model n/a La classe del modello (obbligatorio)
criteria n/a Un criterio da usare per recuperare gli oggetti
column n/a Il nome della colonna (nullo di default, significa che viene usata la chiave primaria) - deve avere lo stesso formato del nome del campo
connection n/a La connessione Propel da usare (null di default)
multiple n/a true se il tag select deve permettere selezioni multiple

note

Questo validatore non funziona per modelli con chiave primaria composta.

sfValidatorPropelUnique

Validatore schema*: Sì

Il validatore sfValidatorPropelUnique controlla l'unicità di una colonna o di un gruppo di colonne (opzione column) per un modello Propel.

Se l'unicità è su più colonne, l'errore può essere globale impostando l'opzione throw_global_error.

Opzione Errore Descrizione
model n/a La classe del modello (obbligatorio)
column n/a Il nome della colonna unica con formato del nome Propel (obbligatorio). Se l'unicità è per più colonne si può passare un array con i nomi dei campi
field n/a Nome del campo usato dal form, diverso dal nome della colonna
primary_key n/a Il nome della colonna per la chiave primaria in formato Propel (opzionale, verrà ricavato se non passato). Si può passare un array se la tabella ha più chiavi primarie
connection n/a La connessione Propel da usare (null di default)
throw_global_error n/a Se lanciare un errore globale (false di default) o un errore legato al primo dei campi specificati nell'opzione column

Validatori Doctrine

sfValidatorDoctrineChoice

Validatore schema*: No

Il validatore sfValidatorDoctrineChoice controlla che un valore grezzo sia nella lista di record di un dato modello Doctrine.

La lista di record può essere ristretta usando l'opzione query.

Il valore grezzo deve essere la chiave primaria dei record. Questo può essere cambiato utilizzando l'opzione column.

Opzione Errore Descrizione
model n/a La classe del modello (obbligatorio)
alias n/a L'alias del componente root usato nella query
query n/a La query da usare per recuperare gli oggetti
column n/a Il nome della colonna (null di default, viene usata la chiave primaria) - deve avere lo stesso formato del nome del campo
connection n/a La connessione Doctrine da usare (null di default)

note

Questo validatore non funziona per modelli con chiave primaria composta.

sfValidatorDoctrineUnique

Validatore schema*: Sì

Il validatore sfValidatorDoctrineUnique controlla l'unicità di una colonna o di un gruppo di colonne (opzione column) per un modello Doctrine.

Se l'unicità è su più colonne, l'errore può essere lanciato globalmente impostando l'opzione throw_global_error.

Opzione Errore Descrizione
model n/a La classe del modello (obbligatorio)
column n/a Il nome della colonna unica con formato del nome Doctrine (obbligatorio). Se l'unicità è per più colonne si può passare un array con i nomi dei campi
primary_key n/a Il nome della colonna per la chiave primaria in formato Doctrine (opzionale, verrà ricavato se non passato). Si può passare un array se la tabella ha più chiavi primarie
connection n/a La connessione Doctrine da usare (null di default)
throw_global_error n/a Se lanciare un errore globale (false di default) o un errore legato al primo dei campi specificati nell'opzione column