date_format()

date_format()

Introdução

Datas e horas estão em toda parte em aplicações reais: timestamps em posts de blog, datas de pedidos em lojas online, entradas de log, eventos de calendário. PHP armazena esses momentos internamente de uma forma que não é legível por humanos, por isso você precisa de uma maneira de transformar um objeto de data em uma string que uma pessoa possa ler — "2023-03-03", "Friday, March 3rd", ou "03/03/2023 1:00 PM". É exatamente isso que date_format() faz.

Este capítulo aborda o que é date_format(), sua sintaxe, os caracteres de formato mais úteis e as armadilhas relacionadas a fusos horários e imutabilidade.

O que é a função date_format()?

A função date_format() formata um objeto DateTime como uma string de acordo com um padrão que você fornece. É um alias procedural para o método orientado a objetos DateTime::format() — ambos produzem resultados idênticos, então use o estilo que melhor se adapta ao seu código:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

// These two lines are equivalent
echo date_format($date, 'Y-m-d');   // procedural
echo $date->format('Y-m-d');        // object-oriented

Sintaxe

date_format(DateTimeInterface $object, string $format): string

• $object — uma instância de DateTime (ou DateTimeImmutable). Esta é a data que você deseja renderizar.
• $format — uma string construída a partir de caracteres de formato (como Y, m, d). Qualquer caractere que não seja um caractere de formato é impresso literalmente.
• Valor de retorno — a data formatada como uma string.

Como usar a função date_format()

Primeiro, crie um objeto de data com a classe DateTime, que é integrada ao PHP:

<?php

$date = new DateTime('2023-03-03');

Isso cria uma data definida para 3 de março de 2023, à meia-noite. Por padrão, DateTime usa o fuso horário configurado no servidor — o que significa que o mesmo código pode produzir saídas diferentes em máquinas diferentes. Para resultados previsíveis, sempre defina o fuso horário explicitamente:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

Agora formate-a como desejar:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'Y-m-d');
// Output: 2023-03-03

Para aplicações PHP modernas, prefira DateTimeImmutable em vez de DateTime. Métodos como modify() modificam um DateTime no local, o que é uma fonte comum de bugs quando o objeto é passado entre funções; DateTimeImmutable retorna um novo objeto em vez disso e funciona com date_format() exatamente da mesma forma:

<?php

$date = new DateTimeImmutable('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'd/m/Y');
// Output: 03/03/2023

Formatos de data comuns

Há muitas maneiras diferentes de formatar datas usando a função date_format(). Aqui estão alguns dos formatos mais comuns:

• Y-m-d: A data no formato YYYY-MM-DD.
• d/m/Y: A data no formato DD/MM/YYYY.
• m/d/Y: A data no formato MM/DD/YYYY.
• H:i:s: A hora no formato 24 horas (por exemplo, 13:00:00).
• h:i:s a: A hora no formato 12 horas (por exemplo, 01:00:00 am).

Caracteres de formato

Além dos formatos comuns acima, você pode construir seu próprio padrão a partir de caracteres de formato individuais. Aqui estão os mais usados com frequência:

• Y: O ano em quatro dígitos (por exemplo, 2023).
• y: O ano em dois dígitos (por exemplo, 23).
• m: O mês como um número de dois dígitos (por exemplo, 03).
• M: O nome abreviado do mês (por exemplo, Mar).
• F: O nome completo do mês (por exemplo, March).
• d: O dia do mês como um número de dois dígitos (por exemplo, 03).
• D: O nome abreviado do dia (por exemplo, Fri).
• l: O nome completo do dia (por exemplo, Friday).
• j: O dia do mês sem zeros à esquerda (por exemplo, 3).
• S: Sufixo ordinal em inglês para o dia do mês (por exemplo, st, nd, rd, th).
• H: A hora no formato 24 horas (por exemplo, 13).
• h: A hora no formato 12 horas (por exemplo, 01).
• i: Os minutos como um número de dois dígitos (por exemplo, 05).
• s: Os segundos como um número de dois dígitos (por exemplo, 30).
• a: am ou pm.

Para a lista completa de todos os caracteres suportados, consulte PHP date and time e o capítulo date() — date_format() usa os mesmos caracteres.

Aqui está um exemplo de um formato de data personalizado:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, 'l, F jS Y, h:i:s a');
// Output: Friday, March 3rd 2023, 12:00:00 am

Para imprimir um caractere de formato literalmente em vez de interpretá-lo, escape-o com uma barra invertida:

<?php

$date = new DateTime('2023-03-03', new DateTimeZone('UTC'));

echo date_format($date, '\T\o\d\a\y \i\s l');
// Output: Today is Friday

date_format() vs date()

Ambas as funções formatam datas, mas recebem entradas diferentes:

• date() trabalha com um timestamp Unix (um inteiro) e usa "agora" como padrão. Use-o para formatação rápida e independente de fuso horário: date('Y-m-d').
• date_format() trabalha com um objeto DateTime, portanto ele carrega seu próprio fuso horário e suporta aritmética (adicionar dias, calcular diferenças) antes de você formatar. Use-o quando precisar manipular a data.

Se você tiver uma string como "3 March 2023", crie primeiro um DateTime — date_create_from_format() e strtotime() são os pontos de entrada habituais.

Conclusão

A função date_format() em PHP oferece uma maneira direta de formatar um objeto DateTime como uma string legível. Ao compreender os caracteres de formato disponíveis e as boas práticas — definir o fuso horário explicitamente e preferir DateTimeImmutable — você pode garantir uma saída de data precisa e previsível em todos os ambientes em que seu código for executado.

Prática