date_interval_create_from_date_string()

¿Qué es date_interval_create_from_date_string()?

La función date_interval_create_from_date_string() es una función integrada de PHP que construye un objeto DateInterval a partir de una cadena de tiempo relativo legible por humanos, como '1 day' o '2 weeks 3 hours'. Es el alias procedimental del método estático DateInterval::createFromDateString() — ambos se comportan de manera idéntica.

Esta página cubre la firma de la función, qué tipos de cadenas acepta, el valor que devuelve, la importante obsolescencia en PHP 8.2 y ejemplos ejecutables para agregar y formatear intervalos.

Obsolescencia: date_interval_create_from_date_string() fue declarada obsoleta en PHP 8.2 y está programada para su eliminación en una versión futura. En el código nuevo, prefiera el constructor de DateInterval con una cadena de duración ISO-8601 (por ejemplo new DateInterval('P1D')). Consulte Migración más abajo.

Sintaxis

date_interval_create_from_date_string(string $datetime): DateInterval|false

Parámetros

• $datetime — Una cadena de tiempo relativo, del mismo tipo que entiende strtotime(). Solo se utilizan las partes relativas; las partes absolutas (una fecha u hora explícita) se ignoran.

Valor de retorno

Devuelve un objeto DateInterval en caso de éxito, o false si la cadena no contiene partes relativas que puedan analizarse. Compruebe siempre el valor de retorno antes de utilizarlo.

¿Cómo funciona?

La función procesa la cadena a través del mismo analizador que strtotime() y conserva solo las partes relativas. Los formatos útiles incluyen:

Un signo menos inicial (por ejemplo '-1 week') almacena un valor negativo directamente en la propiedad correspondiente (aquí d pasa a ser -7), por lo que agregar dicho intervalo a una fecha retrocede en el tiempo.

Uso básico

<?php

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

Aquí creamos un DateInterval que representa un período de un día; su propiedad d (días) es 1.

Ejemplos

Ejemplo 1: Agregar un intervalo a una fecha

Este ejemplo crea un intervalo de un día y lo agrega a un objeto DateTime con DateTime::add():

Salida:

2023-03-04

Ejemplo 2: Formatear un intervalo

Este ejemplo crea un intervalo de un mes y lo imprime con DateInterval::format(). Tenga en cuenta que %m no tiene relleno de ceros — use %M si desea un cero inicial:

Salida:

1 months

Ejemplo 3: Protección ante un retorno false

Si la cadena no tiene partes relativas, la función devuelve false. Compruebe siempre antes de usar el 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');
}

Salida:

Could not parse the interval.

Migración para dejar de usar la función

Debido a que la función está obsoleta, prefiera el constructor de DateInterval en el código nuevo. Acepta una cadena de duración ISO-8601: P inicia un período y T separa la parte de fecha de la parte de tiempo.

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

Salida:

1 day

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

Consejos de rendimiento

• Construya un intervalo una sola vez y reutilícelo; evite recrear el mismo DateInterval dentro de bucles ajustados.
• Analizar una cadena relativa requiere un poco más de trabajo que el constructor, por lo que prefiera new DateInterval('P1D') cuando la duración es fija y conocida de antemano.

Véase también

• date_interval_format() — formatear un DateInterval para su visualización.
• date_add() — agregar un intervalo a una fecha.
• date_diff() — obtener el DateInterval entre dos fechas.
• strtotime() — el analizador de tiempo relativo en el que se basa esta función.

Conclusión

date_interval_create_from_date_string() convierte una cadena de tiempo relativo en un DateInterval, devolviendo false cuando la cadena no puede analizarse. Fue declarada obsoleta en PHP 8.2, por lo que en el código nuevo prefiera el constructor de DateInterval con una duración ISO-8601 (new DateInterval('P1D')). Cuando la utilice, valide siempre el valor de retorno antes de confiar en el objeto resultante.

Práctica