date_create()

Introdução

A função date_create() do PHP é a forma procedural de construir um objeto DateTime — o bloco de construção orientado a objetos para quase todo o trabalho com datas e horas em PHP. Este artigo aborda sua sintaxe e parâmetros, mostra como ler um DateTime depois de obtê-lo, explica o que acontece quando a análise falha e aponta as funções relacionadas que você usará a seguir.

date_create() é simplesmente um alias para new DateTime(). As duas são intercambiáveis, portanto use aquela que for mais legível no seu código. Um motivo comum para preferir date_create() é que, diferentemente do construtor, ela retorna false em vez de lançar uma exceção quando a string de entrada é inválida — o que pode ser tratado sem um bloco try/catch.

A Função date_create()

A função date_create() é uma função embutida do PHP que cria um novo objeto DateTime. Ela aceita um parâmetro opcional que especifica a data e a hora em um formato reconhecido pela função strtotime(). Se nenhum parâmetro for passado, a função retorna um objeto DateTime representando a data e a hora atuais.

Sintaxe

A sintaxe da função date_create() é a seguinte:

Sintaxe da função date_create() em PHP

date_create(string $datetime = "now", ?DateTimeZone $timezone = null): DateTime|false

O primeiro parâmetro, $time, especifica a data e a hora para criar o objeto DateTime. É opcional e tem um valor padrão de "now". O segundo parâmetro, $timezone, especifica o fuso horário a ser utilizado. Também é opcional e tem um valor padrão de NULL.

Parâmetros

Vamos analisar mais de perto os parâmetros da função date_create():

• $datetime (opcional): Especifica a data e a hora para criar o objeto DateTime. Pode ser qualquer string em um formato reconhecido pela função strtotime() — uma data absoluta como "2022-12-31", uma expressão relativa como "next monday" ou "+1 week", ou um timestamp UNIX prefixado com @ (por exemplo, "@1672531199"). O padrão "now" produz a data e a hora atuais.
• $timezone (opcional): Um object DateTimeZone que especifica o fuso horário. Se omitido (ou null), o fuso horário padrão do script é utilizado. Observação: este parâmetro é ignorado quando $datetime é um timestamp UNIX (@...) ou já contém um deslocamento de fuso horário como "2022-12-31 23:59:59+02:00".

Valor de retorno

Em caso de sucesso, date_create() retorna um objeto DateTime. Em caso de falha — por exemplo, quando $datetime não pode ser analisado — ela retorna false em vez de lançar uma exceção. Isso torna o resultado seguro para verificar com uma condição simples:

<?php

$date = date_create('not a real date');

if ($date === false) {
    echo 'Could not parse the date.';
} else {
    echo $date->format('Y-m-d');
}
// Output: Could not parse the date.

Exemplos

Aqui estão alguns exemplos de como usar a função date_create():

Exemplo de uso da função date_create() em PHP

Usando strings de data relativas

Como date_create() aceita qualquer coisa que strtotime() compreende, você pode construir datas relativas a "agora" sem nenhuma aritmética:

<?php

$today = date_create();
echo $today->format('l') . "\n";          // e.g. Output: Thursday

$nextWeek = date_create('+1 week');
echo $nextWeek->format('Y-m-d') . "\n";   // 7 days from today

$firstOfMonth = date_create('first day of this month');
echo $firstOfMonth->format('Y-m-d');       // e.g. 2023-03-01

Trabalhando com o resultado

Depois de obter um objeto DateTime, você normalmente o formata para exibição ou o compara com outra data:

<?php

$start = date_create('2022-01-01');
$end   = date_create('2022-12-31');

// Format the object as a string
echo $end->format('F j, Y') . "\n";   // Output: December 31, 2022

// Compare two DateTime objects directly
echo ($end > $start ? 'end is later' : 'start is later');
// Output: end is later

Use date_format() (ou o método ->format() mostrado acima) para renderizar o object, e date_diff() para medir o intervalo entre dois objetos DateTime.

Funções relacionadas

• date_create_from_format() — cria um DateTime a partir de uma string que usa um formato personalizado que você especifica, em vez de depender das heurísticas de strtotime().
• date_format() — converte um objeto DateTime em uma string formatada.
• date_add() — adiciona um DateInterval a um DateTime.
• strtotime() — o analisador que alimenta o argumento $datetime; retorna um timestamp UNIX em vez de um object.

Conclusão

A função date_create() é o ponto de entrada procedural para trabalhar com objetos DateTime do PHP. Ela aceita strings de data absolutas e relativas, opcionalmente recebe um fuso horário e retorna false em caso de falha para que você possa validar a entrada sem tratamento de exceções. Depois de ter um DateTime, formate-o com ->format() e compare ou subtraia objetos diretamente. Para analisar entradas não padronizadas, use date_create_from_format(); para renderizar resultados, use date_format().

Prática