Análisis de fechas en PHP

Las fechas suelen llegar como cadenas de texto — desde un formulario, un archivo CSV o una respuesta de API — y PHP no tiene forma de saber cómo están estructuradas a menos que se lo indiques. La función date_parse_from_format() permite analizar una cadena de fecha según un formato explícito e inspeccionar el resultado, incluyendo cualquier error o advertencia. Esta página explica cómo funciona la función, cómo leer su valor de retorno, cómo validar la entrada y cuándo conviene usar una herramienta diferente como DateTime o strtotime().

Qué significa analizar fechas

El análisis de fechas es el proceso de convertir una cadena como "2023-03-03" en datos estructurados — un año, un mes, un día, etc. — con los que tu programa pueda trabajar. La dificultad radica en la ambigüedad: 03/04/2023 podría ser el 4 de marzo o el 3 de abril según la convención, y 2023-13-45 parece una fecha pero no es válida.

date_parse_from_format() elimina esa ambigüedad al requerir que especifiques el formato exacto de antemano. Lee la cadena estrictamente según ese formato y te indica qué encontró, para que puedas decidir si la entrada era válida.

La función date_parse_from_format()

date_parse_from_format() analiza una cadena de fecha usando un formato específico y devuelve un array asociativo que describe la fecha analizada: año, mes, día, hora, minuto, segundo, además de las advertencias y errores recopilados durante la lectura de la cadena.

Sintaxis

date_parse_from_format(string $format, string $datetime): array

• $format — una cadena de formato que usa los mismos marcadores de posición que date(), por ejemplo Y-m-d para 2023-03-03 o d/m/Y para 03/03/2023.
• $datetime — la cadena de fecha a analizar.

La función siempre devuelve un array; nunca lanza excepciones. Para saber si el análisis fue exitoso debes comprobar las claves error_count y warning_count.

Un ejemplo básico

La salida de este código será:

Array
(
    [year] => 2023
    [month] => 3
    [day] => 3
    [hour] => 10
    [minute] => 30
    [second] => 0
    [fraction] => 
    [warning_count] => 0
    [warnings] => Array()
    [error_count] => 0
    [errors] => Array()
    [is_localtime] => 
    [zone_type] => 1
    [zone] => -14400
    [is_dst] => 
)

La función analizó "2023-03-03 10:30:00" según el formato Y-m-d H:i:s y rellenó cada componente. Puedes leer valores individuales directamente del array, como $date_array['year'] o $date_array['month']. Cuando un componente está ausente en la cadena de formato, su valor es false (representado como un valor vacío por print_r).

Análisis de formatos personalizados

Los marcadores de posición del formato son los mismos que usa date(), así que cualquier estructura que puedas producir también puedes analizarla. El siguiente ejemplo lee una fecha en formato europeo día/mes/año:

<?php

$result = date_parse_from_format("d/m/Y", "03/03/2023");

echo "Day:   {$result['day']}\n";
echo "Month: {$result['month']}\n";
echo "Year:  {$result['year']}\n";

Esto imprime:

Day:   3
Month: 3
Year:  2023

Como solo aparecen d, m e Y en el formato, las claves hour, minute y second devuelven false.

Validación del resultado: errores y advertencias

date_parse_from_format() nunca lanza una excepción — incluso con una entrada incorrecta devuelve un array. Dos claves indican si la entrada era utilizable:

• error_count cuenta los caracteres que no coincidieron con el formato en absoluto.
• warning_count cuenta los valores que coincidieron con el formato pero no tienen sentido, como el mes 13 o el día 45.

Una cadena que no coincide con el formato produce errores:

<?php

// Expecting Y-m-d but the input is d/m/Y
$result = date_parse_from_format("Y-m-d", "03/03/2023");

echo "Errors:   {$result['error_count']}\n";
print_r($result['errors']);

Errors:   5
Array
(
    [2] => Unexpected data found.
    [5] => Unexpected data found.
    [8] => Trailing data
)

Una cadena que coincide con el formato pero no es una fecha real produce una advertencia en su lugar:

<?php

$result = date_parse_from_format("Y-m-d", "2023-13-45");

echo "Warnings: {$result['warning_count']}\n";
print_r($result['warnings']);

Warnings: 1
Array
(
    [10] => The parsed date was invalid
)

Siempre comprueba ambos contadores antes de confiar en los valores analizados:

if ($result['error_count'] === 0 && $result['warning_count'] === 0) {
    // safe to use $result['year'], $result['month'], etc.
}

Cuándo usar una función diferente

date_parse_from_format() es ideal cuando necesitas un informe detallado con conciencia del formato — especialmente para validar la entrada. Si simplemente necesitas un valor de fecha utilizable, otras herramientas son más convenientes:

• DateTime::createFromFormat($format, $string) devuelve un objeto DateTime listo para usar que puedes formatear o sobre el que puedes hacer operaciones aritméticas. Consulta Fecha y hora en PHP.
• strtotime() adivina el formato por ti y devuelve un timestamp Unix — útil para cadenas comunes e inequívocas, pero más arriesgado para formatos específicos de una región.
• date_parse() es igual que esta función pero sin una cadena de formato; intenta interpretar la fecha por su cuenta.

Conclusión

date_parse_from_format() analiza una cadena de fecha según un formato explícito y devuelve un array asociativo detallado, lo que lo hace ideal para validar fechas introducidas por el usuario. Recuerda que nunca lanza excepciones — comprueba error_count y warning_count antes de usar el resultado. Cuando necesites un objeto DateTime o un timestamp en su lugar, utiliza DateTime::createFromFormat() o strtotime().

Práctica