strftime()

Introdução

strftime() formata um timestamp Unix em uma string de data/hora legível por humanos usando especificadores no estilo POSIX (%Y, %B, %H, …) e — o ponto crucial — respeita o locale ativo. Isso fez dela a função preferida sempre que era preciso obter nomes de meses ou de dias da semana em um idioma diferente do inglês.

Este capítulo mostra como o strftime() funciona, lista os especificadores mais úteis e explica por que, em código novo, você deve preferir DateTime::format() ou IntlDateFormatter. O strftime() foi descontinuado no PHP 8.1 e removido no PHP 9.0, portanto entender tanto a abordagem antiga quanto a nova é importante ao manter ou migrar uma base de código.

Sintaxe

strftime(string $format, ?int $timestamp = null): string|false

• $format — uma string com texto literal e especificadores % (veja a tabela abaixo).
• $timestamp — um timestamp Unix. Se omitido (ou null), o horário atual é usado, então raramente é necessário passar time() explicitamente.

A função retorna a string formatada ou false em caso de falha.

Como o strftime() difere do date()

Ambas as funções transformam um timestamp em uma string, mas atendem a necessidades diferentes:

Portanto, se você só precisa de saída em inglês, date() é mais simples. O motivo histórico para escolher o strftime() eram os nomes de meses e dias da semana localizados.

Um exemplo básico

Aqui, date() formata o horário atual como mês/dia/ano, produzindo uma saída como 03/03/2023. Essa é a base apenas em inglês que o strftime() estende com localização.

Usando strftime() para uma saída sensível ao locale

%B é o nome completo do mês, %d o dia com zero à esquerda e %Y o ano com quatro dígitos, de modo que a saída fica parecida com March 03, 2023. O poder do strftime() aparece quando você troca o locale.

Trocando o locale

Para que especificadores como %B (nome do mês) e %A (nome do dia da semana) retornem texto localizado, defina o locale LC_TIME antes de chamar strftime(), usando setlocale():

<?php
setlocale(LC_TIME, 'fr_FR.UTF-8');           // French
echo strftime('%A %d %B %Y', mktime(0, 0, 0, 3, 3, 2023));
// → "vendredi 03 mars 2023"
?>

A string exata do locale (fr_FR.UTF-8, de_DE.UTF-8, …) precisa estar instalada no servidor; caso contrário, setlocale() retorna false e a saída volta para o locale C/inglês.

Especificadores comuns

A substituição moderna

Como o strftime() deixa de existir no PHP 9.0, o código novo deve formatar datas com DateTime ou, para localização completa, com IntlDateFormatter, da extensão intl:

<?php
// English-only output: DateTime::format() with date()-style letters
$dt = new DateTime('2023-03-03');
echo $dt->format('F d, Y');   // March 03, 2023

// Localized output without a server-wide locale: IntlDateFormatter
$fmt = new IntlDateFormatter(
    'fr_FR',
    IntlDateFormatter::FULL,
    IntlDateFormatter::NONE
);
echo "\n", $fmt->format($dt);  // vendredi 3 mars 2023
?>

IntlDateFormatter é o caminho recomendado: é baseado em ICU, não depende de locales instalados no sistema operacional e não é afetado pela descontinuação. Consulte DateTime::format() para o conjunto completo de especificadores.

Pontos de atenção

• Passe um timestamp, não um DateTime. O strftime() espera um timestamp Unix inteiro; crie um com mktime() ou strtotime().
• O locale precisa estar instalado. Um locale ausente degrada silenciosamente para o inglês — verifique o valor de retorno de setlocale().
• Use gmstrftime() se precisar de UTC em vez do fuso horário local.
• %e não está disponível no Windows. Alguns especificadores dependem da plataforma, pois o strftime() delega o trabalho à biblioteca C.

Conclusão

O strftime() formatava um timestamp em uma string sensível ao locale usando especificadores POSIX com %, e é por isso que era historicamente preferido a date() para nomes de meses e dias da semana em outros idiomas. Como foi descontinuado no PHP 8.1 e removido no 9.0, trate-o como legado: leia-o com confiança em código existente, mas escreva código novo com DateTime::format() ou IntlDateFormatter.

Prática