DateTimeImmutable::createFromFormat

DateTimeImmutable::createFromFormat

date_create_immutable_from_format

Analiza un string de tiempo según el formato especificado

Descripción#

Estilo orientado a objetos

public static DateTimeImmutable::createFromFormat(string $format, string $datetime, [DateTimeZone $timezone]): DateTimeImmutable
```php

Estilo procedimental

```php
date_create_immutable_from_format(string $format, string $datetime, [DateTimeZone $timezone]): DateTimeImmutable

Devuelve un nuevo objeto DateTimeImmutable representando la fecha y hora especificada por el string datetime, que tiene el formato indicado por format.

Parámetros#

format
El formato en el cual se ha pasado el string. Consulta las opciones de formato a continuación. En la mayoría de los casos, pueden ser usadas las mismas letras que para la función date.

Todos los campos son inicializados con la fecha y hora actual. En el caso de que quieras restablecerlos a "cero" (Unix epoch, 01/01/1970 00:00:00 UTC). Puedes hacerlo incluyendo el carácter ! al principio de format, o | al final. Por favor, consulta la documentación de cada carácter a continuación para más información.

El formato es analizado de izquierda a derecha, lo que significa que en algunas situaciones el orden en el que los caracteres de formato están escritos afecta al resultado. En el caso de z (el día del año), es necesario que un año ya se haya analizado, por ejemplo mediante los caracteres Y o y.

Las letras de formato que se usan para analizar números permiten un amplio rango de valores, fuera de lo que sería el rango lógico. Por ejemplo, el d (día del mes) acepta valores en el rango de 00 a 99. La única restricción es en la cantidad de dígitos. El mecanismo de desbordamiento del analizador de fecha/hora se usa cuando se dan valores fuera de rango. Los ejemplos a continuación muestran algo de este comportamiento.

Esto también significa que los datos analizados para una letra de formato son golosos, y leerán toda la cantidad de dígitos que su formato permite. Esto también puede significar que no hay suficientes caracteres en datetime para las letras de formato sucesivas. Un ejemplo en esta página también ilustra este problema.

Los siguientes caracteres son reconocidos en la cadena del parámetro format

Los caracteres no reconocidos en el string de formato causarán que el análisis falle y un mensaje de error se añadirá a la estructura devuelta. Puedes consultar los mensajes de error con DateTimeImmutable::getLastErrors.

Para incluir caracteres literales en format, debes escaparlos con una barra invertida (\).

Si format no contiene el carácter !, entonces las partes de la fecha/hora que no están especificadas en format se establecerán a la fecha actual del sistema.

Si format contiene el carácter !, entonces las partes de la fecha/hora generadas que no están especificadas en format, así como los valores a la izquierda del !, se establecerán a los valores correspondientes de Unix epoch.

Si cualquier carácter de tiempo es analizado, entonces todos los demás campos relacionados con el tiempo se establecerán a "0", a menos que también se analicen.

Unix epoch es 01/01/1970 00:00:00 UTC.

datetime
String representando la fecha y hora.

timezone
Una instancia de DateTimeZone representando la zona horaria deseada.

Si se omite timezone o pasado null y datetime no contiene zona horaria, se usará la zona horaria actual.

[!NOTE] El parámetro timezone y la zona horaria actual son ignorados cuando el parámetro datetime contiene un timestamp UNIX (por ejemplo, 946684800) o especifica una zona horaria (por ejemplo, 2010-01-28T15:00:00+02:00).

Valores devueltos#

Devuelve una nueva instancia de DateTimeImmutable o false si ocurre un error.

Errores/Excepciones#

Este método lanza ValueError cuando datetime contiene bytes nulos.

Historial de cambios#

Ejemplos#

Ejemplo de DateTimeImmutable::createFromFormat

Estilo orientado a objetos

<?php
$date = DateTimeImmutable::createFromFormat('j-M-Y', '15-Feb-2009');
echo $date->format('Y-m-d');

Usando constantes predefinidas con DateTimeImmutable::createFromFormat

Estilo orientado a objetos

<?php
$date = DateTimeImmutable::createFromFormat(
    DateTimeInterface::ISO8601,
    '2004-02-12T15:19:21+00:00'
);
echo $date->format('c e') . "\n";

$date = DateTimeImmutable::createFromFormat(
    DateTimeInterface::RFC3339_EXTENDED,
    '2013-10-14T09:00:00.000+02:00'
);
echo $date->format('c e') . "\n";

Las constantes de formato usadas en este ejemplo consisten en una cadena de caracteres para formatear un objeto DateTimeImmutable. En la mayoría de los casos, estas letras coinciden con los mismos elementos de información de fecha/hora que los definidos en los parámetros de la sección anterior, pero tienden a ser más permisivos.

