Analisi delle date in PHP

Le date spesso arrivano come semplici stringhe — da un campo di un modulo, un file CSV o una risposta API — e PHP non ha modo di sapere come sono strutturate a meno che non glielo si dica. La funzione date_parse_from_format() permette di analizzare una stringa di data secondo un formato esplicito e di esaminare il risultato, inclusi eventuali errori o avvisi. Questa pagina spiega come funziona la funzione, come interpretare il valore restituito, come validare l'input e quando è preferibile usare uno strumento diverso come DateTime o strtotime().

Cosa significa analizzare una data

L'analisi delle date è il processo che trasforma una stringa come "2023-03-03" in dati strutturati — anno, mese, giorno e così via — con cui il programma può lavorare. La parte difficile è l'ambiguità: 03/04/2023 potrebbe essere il 4 marzo o il 3 aprile a seconda della convenzione, e 2023-13-45 sembra una data ma non è valida.

date_parse_from_format() elimina questa ambiguità richiedendo di specificare il formato esatto in anticipo. Legge la stringa seguendo rigorosamente quel formato e comunica cosa ha trovato, così puoi decidere se l'input era valido.

La funzione date_parse_from_format()

date_parse_from_format() analizza una stringa di data usando un formato specifico e restituisce un array associativo che descrive la data analizzata: anno, mese, giorno, ora, minuto, secondo, oltre ad avvisi ed errori raccolti durante la lettura della stringa.

Sintassi

date_parse_from_format(string $format, string $datetime): array

• $format — una stringa di formato che usa gli stessi segnaposto di date(), ad esempio Y-m-d per 2023-03-03 oppure d/m/Y per 03/03/2023.
• $datetime — la stringa di data da analizzare.

La funzione restituisce sempre un array; non lancia mai eccezioni. Per sapere se l'analisi è riuscita è necessario controllare le chiavi error_count e warning_count.

Un esempio base

L'output di questo codice sarà:

Array
(
    [year] => 2023
    [month] => 3
    [day] => 3
    [hour] => 10
    [minute] => 30
    [second] => 0
    [fraction] => 
    [warning_count] => 0
    [warnings] => Array()
    [error_count] => 0
    [errors] => Array()
    [is_localtime] => 
    [zone_type] => 1
    [zone] => -14400
    [is_dst] => 
)

La funzione ha analizzato "2023-03-03 10:30:00" secondo il formato Y-m-d H:i:s e ha popolato ciascun componente. Puoi leggere i singoli valori direttamente dall'array, ad esempio $date_array['year'] o $date_array['month']. Quando un componente è assente dalla stringa di formato, il suo valore viene restituito come false (visualizzato come valore vuoto da print_r).

Analisi di formati personalizzati

I segnaposto del formato sono gli stessi usati da date(), quindi qualsiasi layout tu possa produrre puoi anche analizzarlo. L'esempio seguente legge una data in stile europeo giorno/mese/anno:

<?php

$result = date_parse_from_format("d/m/Y", "03/03/2023");

echo "Day:   {$result['day']}\n";
echo "Month: {$result['month']}\n";
echo "Year:  {$result['year']}\n";

Questo stampa:

Day:   3
Month: 3
Year:  2023

Poiché nel formato compaiono solo d, m e Y, le chiavi hour, minute e second vengono restituite come false.

Validare il risultato: errori e avvisi

date_parse_from_format() non lancia mai un'eccezione — anche con un input non valido restituisce un array. Due chiavi indicano se l'input era utilizzabile:

• error_count conta i caratteri che non corrispondono affatto al formato.
• warning_count conta i valori che corrispondono al formato ma non hanno senso, come il mese 13 o il giorno 45.

Una stringa che non corrisponde al formato produce errori:

<?php

// Expecting Y-m-d but the input is d/m/Y
$result = date_parse_from_format("Y-m-d", "03/03/2023");

echo "Errors:   {$result['error_count']}\n";
print_r($result['errors']);

Errors:   5
Array
(
    [2] => Unexpected data found.
    [5] => Unexpected data found.
    [8] => Trailing data
)

Una stringa che corrisponde al formato ma non è una data reale produce invece un avviso:

<?php

$result = date_parse_from_format("Y-m-d", "2023-13-45");

echo "Warnings: {$result['warning_count']}\n";
print_r($result['warnings']);

Warnings: 1
Array
(
    [10] => The parsed date was invalid
)

Controlla sempre entrambi i conteggi prima di fidarti dei valori analizzati:

if ($result['error_count'] === 0 && $result['warning_count'] === 0) {
    // safe to use $result['year'], $result['month'], etc.
}

Quando usare una funzione diversa

date_parse_from_format() è la scelta migliore quando si vuole un report dettagliato e consapevole del formato — soprattutto per validare l'input. Se hai semplicemente bisogno di un valore di data utilizzabile, altri strumenti sono più comodi:

• DateTime::createFromFormat($format, $string) restituisce un oggetto DateTime pronto all'uso su cui puoi formattare o eseguire operazioni aritmetiche. Vedi data e ora in PHP.
• strtotime() indovina il formato autonomamente e restituisce un timestamp Unix — pratico per stringhe comuni e non ambigue, ma più rischioso per layout specifici della lingua.
• date_parse() è uguale a questa funzione ma senza una stringa di formato; cerca di interpretare la data da sola.

Conclusione

date_parse_from_format() analizza una stringa di data secondo un formato esplicito e restituisce un array associativo dettagliato, rendendola ideale per validare date fornite dall'utente. Ricorda che non lancia mai eccezioni — controlla error_count e warning_count prima di usare il risultato. Quando hai bisogno di un oggetto DateTime o di un timestamp, usa DateTime::createFromFormat() o strtotime().

Esercizio