date_create()

Introduzione

La funzione date_create() di PHP è il modo procedurale per costruire un object DateTime — il blocco fondamentale orientato agli oggetti per quasi tutto il lavoro con date e orari in PHP. Questo articolo ne illustra la sintassi e i parametri, mostra come leggere un DateTime una volta ottenuto, spiega cosa accade quando il parsing fallisce e indica le funzioni correlate a cui ricorrere successivamente.

date_create() è semplicemente un alias di new DateTime(). I due sono intercambiabili, quindi usa quello che si legge meglio nel tuo codice. Un motivo comune per preferire date_create() è che, a differenza del costruttore, restituisce false invece di lanciare un'eccezione in caso di string di input non valida — il che può essere gestito senza un blocco try/catch.

La funzione date_create()

La funzione date_create() è una funzione built-in di PHP che crea un nuovo object DateTime. Accetta un parametro opzionale che specifica la data e l'orario in un formato riconosciuto dalla funzione strtotime(). Se non viene passato alcun parametro, la funzione restituisce un object DateTime che rappresenta la data e l'orario correnti.

Sintassi

La sintassi della funzione date_create() è la seguente:

Sintassi della funzione date_create() in PHP

date_create(string $datetime = "now", ?DateTimeZone $timezone = null): DateTime|false

Il primo parametro, $time, specifica la data e l'orario per creare l'object DateTime. È opzionale e ha un valore predefinito di "now". Il secondo parametro, $timezone, specifica il fuso orario da utilizzare. Anch'esso è opzionale e ha un valore predefinito di NULL.

Parametri

Vediamo più da vicino i parametri della funzione date_create():

• $datetime (opzionale): Specifica la data e l'orario per creare l'object DateTime. Può essere qualsiasi string in un formato riconosciuto dalla funzione strtotime() — una data assoluta come "2022-12-31", una frase relativa come "next monday" o "+1 week", oppure un timestamp UNIX preceduto da @ (ad esempio "@1672531199"). Il valore predefinito "now" produce la data e l'orario correnti.
• $timezone (opzionale): Un object DateTimeZone che specifica il fuso orario. Se omesso (o null), viene utilizzato il fuso orario predefinito dello script. Nota: questo parametro viene ignorato quando $datetime è un timestamp UNIX (@...) o contiene già un offset di fuso orario come "2022-12-31 23:59:59+02:00".

Valore restituito

In caso di successo, date_create() restituisce un object DateTime. In caso di errore — ad esempio quando $datetime non può essere analizzato — restituisce false invece di lanciare un'eccezione. Questo rende il risultato sicuro da testare con una semplice condizione:

<?php

$date = date_create('not a real date');

if ($date === false) {
    echo 'Could not parse the date.';
} else {
    echo $date->format('Y-m-d');
}
// Output: Could not parse the date.

Esempi

Ecco alcuni esempi di utilizzo della funzione date_create():

Esempio di utilizzo della funzione date_create() in PHP

Utilizzo di string di date relative

Poiché date_create() accetta qualsiasi cosa che strtotime() comprenda, puoi costruire date relative a "now" senza alcuna operazione aritmetica:

<?php

$today = date_create();
echo $today->format('l') . "\n";          // e.g. Output: Thursday

$nextWeek = date_create('+1 week');
echo $nextWeek->format('Y-m-d') . "\n";   // 7 days from today

$firstOfMonth = date_create('first day of this month');
echo $firstOfMonth->format('Y-m-d');       // e.g. 2023-03-01

Utilizzo del risultato

Una volta ottenuto un object DateTime, in genere lo si formatta per la visualizzazione o lo si confronta con un'altra data:

<?php

$start = date_create('2022-01-01');
$end   = date_create('2022-12-31');

// Format the object as a string
echo $end->format('F j, Y') . "\n";   // Output: December 31, 2022

// Compare two DateTime objects directly
echo ($end > $start ? 'end is later' : 'start is later');
// Output: end is later

Usa date_format() (o il metodo ->format() mostrato sopra) per visualizzare l'object, e date_diff() per misurare l'intervallo tra due object DateTime.

Funzioni correlate

• date_create_from_format() — crea un DateTime da una string che usa un formato personalizzato specificato dall'utente, invece di affidarsi alle euristiche di strtotime().
• date_format() — converte un object DateTime in una string formattata.
• date_add() — aggiunge un DateInterval a un DateTime.
• strtotime() — il parser che gestisce l'argomento $datetime; restituisce un timestamp UNIX invece di un object.

Conclusione

La funzione date_create() è il punto di ingresso procedurale per lavorare con gli object DateTime di PHP. Accetta sia string di date assolute che relative, opzionalmente accetta un fuso orario e restituisce false in caso di errore, così puoi validare l'input senza gestire eccezioni. Una volta ottenuto un DateTime, formattalo con ->format() e confronta o sottrai direttamente gli object. Per analizzare input non standard, usa date_create_from_format(); per visualizzare i risultati, usa date_format().

Esercitazione