date_interval_create_from_date_string()

O que é date_interval_create_from_date_string()?

A função date_interval_create_from_date_string() é uma função nativa do PHP que constrói um objeto DateInterval a partir de uma string de tempo relativo legível por humanos, como '1 day' ou '2 weeks 3 hours'. É o alias procedural do método estático DateInterval::createFromDateString() — ambos se comportam de forma idêntica.

Esta página aborda a assinatura da função, os tipos de strings que ela aceita, o valor que retorna, a importante depreciação no PHP 8.2 e exemplos executáveis para adicionar e formatar intervalos.

Depreciação: date_interval_create_from_date_string() foi depreciada no PHP 8.2 e está programada para remoção em uma versão futura. Prefira o construtor DateInterval com uma string de duração ISO-8601 (por exemplo, new DateInterval('P1D')) em código novo. Veja Migração abaixo.

Sintaxe

date_interval_create_from_date_string(string $datetime): DateInterval|false

Parâmetros

• $datetime — Uma string de tempo relativo, do mesmo tipo que strtotime() compreende. Somente as partes relativas são utilizadas; partes absolutas (uma data ou hora explícita) são ignoradas.

Valor de retorno

Retorna um objeto DateInterval em caso de sucesso, ou false se a string não contiver partes relativas que possam ser analisadas. Sempre verifique o valor de retorno antes de utilizá-lo.

Como funciona?

A função passa a string pelo mesmo analisador que o strtotime() e mantém apenas as partes relativas. Os formatos úteis incluem:

Um menos inicial (por exemplo, '-1 week') armazena um valor negativo diretamente na propriedade relevante (aqui d torna-se -7), portanto adicionar tal intervalo a uma data move o tempo para trás.

Uso básico

<?php

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

Aqui criamos um DateInterval representando um período de um dia; sua propriedade d (dias) é 1.

Exemplos

Exemplo 1: Adicionando um intervalo a uma data

Este exemplo cria um intervalo de um dia e o adiciona a um objeto DateTime com DateTime::add():

Saída:

2023-03-04

Exemplo 2: Formatando um intervalo

Este exemplo cria um intervalo de um mês e o exibe com DateInterval::format(). Observe que %m não recebe zero à esquerda — use %M se quiser um zero inicial:

Saída:

1 months

Exemplo 3: Protegendo contra retorno false

Se a string não tiver partes relativas, a função retorna false. Sempre verifique antes de usar o resultado:

<?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');
}

Saída:

Could not parse the interval.

Migrando para longe da função

Como a função está depreciada, prefira o construtor DateInterval em código novo. Ele aceita uma string de duração ISO-8601: P inicia um período, e T separa a parte de data da parte de tempo.

<?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

Saída:

1 day

Conversões comuns: '1 day' → P1D, '2 weeks' → P14D, '1 month' → P1M, '2 hours 30 minutes' → PT2H30M.

Dicas de desempenho

• Construa um intervalo uma vez e reutilize-o; evite recriar o mesmo DateInterval dentro de loops com muitas iterações.
• Analisar uma string relativa exige um pouco mais de trabalho do que o construtor, portanto prefira new DateInterval('P1D') quando a duração for fixa e conhecida antecipadamente.

Veja também

• date_interval_format() — formata um DateInterval para exibição.
• date_add() — adiciona um intervalo a uma data.
• date_diff() — obtém o DateInterval entre duas datas.
• strtotime() — o analisador de tempo relativo no qual esta função se baseia.

Conclusão

date_interval_create_from_date_string() transforma uma string de tempo relativo em um DateInterval, retornando false quando a string não pode ser analisada. Foi depreciada no PHP 8.2, portanto, para código novo prefira o construtor DateInterval com uma duração ISO-8601 (new DateInterval('P1D')). Quando utilizá-la, sempre valide o valor de retorno antes de depender do objeto resultante.

Prática