Tipo di campo date

Un campo che consente all’utente di modificare le informazioni sulle date tramite una serie di diversi elementi HTML.

I dati sottostanti usati per questo campo possono essere un oggetto DateTime, una stringa, un timestamp o un array. Se l’opzione input è impostata correttamente, il campo si occuperà di tutti i dettagli.

Il campo può essere reso come una singola casella di testo, tre caselle di testo (mese, giorno e anno) oppure tre select (vedere l’opzione widget_).

Tipo di dato sottostante uno tra DateTime, stringa, timestamp o array (vedere opzione input)
Reso come singolo campo testo o tre campi select
Opzioni
Opzioni ridefinite
Opzioni ereditate
Tipo genitore form
Classe Symfony\Component\Form\Extension\Core\Type\DateType

Uso di base

Questo tipo di campo è altamente configurabile, ma facile da usare. Le opzioni più importanti sono input e widget.

Si supponga di avere un campo publishedAt, la cui data sottostante sia un oggetto DateTime. Il codice seguente configura il tipo date per tale campo come tre diversi campi di scelta:

$builder->add('publishedAt', 'date', array(
    'input'  => 'datetime',
    'widget' => 'choice',
));

L’opzione input deve essere cambiata per corrispondere al tipo di dato della data sottostante. Per esempio, se i dati del campo publishedAt fossero un timestamp, si dovrebbe impostare input a timestamp:

$builder->add('publishedAt', 'date', array(
    'input'  => 'timestamp',
    'widget' => 'choice',
));

Il campo supporta anche array e string come valori validi dell’opzione input.

Opzioni del campo

days

tipo: array predefinito: da 1 a 31

Lista di giorni disponibili per il tipo di campo day. Questa opzione è rilevante solo quando l’opzione widget è impostata a choice:

'days' => range(1, 31)

placeholder

Nuovo nella versione 2.6: L’opzione placeholder è stata introdotta in Symfony 2.6 al posto di placeholder, che è disponibile prima di 2.6.

tipo: stringa o array

Se l’opzione del widget è choice, il campo sarà rappresentato come una serie di select. L’opzione placeholder può essere usata per aggiungere una voce vuota in cima a ogni select:

$builder->add('dueDate', 'date', array(
    'placeholder' => '',
));

In alternativa, si può specificare una stringa da mostrare per ogni voce vuota:

$builder->add('dueDate', 'date', array(
    'placeholder' => array('year' => 'Anno', 'month' => 'Mese', 'day' => 'Giorno')
));

format

tipo: intero o stringa predefinito: IntlDateFormatter::MEDIUM

Opzione passata alla classe IntlDateFormatter, usata per trasformare il dato inserito dall’utente nel formato appropriato. Questo è molto importante quando l’opzione widget è single_text e definisce il modo in cui il dato viene trasformato. Per impostazione predefinita, il formato è determinato in base al locale dell’utente; si può sovrascriverlo passando il formato come stringa.

Per maggiori informazioni sui formati validi, si veda sintassi del formato Date/Time. Per esempio, per rendere un singolo campo testuale, che si aspetta che l’utente inserisca yyyy-MM-dd, usare le seguenti opzioni:

$builder->add('date_created', 'date', array(
    'widget' => 'single_text',
    'format' => 'yyyy-MM-dd',
));

html5

Nuovo nella versione 2.6: L’opzione html5 è stata introdotta in Symfony 2.6.

tipo: booleano predefinito: true

Se impostata a true (valore predefinito), userà il tipo HTML5 (date, time o datetime) per rendere il campo. Se impostata a false, userà il tipo text.

Utile quando si vuole usare un calendario JavaScript personalizzato, che spesso richiede un tipo text invece di un tipo HTML5.

input

tipo: stringa predefinito: datetime

Il formato in ingresso dei dati, cioè il formato in cui la data è memorizzata nell’oggetto sottostante. Valori validi sono:

  • stringa (p.e. 2011-06-05)
  • datetime (un oggetto DateTime)
  • array (p.e. array('year' => 2011, 'month' => 06, 'day' => 05))
  • timestamp (p.e. 1307232000)

Anche il valore proveniente dal form sarà normalizzato in tale formato.

model_timezone

tipo: stringa predefinito: fuso orario di sistema

Fuso orario con cui vengono salvati i dati ricevuti. Deve essere uno dei fusi orari supportati da PHP

months

tipo: array predefinito: da 1 a 12

Lista di ore disponibili per il tipo di campo month. Questa opzione è rilevante solo se l’opzione widget è impostata a choice.

view_timezone

tipo: stringa predefinito: fuso orario di sistema

Fuso orario con cui i dati vanno mostrati all’utente (e quindi anche i dati che l’utente invia). Deve essere uno dei fusi orari supportati da PHP

widget

tipo: stringa predefinito: choice

