date_format()

date_format()

Introduzione

Date e orari sono presenti ovunque nelle applicazioni reali: timestamp sui post di un blog, date degli ordini in un negozio online, voci di log, eventi in calendario. PHP memorizza questi momenti internamente in un formato non leggibile dall'uomo, quindi è necessario un modo per trasformare un oggetto data in una stringa comprensibile — "2023-03-03", "Friday, March 3rd" oppure "03/03/2023 1:00 PM". È esattamente questo ciò che fa date_format().

Questo capitolo illustra cos'è date_format(), la sua sintassi, i caratteri di formato più utili e gli aspetti critici relativi ai fusi orari e all'immutabilità.

Cos'è la funzione date_format()?

La funzione date_format() formatta un oggetto DateTime come stringa secondo un pattern che si fornisce. È un alias procedurale del metodo orientato agli oggetti DateTime::format() — entrambi producono risultati identici, quindi si utilizza quello che meglio si adatta al proprio codebase:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

// These two lines are equivalent
echo date_format($date, 'Y-m-d');   // procedural
echo $date->format('Y-m-d');        // object-oriented

Sintassi

date_format(DateTimeInterface $object, string $format): string

• $object — un'istanza di DateTime (o DateTimeImmutable). È la data che si vuole visualizzare.
• $format — una stringa composta da caratteri di formato (come Y, m, d). Qualsiasi carattere che non sia un carattere di formato viene stampato letteralmente.
• Valore restituito — la data formattata come stringa.

Come usare la funzione date_format()

Prima si crea un oggetto data con la classe DateTime, integrata in PHP:

<?php

$date = new DateTime('2023-03-03');

Questo crea una data impostata al 3 marzo 2023, a mezzanotte. Per impostazione predefinita, DateTime utilizza il fuso orario configurato sul server — il che significa che lo stesso codice può produrre output diversi su macchine diverse. Per risultati prevedibili, impostare sempre il fuso orario in modo esplicito:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

Ora è possibile formattarla come si preferisce:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'Y-m-d');
// Output: 2023-03-03

Per le applicazioni PHP moderne, è preferibile usare DateTimeImmutable al posto di DateTime. Metodi come modify() modificano un DateTime in-place, il che è una fonte comune di bug quando l'oggetto viene passato in giro; DateTimeImmutable restituisce invece un nuovo oggetto e funziona con date_format() esattamente allo stesso modo:

<?php

$date = new DateTimeImmutable('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'd/m/Y');
// Output: 03/03/2023

Formati di data comuni

Esistono molti modi diversi per formattare le date usando la funzione date_format(). Ecco alcuni dei formati più comuni:

• Y-m-d: La data nel formato YYYY-MM-DD.
• d/m/Y: La data nel formato DD/MM/YYYY.
• m/d/Y: La data nel formato MM/DD/YYYY.
• H:i:s: L'ora nel formato 24 ore (ad es., 13:00:00).
• h:i:s a: L'ora nel formato 12 ore (ad es., 01:00:00 am).

Caratteri di formato

Oltre ai formati comuni sopra indicati, è possibile costruire il proprio pattern utilizzando singoli caratteri di formato. Ecco quelli che si utilizzano più spesso:

• Y: L'anno in quattro cifre (ad es., 2023).
• y: L'anno in due cifre (ad es., 23).
• m: Il mese come numero a due cifre (ad es., 03).
• M: Il nome abbreviato del mese (ad es., Mar).
• F: Il nome completo del mese (ad es., March).
• d: Il giorno del mese come numero a due cifre (ad es., 03).
• D: Il nome abbreviato del giorno (ad es., Fri).
• l: Il nome completo del giorno (ad es., Friday).
• j: Il giorno del mese senza zeri iniziali (ad es., 3).
• S: Il suffisso ordinale inglese per il giorno del mese (ad es., st, nd, rd, th).
• H: L'ora nel formato 24 ore (ad es., 13).
• h: L'ora nel formato 12 ore (ad es., 01).
• i: I minuti come numero a due cifre (ad es., 05).
• s: I secondi come numero a due cifre (ad es., 30).
• a: am oppure pm.

Per l'elenco completo di tutti i caratteri supportati, consultare PHP date and time e il capitolo date() — date_format() utilizza gli stessi caratteri.

Ecco un esempio di formato data personalizzato:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'l, F jS Y, h:i:s a');
// Output: Friday, March 3rd 2023, 12:00:00 am

Per stampare letteralmente un carattere di formato invece di farlo interpretare, è necessario eseguirne l'escape con una barra rovesciata:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, '\T\o\d\a\y \i\s l');
// Output: Today is Friday

date_format() vs date()

Entrambe le funzioni formattano le date, ma accettano input diversi:

• date() opera su un timestamp Unix (un numero intero) e ha come valore predefinito "adesso". Usarla per una formattazione rapida e indipendente dal fuso orario: date('Y-m-d').
• date_format() opera su un oggetto DateTime, quindi porta con sé il proprio fuso orario e supporta operazioni aritmetiche (aggiunta di giorni, calcolo di differenze) prima della formattazione. Usarla quando è necessario manipolare la data.

Se si dispone di una stringa come "3 March 2023", è necessario prima creare un DateTime — date_create_from_format() e strtotime() sono i punti di ingresso più comuni.

Conclusione

La funzione date_format() in PHP offre un modo diretto per formattare un oggetto DateTime come stringa leggibile. Comprendendo i caratteri di formato disponibili e le best practice — impostare il fuso orario in modo esplicito e preferire DateTimeImmutable — è possibile garantire un output delle date accurato e prevedibile in qualsiasi ambiente in cui il codice viene eseguito.

Practice