Appendice B - Validatori

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. Abbiamo anche incluso i validatori dei plugin sfPropelPlugin e sfDoctrinePlugin, in quanto questi plugin sono supportati dal team ufficiale e contengono alcuni validatori molto utili.

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 create un validatore, potete opzionalmente 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 è necessario.'));

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

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 argomenti e restituisce i valori ripuliti. Se avviene un errore di validazione, è restituito un errore di tipo sfValidatorError.

Le opzioni definite di default da sfValidatorBase sono le seguenti:

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

Si possono cambiare le stringhe di default usate per gli errori di required e invalid, invocando rispettivamente i metodi setRequiredMessage() e setInvalidMessage(). Questo va fatto prima che qualsiasi validatore sia caricato, ad esempio nel metodo setup():

public function setup()
{
sfValidatorBase::setRequiredMessage('Questo valore è obbligatorio.');
sfValidatorBase::setInvalidMessage('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.

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

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

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

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

Validatori semplici

sfValidatorString

Schema validator: No

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

sfValidatorRegex

Schema validator: No

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

sfValidatorEmail

Schema validator: No

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

sfValidatorUrl

Schema validator: No

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

sfValidatorInteger

Schema validator: No

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

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

sfValidatorNumber

Schema validator: 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.

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

sfValidatorBoolean

Schema validator: No

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

sfValidatorChoice

Schema validator: No

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

sfValidatorPass

Schema validator: No

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

sfValidatorCallback

Schema validator: No

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

Al callback sono passati come argomenti l'istanza del validatore, i valori grezzi e un array di argomenti (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'),
));

Validatori di date

sfValidatorDate

Schema validator: 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.

sfValidatorTime

Schema validator: 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.

sfValidatorDateTime

Schema validator: No

Il validatore sfValidatorDateTime controlla le date con gli orari.

È una scorciatoia per:

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

sfValidatorDateRange

Schema validator: No

Il validatore sfValidatorDateTime controlla intervalli di date.

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

Schema validator: 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.

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)

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

Schema validator: No

Il validatore sfValidatorAnd controlla un valore grezzo se 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 ad una stringa non vuota, come mostrato nell'esempio precedente.

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

Schema validator: 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 ad 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

Schema validator: 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(),
));

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

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

Schema validator: Sì

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

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

Gli operatori disponibili sono i seguenti:

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

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

Schema validator: Sì

Il validatore sfValidatorSchemaFilter converte un validatore di tipo non-schema ad 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

Schema validator: No

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

sfValidatorI18nChoiceLanguage

Schema validator: No

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

Validatori Propel

sfValidatorPropelChoice

Schema validator: 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.

sfValidatorPropelChoiceMany

Schema validator: No

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

Questo validatore è una scorciatoia per:

$v = new sfValidatorPropelChoice(array('multiple' => true));

sfValidatorPropelUnique

Schema validator: 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.

Validatori Doctrine

sfValidatorDoctrineChoice

Schema validator: 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.

sfValidatorDoctrineChoiceMany

Schema validator: No

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

Questo validatore eredita tutte le opzioni dal validatore sfValidatorDoctrineChoice.

sfValidatorDoctrineUnique

Schema validator: 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.