HOWTO · PHP

Como converter String para Data e Data/Hora em PHP

Aprenda a analisar strings de data em PHP com `strtotime()` e `date()`, usando também `DateTime::createFromFormat()` ou `date_create_from_format()` quando a entrada seguir um formato conhecido.

Nesta página

Uma string de data é texto até que o PHP a interprete. A análise transforma esse texto em um timestamp ou objeto de data e hora; em seguida, a formatação converte o valor analisado na representação de que sua aplicação precisa. Use strtotime() quando a entrada for uma expressão de data conhecida e sem ambiguidades. Se ela seguir um padrão conhecido, prefira um formato explícito com DateTime::createFromFormat() ou sua alternativa procedural, date_create_from_format().

Escolha a abordagem correta para analisar datas em PHP

Use strtotime() para strings comuns, como uma data no formato ISO, quando uma interpretação flexível for aceitável. A função retorna um timestamp Unix ou false, e date() formata um timestamp. Para um padrão de entrada fixo, o método DateTime::createFromFormat() explicita a ordem esperada dos campos e retorna um objeto de data e hora ou false. A função procedural date_create_from_format() oferece o mesmo tipo de análise sem chamar diretamente o método estático.

Essas funções não eliminam ambiguidades na entrada. Se os usuários puderem informar datas segundo convenções diferentes, defina e valide o formato esperado no ponto de entrada dos dados. Em todos os casos, escolha deliberadamente o fuso horário ao interpretar uma data e hora; caso contrário, será usado o fuso horário padrão configurado no PHP.

Analise strings de data flexíveis com strtotime() e date()

Para uma string conhecida de data e hora, analise-a com strtotime() e passe o timestamp retornado para date(). Verifique se o resultado é false antes de formatá-lo, para não usar como timestamp o resultado de uma análise malsucedida. O exemplo usa formatos de entrada e saída fixos, portanto seu resultado é reproduzível independentemente do relógio atual da máquina.

Execute este exemplo. As mensagens textuais que ele pode exibir permanecem em inglês.

<?php
$dateString = '2023-10-15 14:30:00';
$timestamp = strtotime($dateString);

if ($timestamp === false) {
    echo "Could not parse the date string.";
} else {
    echo date('Y-m-d H:i:s', $timestamp);
}

strtotime() aceita muitas expressões textuais de data, mas essa flexibilidade não substitui a definição de um formato de entrada. O resultado representa um instante interpretado segundo as regras de fuso horário; date() formata o timestamp usando o fuso horário padrão do PHP. Se a origem tiver um fuso horário conhecido, inclua-o ou aplique-o explicitamente, em vez de depender de uma configuração do servidor.

Analise um formato conhecido com DateTime::createFromFormat()

Quando a string tiver uma estrutura definida, informe a string de formato correspondente. No formato abaixo, d, m, Y, H e i representam, respectivamente, dia, mês, ano com quatro dígitos, hora e minuto. O ! inicial redefine os campos que não estão presentes na entrada, em vez de herdar os segundos da data atual ou outros campos. As mensagens textuais que o exemplo pode exibir permanecem em inglês.

<?php
$dateString = '15-10-2023 14:30';
$dateFormat = '!d-m-Y H:i';
$dateTime = DateTime::createFromFormat($dateFormat, $dateString);

if ($dateTime === false) {
    echo "Could not parse the date string.";
} else {
    echo $dateTime->format('Y-m-d H:i:s');
}

O formato deve descrever a entrada, não a saída desejada. Após a análise, chame format() com o padrão de saída desejado. Um resultado diferente de false, por si só, não garante que todos os componentes do calendário tenham sido aceitos exatamente como esperado: o PHP pode normalizar alguns valores fora do intervalo e emitir avisos. Para validar a entrada com rigor, consulte DateTime::getLastErrors() após a análise, conforme descrito abaixo.

Use a função procedural date_create_from_format()

A função procedural é útil em código que já usa as funções de data do PHP. Ela aceita o mesmo formato e a mesma string de entrada e retorna um objeto DateTime em caso de sucesso ou false quando a análise falha. Formate o objeto retornado com date_format() somente depois de verificar que ele é um objeto. As mensagens textuais que o exemplo pode exibir permanecem em inglês.

<?php
$dateString = '2023/10/15 14:30';
$dateFormat = '!Y/m/d H:i';
$dateTime = date_create_from_format($dateFormat, $dateString);

if ($dateTime === false) {
    echo "Could not parse the date string.";
} else {
    echo date_format($dateTime, 'Y-m-d H:i:s');
}

Esta é a alternativa procedural a DateTime::createFromFormat(): ambas analisam a entrada segundo o formato informado e produzem um objeto DateTime. Escolha o estilo mais adequado ao código ao redor. Não é necessário considerar uma versão específica do PHP para escolher entre elas; consulte a documentação da versão compatível com sua aplicação para verificar a disponibilidade da API.

Lide com entradas ambíguas, erros de análise e fusos horários

Uma string como 03/04/2023 pode significar 4 de março ou 3 de abril, dependendo da convenção. Não deduza a intenção apenas pelos separadores. Se a origem tiver uma estrutura conhecida, passe o formato exato para DateTime::createFromFormat() e valide o resultado. strtotime() é conveniente para strings convencionais e claramente especificadas, mas não consegue inferir a convenção pretendida pelo usuário.

DateTime::createFromFormat() e date_create_from_format() podem retornar false; verifique esse resultado antes de chamar um método do objeto ou date_format(). Também podem aceitar um valor e, ao mesmo tempo, emitir avisos de análise, por exemplo quando o PHP normaliza um componente da data. Quando a validade exata do calendário for importante, verifique também os diagnósticos da análise. As mensagens textuais que o exemplo pode exibir permanecem em inglês:

<?php
$dateTime = DateTime::createFromFormat('!Y-m-d', '2023-02-31');
$errors = DateTime::getLastErrors();

if ($dateTime === false || ($errors !== false && ($errors['warning_count'] > 0 || $errors['error_count'] > 0))) {
    echo "The date is not valid for the specified format.";
} else {
    echo $dateTime->format('Y-m-d');
}

O ! redefine os campos não especificados, enquanto getLastErrors() informa os avisos e erros da análise mais recente. Os detalhes dos diagnósticos podem variar entre versões do PHP; por isso, teste a política de validação nas versões compatíveis com sua aplicação. Para datas e horas vinculadas a uma região específica, crie um DateTimeZone para essa região e passe-o como terceiro argumento para DateTime::createFromFormat() (ou como o argumento de fuso horário correspondente na função procedural). Se a entrada contiver um deslocamento UTC explícito, preserve-o ou converta-o intencionalmente antes de formatar o valor para exibição.