date_interval_format()

Introduzione

DateInterval::format() trasforma un intervallo di date — il divario tra due momenti nel tempo — in una string leggibile. Puoi decidere esattamente cosa mostrare (giorni, ore, il segno e così via) passando una string di formato composta da segnaposto %.

Questa pagina copre la sintassi, ogni codice di formato, la differenza fondamentale tra %a e %d, il funzionamento del padding e del segno, e diversi esempi eseguibili.

Cos'è un DateInterval?

Un DateInterval rappresenta un lasso di tempo (ad esempio "1 anno, 3 mesi, 12 giorni"), non una data specifica. Lo si ottiene quasi sempre da DateTime::diff(), che sottrae una data dall'altra:

<?php

$start = new DateTime('2022-03-03 00:00:00');
$end   = new DateTime('2023-06-15 14:30:00');

$interval = $start->diff($end); // returns a DateInterval object
echo $interval->format('%y years, %m months, %d days');

1 years, 3 months, 12 days

format() è il metodo che trasforma quell'object in una string. (Puoi anche costruire gli intervalli direttamente con il costruttore DateInterval o applicarli alle date con DateTime::add() e DateTime::sub().)

Sintassi

public DateInterval::format(string $format): string

• $format — una string contenente testo letterale più codici di formato %.
• Restituisce l'intervallo formattato come string.

Qualsiasi carattere che non fa parte di un codice % viene stampato letteralmente, quindi %d days produce qualcosa come 12 days. Per stampare un segno di percentuale letterale, usa %%.

%a vs %d — l'errore più comune

Questi due codici sembrano simili ma significano cose diverse:

• %a è il numero totale di giorni dell'intero intervallo.
• %d sono i giorni rimanenti dopo aver contabilizzato anni e mesi interi.

<?php

$start = new DateTime('2022-03-03');
$end   = new DateTime('2023-06-15');
$interval = $start->diff($end);

echo $interval->format('%a total days') . "\n";          // every day, counted flat
echo $interval->format('%y y, %m m, %d d') . "\n";        // broken into parts

469 total days
1 y, 3 m, 12 d

Usa %a quando vuoi un singolo numero "quanti giorni di distanza", e %d quando visualizzi anni/mesi/giorni insieme.

Codici di formato

I codici minuscoli restituiscono il valore grezzo; i codici maiuscoli sono zero-padded ad almeno due cifre. Non esiste un codice integrato per le ore, i minuti o i secondi totali — solo %a aggrega.

<?php

$start = new DateTime('2022-03-03 00:00:00');
$end   = new DateTime('2023-06-15 14:30:05');
$interval = $start->diff($end);

echo $interval->format('Padded: %Y-%M-%D %H:%I:%S');

Padded: 01-03-12 14:30:05

Esempio 1: Giorni totali tra due date

Mostrare un conteggio dei giorni con segno

Output:

+365 days

%R stampa il segno dell'intervallo e %a stampa il numero totale di giorni. Poiché $datetime2 è successiva a $datetime1, il segno è +. Invertendo le due date (o usando diff() nell'altro verso), %R diventa -.

Esempio 2: Giorni, ore e minuti

Combinare più unità in una sola string

Output:

+365 days 00 hours 00 minutes

Entrambi gli orari sono mezzanotte, quindi ore e minuti sono zero. Nota che vengono comunque stampati come 00 perché %h e %i già aggiungono padding ai risultati a cifra singola che sono zero — ma per i valori da 1 a 9 i codici minuscoli non hanno padding; usa %H / %I se vuoi sempre due cifre.

Quando usarlo?

• Etichette "membro da" / "X giorni fa" — calcola la differenza con diff(), poi formatta %a days.
• Conto alla rovescia — mostra %d days %h hours %i minutes fino a una scadenza.
• Report di durata — visualizza un DateInterval memorizzato (ad esempio la durata di un'attività) per un'interfaccia utente o una fattura.

Per formattare una data o un orario effettivo invece di un intervallo, usa DateTime::format() o la funzione procedurale date() — condividono un insieme di segnaposto completamente diverso da DateInterval::format().

Conclusione

DateInterval::format() visualizza il divario tra due date usando codici prefissati da %. Ricorda le due regole fondamentali: %a è il conteggio totale dei giorni mentre %d sono i giorni rimanenti, e i codici maiuscoli aggiungono zero-padding mentre quelli minuscoli no. Per saperne di più su come produrre l'intervallo, consulta DateTime::diff().

Esercizio