Complejidades de DateTimeImmutable::createFromFormat

<?php
echo 'Hora actual: ' . date('Y-m-d H:i:s') . "\n";

$format = 'Y-m-d';
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15');
echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'Y-m-d H:i:s';
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'Y-m-!d H:i:s';
$date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = '!d';
$date = DateTimeImmutable::createFromFormat($format, '15');
echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

$format = 'i';
$date = DateTimeImmutable::createFromFormat($format, '15');
echo "Formato: $format; " . $date->format('Y-m-d H:i:s') . "\n";

Resultado del ejemplo anterior es similar a:

Hora actual: 2022-06-02 15:50:46
Formato: Y-m-d; 2009-02-15 15:50:46
Formato: Y-m-d H:i:s; 2009-02-15 15:16:17
Formato: Y-m-!d H:i:s; 1970-01-15 15:16:17
Formato: !d; 1970-01-15 00:00:00
Formato: i; 2022-06-02 00:15:00

Cadenas de formato con caracteres literales

<?php
echo DateTimeImmutable::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');

Resultado del ejemplo anterior es similar a:

23:15:03

Comportamiento de desbordamiento

<?php
echo DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97')->format(DateTimeImmutable::RFC2822);

Resultado del ejemplo anterior es similar a:

Sat, 04 Jun 2022 17:01:37 +0000

Aunque el resultado parece extraño, es correcto, ya que ocurren los siguientes desbordamientos:

1. 97 segundos se desbordan a 1 minuto, dejando 37 segundos.

2. 61 minutos se desbordan a 1 hora, dejando 1 minuto.

3. 35 días se debordan a 1 mes, dejando 4 días. La cantidad de días que quedan depende del mes, ya que no todos los meses tienen la misma cantidad de días.

4. 18 meses se desbordan a 1 año, dejando 6 meses.

Comportamiento de desbordamiento de nombres de días de la semana

<?php
$d = DateTime::createFromFormat(DateTimeInterface::RFC1123, 'Mon, 3 Aug 2020 25:00:00 +0000');
echo $d->format(DateTime::RFC1123), "\n";

Resultado del ejemplo anterior es similar a:

Mon, 10 Aug 2020 01:00:00 +0000

Aunque el resultado parece extraño, es correcto, ya que ocurren los siguientes desbordamientos:

1. 3 Aug 2020 25:00:00 se desborda a (Tue) 4 Aug 2020 01:00.

2. Se aplica Mon, el cual avanza la fecha a Mon, 10 Aug 2020 01:00:00. La explicación de palabras clave relativas como Mon se explica en la sección de formatos relativos.

Para detectar desbordamientos en fechas, puedes usar DateTimeImmutable::getLastErrors, el cual incluirá una advertencia si ocurrió un desbordamiento.

Detección de fechas desbordadas

<?php
$d = DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97');
echo $d->format(DateTimeImmutable::RFC2822), "\n\n";

var_dump(DateTimeImmutable::getLastErrors());

Resultado del ejemplo anterior es similar a:

Sat, 04 Jun 2022 17:01:37 +0000

array(4) {
  'warning_count' =>
  int(2)
  'warnings' =>
  array(1) {
    [19] =>
    string(27) "The parsed date was invalid"
  }
  'error_count' =>
  int(0)
  'errors' =>
  array(0) {
  }
}

Comportamiento de análisis goloso

<?php
print_r(date_parse_from_format('Gis', '60101'));

Resultado del ejemplo anterior es similar a:

Array
(
    [year] =>
    [month] =>
    [day] =>
    [hour] => 60
    [minute] => 10
    [second] => 0
    [fraction] => 0
    [warning_count] => 1
    [warnings] => Array
        (
            [5] => The parsed time was invalid
        )

    [error_count] => 1
    [errors] => Array
        (
            [4] => A two digit second could not be found
        )

    [is_localtime] =>
)

El formato G es para analizar horas en formato de 24 horas, con o sin cero inicial. Esto requiere analizar 1 o 2 dígitos. Debido a que hay dos dígitos siguientes, lo lee ávidamente como 60.

Los siguientes caracteres de formato i y s requieren ambos dos dígitos. Esto significa que se pasa 10 como minutos (i), y que luego no quedan suficientes dígitos para analizar como segundos (s).

El array errors indica este problema.

Adicionalmente, una hora de 60 está fuera del rango 0-24, lo que hace que el array warnings incluya una advertencia de que la hora es incorrecta.

Véase también#

DateTimeImmutable::__construct

DateTimeImmutable::getLastErrors

checkdate

strptime