Função PHP strtotime: Entendendo a Análise de Data e Hora

Na programação PHP, trabalhar com datas e horas é uma tarefa comum que pode ser desafiadora devido à variedade de formatos e fusos horários usados em diferentes sistemas e aplicações. A função strtotime é uma ferramenta poderosa que pode ajudar os desenvolvedores a analisar e manipular strings de data e hora com facilidade, mas também requer uma boa compreensão de sua sintaxe e opções para evitar erros e resultados inesperados. Neste artigo, exploraremos a função strtotime e seu uso em detalhes, fornecendo exemplos e dicas que podem ajudá-lo a melhorar suas habilidades de programação PHP.

O que é a Função strtotime?

A função strtotime é uma função PHP integrada que converte uma representação em string de uma data e/ou hora em um timestamp Unix, que é um valor numérico que representa o número de segundos decorridos desde 1º de janeiro de 1970, 00:00:00 UTC (Tempo Universal Coordenado). O timestamp Unix é um formato amplamente utilizado para armazenar e manipular datas e horas em muitas linguagens de programação e sistemas, e permite comparação, cálculo e formatação fáceis de datas e horas.

A sintaxe da função strtotime é a seguinte:

A sintaxe da função strtotime()

<?php

strtotime ( string $time [, int $now = time() ] ) : int|false

onde $time é a string de entrada que contém a data e/ou hora a ser analisada, e $now é um parâmetro opcional que especifica o timestamp de referência usado para cálculos relativos. A função retorna um timestamp Unix se a string de entrada for válida, ou false se a string não puder ser analisada.

Como o valor de retorno é apenas um número de segundos, você quase sempre combina strtotime() com date() para convertê-lo de volta em algo legível por humanos:

<?php

date_default_timezone_set('UTC');

$timestamp = strtotime("2023-03-03");
echo $timestamp;                                  // 1677801600
echo date("Y-m-d H:i:s", $timestamp);             // 2023-03-03 00:00:00

Como Usar a Função strtotime?

A função strtotime suporta uma ampla variedade de formatos de entrada e modificadores que podem ser combinados para analisar várias expressões de data e hora. Alguns dos formatos e modificadores mais comuns são:

• Formatos de data: YYYY-MM-DD, MM/DD/YYYY, DD-MM-YYYY, YYYY.MM.DD, etc.
• Formatos de hora: HH:MM:SS, HH:MM, H:M:S AM/PM, HH:MM:SS +/-HHMM, etc.
• Deslocamentos de fuso horário: +HHMM, -HHMM, Z, etc.
• Expressões relativas: now, yesterday, today, tomorrow, last/next day/week/month/year, +/- N days/weeks/months/years, first/last day/weekday/week/month/year of month/year, etc.

Para usar a função strtotime, você precisa passar uma string que contenha um ou mais desses formatos e modificadores, e a função tentará interpretá-los e convertê-los em um timestamp Unix. Veja alguns exemplos:

Como Usar a Função strtotime?

Como você pode ver, a função strtotime pode lidar com vários formatos de entrada e expressões relativas, mas é importante notar que o comportamento da função pode variar dependendo do fuso horário do sistema, da versão do PHP e da sintaxe e contexto da string de entrada. Portanto, é recomendável usar a função strtotime com cautela e sempre testar e validar o resultado antes de usá-lo em código de produção.

Cálculo de datas relativas

Um dos recursos mais úteis do strtotime() é a análise de expressões relativas em relação a um timestamp base. Isso torna trivial questões como "qual é a data daqui a uma semana?" ou "o primeiro dia do próximo mês":

<?php

date_default_timezone_set('UTC');

$base = strtotime("2023-03-03");

echo date("Y-m-d", strtotime("+1 week", $base));                  // 2023-03-10
echo date("Y-m-d", strtotime("first day of next month", $base));  // 2023-04-01

Tratando o valor de retorno false

strtotime() retorna false (não uma exceção) quando não consegue entender a entrada. Note que false é frouxamente igual a 0, então sempre verifique com o operador estrito === — caso contrário, uma análise malsucedida pode ser confundida com a época (1º de janeiro de 1970):

<?php

$timestamp = strtotime("not a real date");

var_dump($timestamp);             // bool(false)

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

Dicas e Boas Práticas

Aqui estão algumas dicas e boas práticas a seguir ao usar a função strtotime em seu código PHP:

1. Sempre higienize e valide a entrada do usuário: Como a função strtotime aceita entrada do usuário como string, é importante garantir que a entrada seja limpa e segura para uso. Você pode usar funções como trim, strip_tags, htmlspecialchars e expressões regulares para filtrar caracteres indesejados e prevenir ataques de injeção.
2. Use formatos e fusos horários explícitos: Para evitar ambiguidade e erros, é recomendável usar formatos de data e hora explícitos, como ISO 8601, e especificar o fuso horário explicitamente, seja como uma string ou como um objeto DateTimeZone. Isso pode ser feito usando funções como date, gmdate, DateTime, DateTimeImmutable e DateTimeZone.
3. Teste e depure seu código: Para garantir que sua função strtotime funcione conforme o esperado, você deve testá-la com várias strings de entrada, casos extremos e cenários, e verificar o resultado em relação às suas expectativas. Você pode usar ferramentas como var_dump, print_r e assert para depurar seu código e detectar erros.
4. Considere usar bibliotecas alternativas de data e hora: Embora a função strtotime seja uma ferramenta conveniente e poderosa, ela tem algumas limitações e peculiaridades que podem causar problemas em determinadas situações. Portanto, você pode querer considerar o uso de bibliotecas alternativas de data e hora, como Carbon ou Chronos, que oferecem mais recursos e flexibilidade.

Nota sobre PHP moderno: Para novos projetos, as classes DateTime e DateTimeImmutable são fortemente recomendadas em vez de strtotime devido à maior confiabilidade, design orientado a objetos e tratamento explícito de fuso horário. Use strtotime principalmente para código legado ou análise simples de datas relativas. Consulte date_create e date_modify para os equivalentes orientados a objetos.

Funções relacionadas

• date — formata um timestamp Unix em uma string legível.
• mktime — cria um timestamp a partir de partes individuais de data em vez de uma string.
• time — retorna o timestamp Unix atual.
• date_create — a forma moderna e orientada a objetos de analisar datas.
• PHP Date and Time — visão geral do kit de ferramentas de data/hora do PHP.

Conclusão

Neste artigo, exploramos a função strtotime em PHP e seu uso na análise e manipulação de strings de data e hora. Vimos como a função funciona, quais formatos e modificadores ela suporta e quais dicas e boas práticas seguir ao usá-la em seu código. Ao aplicar esses princípios, você pode melhorar suas habilidades de programação PHP e escrever código de manipulação de datas mais confiável. Lembre-se de sempre validar e higienizar a entrada do usuário, usar formatos e fusos horários explícitos, testar e depurar seu código e considerar o uso de bibliotecas alternativas, se necessário. Boas programações!

graph TD;
A[strtotime Function] --> B[Unix timestamp];
B --> C[Date comparison];
B --> D[Date calculation];
B --> E[Date formatting];
C --> F[Equal to];
C --> G[Greater than];
C --> H[Less than];
D --> I[Addition];
D --> J[Subtraction];
E --> K[Textual representation];
E --> L[Numeric representation];

Prática