Função PHP date_create_from_format: Sintaxe e Exemplos

A função date_create_from_format() analisa uma string de data escrita no seu formato — não apenas nos formatos que o PHP tenta adivinhar — e retorna um objeto DateTime. Use-a sempre que receber uma data em um layout fixo e não padrão (uma exportação CSV, uma API de terceiros, um formulário de usuário) e precisar lê-la de forma confiável.

Esta página abrange a sintaxe, exemplos executáveis, o parâmetro de fuso horário, como detectar falhas de análise e como a função difere de strtotime() e date_parse_from_format().

Sintaxe

date_create_from_format(string $format, string $datetime, ?DateTimeZone $timezone = null): DateTime|false

• $format — o layout da string de entrada, escrito com os mesmos caracteres de formato que a função date(). Por exemplo, "Y-m-d H:i:s" corresponde a "2023-03-02 17:30:45".
• $datetime — a string de data a ser analisada. Seu layout deve corresponder a $format.
• $timezone — (opcional) um DateTimeZone para o objeto resultante. Se omitido, o fuso horário padrão atual (definido via date_default_timezone_set()) é usado. O parâmetro é ignorado se $format já contiver um caractere de fuso horário como e, O, P ou T.

Retorna um objeto DateTime em caso de sucesso, ou false se a string não corresponder ao formato.

date_create_from_format() é o alias procedural do método estático DateTime::createFromFormat() — eles se comportam de forma idêntica.

Exemplos

Analisando uma string de data padrão

A função lê "2023-03-02 17:30:45" de acordo com "Y-m-d H:i:s" e retorna um objeto DateTime. Chamar format() nele permite re-renderizar a data em qualquer layout desejado.

Reformatando uma data não padrão

Aqui a entrada usa um dia, um nome de mês com três letras e um ano com quatro dígitos (j-M-Y). A saída é renderizada em ordem ISO (Y-m-d) — prova de que, uma vez que uma data se torna um objeto DateTime, você tem liberdade para exibi-la da forma que quiser.

Redefinindo o horário com !

Se o seu formato não tiver campos de hora, as partes ausentes assumem como padrão a hora, o minuto e o segundo atuais — o que raramente é o que se deseja para um valor apenas de data. Prefixe o formato com ! para redefinir todos os campos não especificados para a época Unix (00:00:00):

<?php

$date = date_create_from_format('!Y-m-d', '2023-03-02');
echo $date->format('Y-m-d H:i:s'); // Output: 2023-03-02 00:00:00

Fornecendo um fuso horário

<?php

$tz = new DateTimeZone('Europe/Paris');
$date = date_create_from_format('Y-m-d H:i:s', '2023-03-02 17:30:45', $tz);
echo $date->format('Y-m-d H:i:s P'); // Output: 2023-03-02 17:30:45 +01:00

O terceiro argumento ancora a data analisada no horário de Paris, de modo que o token P reporta o deslocamento +01:00.

Tratando falhas de análise

Quando a string não corresponde ao formato, a função retorna false em vez de lançar uma exceção. Sempre verifique isso e leia DateTime::getLastErrors() para obter os detalhes:

<?php

$date = date_create_from_format('Y-m-d', 'not-a-date');

if ($date === false) {
    $errors = DateTime::getLastErrors();
    echo "Parse failed: {$errors['error_count']} error(s)\n";
    // Output: Parse failed: 3 error(s)
}

Como false é falsy, um simples if (!$date) também funciona — mas uma verificação estrita === false é mais segura quando um valor vazio poderia legitimamente significar outra coisa.

Comparação com outras funções de data

Use date_create_from_format() quando o layout for fixo e você quiser um objeto DateTime completo para manipular. Use strtotime() para strings em linguagem natural e informal como "next Friday", e date_parse_from_format() quando precisar apenas dos números brutos de ano/mês/dia sem construir um objeto.

Conclusão

date_create_from_format() transforma uma string em um layout arbitrário e conhecido em um objeto DateTime que você pode formatar, comparar e manipular com o restante da API de datas do PHP. Lembre-se de usar o prefixo ! para valores apenas de data, passar um DateTimeZone quando o fuso horário da origem for relevante, e sempre proteger-se contra o retorno false.

Prática