date_interval_create_from_date_string()

Che cos'è date_interval_create_from_date_string()?

La funzione date_interval_create_from_date_string() è una funzione PHP integrata che costruisce un oggetto DateInterval a partire da una stringa di tempo relativo leggibile dall'uomo, come '1 day' o '2 weeks 3 hours'. È l'alias procedurale del metodo statico DateInterval::createFromDateString() — entrambi si comportano in modo identico.

Questa pagina illustra la firma della funzione, i tipi di stringhe accettate, il valore restituito, la deprecazione introdotta in PHP 8.2 e alcuni esempi eseguibili per aggiungere e formattare intervalli.

Deprecazione: date_interval_create_from_date_string() è stata deprecata in PHP 8.2 ed è prevista la sua rimozione in una versione futura. Per il nuovo codice, preferire il costruttore di DateInterval con una stringa di durata ISO-8601 (ad esempio new DateInterval('P1D')). Consultare la sezione Migrazione qui sotto.

Sintassi

date_interval_create_from_date_string(string $datetime): DateInterval|false

Parametri

• $datetime — Una stringa di tempo relativo, dello stesso tipo accettato da strtotime(). Vengono utilizzate solo le parti relative; le parti assolute (una data o un orario espliciti) vengono ignorate.

Valore restituito

Restituisce un oggetto DateInterval in caso di successo, oppure false se la stringa non contiene parti relative analizzabili. Verificare sempre il valore restituito prima di utilizzarlo.

Come funziona?

La funzione passa la stringa attraverso lo stesso parser di strtotime() e conserva solo le parti relative. I formati utili includono:

Un meno iniziale (ad esempio '-1 week') memorizza un valore negativo direttamente nella proprietà corrispondente (qui d diventa -7), quindi aggiungere tale intervallo a una data fa avanzare il tempo a ritroso.

Utilizzo di base

<?php

$interval = date_interval_create_from_date_string('1 day');
var_dump($interval->d); // int(1)

Qui creiamo un DateInterval che rappresenta uno span di un giorno; la sua proprietà d (giorni) è 1.

Esempi

Esempio 1: Aggiungere un intervallo a una data

Questo esempio crea un intervallo di un giorno e lo aggiunge a un oggetto DateTime tramite DateTime::add():

Output:

2023-03-04

Esempio 2: Formattare un intervallo

Questo esempio crea un intervallo di un mese e lo stampa con DateInterval::format(). Notare che %m non è con zero iniziale — usare %M se si vuole uno zero iniziale:

Output:

1 months

Esempio 3: Gestire un valore false restituito

Se la stringa non contiene parti relative, la funzione restituisce false. Verificare sempre prima di utilizzare il risultato:

<?php

$interval = date_interval_create_from_date_string('not an interval');

if ($interval === false) {
    echo "Could not parse the interval.";
} else {
    echo $interval->format('%d days');
}

Output:

Could not parse the interval.

Migrazione dalla funzione

Poiché la funzione è deprecata, preferire il costruttore DateInterval nel nuovo codice. Accetta una stringa di durata ISO-8601: P avvia un periodo e T separa la parte della data dalla parte dell'orario.

<?php

// Deprecated:
$old = date_interval_create_from_date_string('1 day');

// Recommended replacement:
$new = new DateInterval('P1D'); // P = period, 1D = 1 day

echo $new->format('%d day'); // 1 day

Output:

1 day

Conversioni comuni: '1 day' → P1D, '2 weeks' → P14D, '1 month' → P1M, '2 hours 30 minutes' → PT2H30M.

Suggerimenti sulle prestazioni

• Creare un intervallo una sola volta e riutilizzarlo; evitare di ricreare lo stesso DateInterval all'interno di cicli stretti.
• L'analisi di una stringa relativa richiede un po' più di lavoro rispetto al costruttore, quindi preferire new DateInterval('P1D') quando la durata è fissa e nota in anticipo.

Vedere anche

• date_interval_format() — formattare un DateInterval per la visualizzazione.
• date_add() — aggiungere un intervallo a una data.
• date_diff() — ottenere il DateInterval tra due date.
• strtotime() — il parser di tempo relativo su cui si basa questa funzione.

Conclusione

date_interval_create_from_date_string() converte una stringa di tempo relativo in un DateInterval, restituendo false quando la stringa non può essere analizzata. È stata deprecata in PHP 8.2, quindi per il nuovo codice preferire il costruttore DateInterval con una durata ISO-8601 (new DateInterval('P1D')). Quando la si utilizza, validare sempre il valore restituito prima di fare affidamento sull'oggetto risultante.

Esercizio