Il modo di base in cui questo campo andrebbe reso. Può essere uno tra:

  • choice: rende tre campi select. L’ordine dei select è definito nell’opzione format.
  • text: rende tre campi testuali (mese, giorno, anno).
  • single_text: rende un singolo campo testuale. I dati inseriti dall’utente sono validati in base all’opzione format.

Attenzione

Se si usa timestamp, DateType è limitato a date tra il 13 dicembre 1901 20:45:54 GMT e il 19 gennaio 2038 03:14:07 GMT su sistemi a 32bit. Ciò è dovuto a un limite in PHP stesso.

years

tipo: array predefinito: da 5 anni prima a 5 dopo l’anno corrente

Lista di ore disponibili per il tipo di campo year. Questa opzione è rilevante solo se l’opzione widget è impostata a choice.

Opzioni ridefinite

by_reference

predefinito: false

Le classi DateTime sono trattate come oggetti immutabili.

error_bubbling

predefinito: false

Opzioni ereditate

Queste opzioni sono ereditate dal tipo form:

data

tipo: mixed predefinito: Predefinito al campo dell’oggetto sottostante (se presente)

Quando si crea un form, ogni campo inizialmente mostra il valore della proprietà corrispondente dell’oggetto del dominio del form (se un oggetto è legato al form). Se si vuole sovrascrivere il valore iniziale per il form o solo per un singolo campo, lo si può fare con l’opzione data:

$builder->add('token', 'hidden', array(
    'data' => 'abcdef',
));

disabled

type: booleano default: false

Se non si vuole che l’utente modifichi il valore di un campo, si può impostare questa opzione a true. Ogni valore inserito sarà ignorato.

error_mapping

tipo: array predefinito: empty

Questa opzione consente di modificare il bersaglio di un errore di validazione.

Si immagini di avere un metodo personalizzato, di nome matchingCityAndZipCode, che valida se una città e un codice postale corrsispondano. Purtroppo non c’è un campo “matchingCityAndZipCode” nel form, quindi tutto ciò che può fare Symfony è mostrare l’errore in cima al form stesso.

Con la mappatura personalizzata degli errori, si può fare meglio: mappare l’errore al campo della città, in modo che sia mostrato accanto a esso:

public function setDefaultOptions(OptionsResolverInterface $resolver)
{
    $resolver->setDefaults(array(
        'error_mapping' => array(
            'matchingCityAndZipCode' => 'city',
        ),
    ));
}

Ecco le regole per i lati destro e sinistro della mappatura:

  • I lato sinistro contiene i percorsi delle proprietà.
  • Se la validazione è generata su una proprietà o metodo di una classe, il suo percorso è semplicemente “nomeProprietà”.
  • Se la validazione è generata su un elemento di un array od oggetto ArrayAccess, il percorso è [nomeIndice].
  • Si possono costruire percorsi innestati, concatenandoli, separando le proprietà con dei punti. Per esempio: addresses[work].matchingCityAndZipCode
  • Anche il lato sinistro della mappatura accetta un punto ., che si riferisce al campo stesso. Questo significa che un errore aggiunto al campo è aggiunto invece al dato campo innnestato.
  • Il lato destro contiene semplicemente i nomi dei campi nel form.

inherit_data

Nuovo nella versione 2.3: Questa opzione era nota come virtual prima di Symfony 2.3.

tipo: booleano predefinito: false

Questa opzione determina se il form erediterà dati dal form genitore. Può essere utile se si ha un insieme di campi duplicati in form multipli. Vedere Ridurre la duplicazione di codice con “inherit_data”.

invalid_message

tipo: stringa predefinito: This value is not valid

Questo è il messaggio di errore di validazione usato quando i dati inseriti sono determinati dalla validazione interna di un tipo di campo. Questo può accadere, per esempio, se l’utente inserire una stringa dentro un campo time che non può essere convertito in un tempo reale. Per i normali messaggi di validazione (come quando si imposta la lunghezza minima per un campo), impostare i messaggi di validazione con le proprie regole di validazione (riferimento).

invalid_message_parameters

tipo: array predefinito: array()

Impostando l’opzione invalid_message, si potrebbe aver bisogno di includere alcune variabili nella stringa. Lo si può fare aggiungendo dei segnaposto all’opzione e includendo le variabili in questa opzione:

$builder->add('un_campo', 'un_tipo', array(
    // ...
    'invalid_message'            => 'Valore inserito non valido: deve includere almeno %num% caratteri',
    'invalid_message_parameters' => array('%num%' => 6),
));

mapped

tipo: booleano

Se si vuole che il campo sia ignorato durante la lettura o la scrittura dell’oggetto, si può impostare l’opzione mapped a false

read_only

tipo: booleano predefinito: false

Se questa opzione è true, il campo sarà reso con l’attributo disabled, in modo che il campo non sia modificabile.

Variabili del campo

Variabile Tipo Uso
widget mixed Il valore dell’opzione widget.
type string Presente solo quando widget è single_text e HTML5 è attivo, contiene il tipo di input (datetime, date o time).
date_pattern string Una stringa con il formato di data.