Funzione PHP date_create_from_format: Sintassi ed Esempi

La funzione date_create_from_format() analizza una stringa di data scritta nel tuo formato — non solo i formati che PHP cerca di indovinare — e restituisce un oggetto DateTime. Usala ogni volta che ricevi una data in un layout fisso e non standard (un export CSV, una API di terze parti, un modulo utente) e hai bisogno di leggerla in modo affidabile.

Questa pagina tratta la sintassi, esempi eseguibili, il parametro timezone, come rilevare i fallimenti di analisi e come la funzione si differenzia da strtotime() e date_parse_from_format().

Sintassi

date_create_from_format(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTime|false

• $format — il layout della stringa di input, scritto con gli stessi caratteri di formato della funzione date(). Ad esempio "Y-m-d H:i:s" corrisponde a "2023-03-02 17:30:45".
• $datetime — la stringa di data da analizzare. Il suo layout deve corrispondere a $format.
• $timezone — (opzionale) un DateTimeZone per l'oggetto risultante. Se omesso, viene utilizzato il timezone predefinito corrente (impostato tramite date_default_timezone_set()). Il parametro viene ignorato se $format contiene già un carattere timezone come e, O, P, o T.

Restituisce un oggetto DateTime in caso di successo, oppure false se la stringa non corrisponde al formato.

date_create_from_format() è l'alias procedurale del metodo statico DateTime::createFromFormat() — si comportano in modo identico.

Esempi

Analisi di una stringa di data standard

La funzione legge "2023-03-02 17:30:45" secondo "Y-m-d H:i:s" e restituisce un oggetto DateTime. Chiamando format() su di esso è possibile visualizzare nuovamente la data in qualsiasi layout si desideri.

Riformattare una data non standard

Qui l'input utilizza un giorno, un nome di mese a tre lettere e un anno a quattro cifre (j-M-Y). L'output viene visualizzato in ordine ISO (Y-m-d) — prova che una volta che una data è un oggetto DateTime sei libero di visualizzarla come preferisci.

Reimpostare l'ora con !

Se il tuo formato non ha campi orario, le parti mancanti vengono impostate per default all'ora, al minuto e al secondo correnti — il che raramente è quello che si vuole per un valore solo-data. Aggiungi ! come prefisso al formato per reimpostare tutti i campi non specificati all'epoca Unix (00:00:00):

<?php

$date = date_create_from_format('!Y-m-d', '2023-03-02');
echo $date->format('Y-m-d H:i:s'); // Output: 2023-03-02 00:00:00

Specificare un timezone

<?php

$tz = new DateTimeZone('Europe/Paris');
$date = date_create_from_format('Y-m-d H:i:s', '2023-03-02 17:30:45', $tz);
echo $date->format('Y-m-d H:i:s P'); // Output: 2023-03-02 17:30:45 +01:00

Il terzo argomento ancora la data analizzata all'ora di Parigi, quindi il token P riporta l'offset +01:00.

Gestione dei fallimenti di analisi

Quando la stringa non corrisponde al formato, la funzione restituisce false invece di lanciare un'eccezione. Verifica sempre questo caso e leggi DateTime::getLastErrors() per i dettagli:

<?php

$date = date_create_from_format('Y-m-d', 'not-a-date');

if ($date === false) {
    $errors = DateTime::getLastErrors();
    echo "Parse failed: {$errors['error_count']} error(s)\n";
    // Output: Parse failed: 3 error(s)
}

Poiché false è falsy, anche un semplice if (!$date) funziona — ma un controllo rigoroso con === false è più sicuro quando un valore vuoto potrebbe legittimamente significare qualcos'altro.

Confronto con altre funzioni di data

Usa date_create_from_format() quando il layout è fisso e vuoi un oggetto DateTime completo da manipolare. Usa strtotime() per stringhe informali in stile umano come "next Friday", e date_parse_from_format() quando hai bisogno solo dei numeri grezzi anno/mese/giorno senza costruire un oggetto.

Conclusione

date_create_from_format() trasforma una stringa in un layout arbitrario e conosciuto in un oggetto DateTime che puoi formattare, confrontare e spostare con il resto delle API di data di PHP. Ricorda di usare il prefisso ! per i valori solo-data, passa un DateTimeZone quando il timezone sorgente è importante e proteggi sempre contro il ritorno di false.

Esercizio