date_parse()

Introduzione

La funzione date_parse() in PHP prende una stringa di data leggibile dall'uomo e la scompone nei singoli componenti — anno, mese, giorno, ora, minuto, secondo — restituendoli come array associativo. In modo fondamentale, segnala anche eventuali avvertimenti ed errori riscontrati durante l'interpretazione della stringa, il che la rende uno strumento utile per validare l'input di date prima di utilizzarle.

A differenza di strtotime(), che riduce una stringa di data a un singolo timestamp Unix, date_parse() mantiene ogni parte separata e non scarta mai i messaggi diagnostici. Questa distinzione è il motivo principale per sceglierla: quando è necessario sapere non solo qual è una data, ma se l'input fosse effettivamente una data valida.

Questa pagina tratta la sintassi, la struttura completa dell'array restituito, come leggere avvertimenti ed errori, e come date_parse() si confronta con le funzioni correlate.

Sintassi

date_parse(string $datetime): array

Restituisce sempre un array (non restituisce mai false); quando il parsing fallisce, l'errore viene descritto nella chiave errors anziché essere segnalato dal valore restituito.

Parametri

$datetime — una string che rappresenta la data/ora da analizzare. Accetta gli stessi formati flessibili compresi dal parser di date interno di PHP, ad esempio:

• '2022-03-03 15:30:45' — data e ora in formato ISO completo
• 'July 4, 2023' — linguaggio naturale
• 'now', 'tomorrow', '+1 week' — espressioni relative

Se un componente è assente dalla stringa (per esempio, non viene indicata l'ora), la sua chiave viene restituita come valore vuoto anziché essere omessa.

Valore Restituito

La funzione restituisce un array associativo con le seguenti chiavi:

• year, month, day — i componenti della data (interi, o vuoti se non presenti)
• hour, minute, second — i componenti dell'ora (interi, o vuoti se non presenti)
• fraction — la parte frazionaria dei secondi (un float, es. 0)
• warning_count — il numero di avvertimenti generati durante il parsing
• warnings — un array di avvertimenti, indicizzato dalla posizione del carattere nell'input
• error_count — il numero di errori generati durante il parsing
• errors — un array di errori, indicizzato dalla posizione del carattere nell'input
• is_localtime — indica se la stringa conteneva informazioni sul fuso orario

Quando is_localtime è true, chiavi aggiuntive come zone_type, zone e is_dst descrivono il fuso orario.

Esempio Base

Analizziamo una stringa completa di data e ora:

Output:

Array
(
    [year] => 2022
    [month] => 3
    [day] => 3
    [hour] => 15
    [minute] => 30
    [second] => 45
    [fraction] => 0
    [warning_count] => 0
    [warnings] => Array()
    [error_count] => 0
    [errors] => Array()
    [is_localtime] =>
)

Ogni componente è ora disponibile individualmente — ad esempio, $date_arr['month'] è 3. Poiché error_count e warning_count sono entrambi 0, sappiamo che la stringa era una data pulita e valida.

Parsing di una Data Parziale

date_parse() non richiede una data completa. Se si passa solo una data senza ora, le chiavi dell'ora tornano vuote:

<?php

$result = date_parse('July 4, 2023');
echo "Year: {$result['year']}\n";
echo "Month: {$result['month']}\n";
echo "Day: {$result['day']}\n";
echo "Hour: '{$result['hour']}'\n"; // empty — no time was given

Output:

Year: 2023
Month: 7
Day: 4
Hour: ''

Questo è utile quando si accettano date senza orari e si vogliono i singoli elementi senza scrivere un parser personalizzato.

Rilevare Date Non Valide con gli Avvertimenti

Qui date_parse() eccelle. Si consideri il 30 febbraio — una data che non esiste. Il parser restituirà comunque dei valori, ma segnalerà il problema in warnings:

<?php

$result = date_parse('2023-02-30');

if ($result['warning_count'] > 0) {
    foreach ($result['warnings'] as $position => $message) {
        echo "Warning at position $position: $message\n";
    }
}

Output:

Warning at position 11: The parsed date was invalid

Verificare sempre error_count (la stringa non era comprensibile) e warning_count (la stringa era comprensibile ma descrive una data impossibile) prima di fidarsi dei componenti analizzati. Per un controllo del calendario stretto sì/no su un anno-mese-giorno specifico, abbinare questa funzione a checkdate().

Quando Usare date_parse() rispetto alle Funzioni Correlate

Se successivamente è necessario visualizzare una data, vedere date() per formattare i componenti in una stringa.

Conclusione

La funzione date_parse() offre un modo diretto per scomporre una stringa di data nei suoi singoli componenti segnalando nel contempo eventuali avvertimenti ed errori. Questo duplice ruolo — estrazione e validazione — la rende particolarmente utile per verificare le date fornite dall'utente prima di elaborarle. Combinarla con checkdate() per una validazione rigorosa, oppure con strtotime() e DateTime quando servono timestamp o oggetti data completi.

Esercizio