Plugin WordPress com fix de timezone (UTC)
Plugin com datas deslocadas 3h em cenários de cron. Regra única: UTC como fonte da verdade, conversão só no display. Zero tickets pós-deploy.
Contexto
O que é: fix de bug de timezone em plugin WordPress que integrava plataforma educacional externa (Lyceum) ao site institucional. Datas de turmas apareciam deslocadas 3 horas para alguns usuários, derrubando matrículas. Solução: UTC como single source of truth, conversão só no display layer com DateTimeImmutable.
Contexto: cascata de inconsistência típica de plugins que tratam data como string. Usuários em horário-padrão viam uma data; cron rodando em UTC persistia outra; página renderizada com date() do PHP mostrava uma terceira.
Problema
O plugin armazenava datas no timezone do servidor (America/Sao_Paulo) e exibia com date() do PHP, que usa o timezone atual do runtime. Em operações batch rodando em UTC via cron, as datas saíam erradas. Cascata de inconsistência.
Abordagem
Regra única: armazenar tudo em UTC, converter no display layer. DateTime nunca string. Parse e format sempre explícitos.
Execução
Criada classe dedicada a horários. Toda leitura/escrita passa por ela. Testes unitários simples cobrindo edge cases (DST, virada de dia, virada de mês).
<?php
declare( strict_types=1 );
final class Course_Schedule {
private const DISPLAY_TZ = 'America/Sao_Paulo';
public function save( string $local_datetime, string $tz = self::DISPLAY_TZ ): string {
$local = new DateTimeImmutable( $local_datetime, new DateTimeZone( $tz ) );
return $local
->setTimezone( new DateTimeZone( 'UTC' ) )
->format( DATE_ATOM );
}
public function display( string $utc_datetime ): string {
$utc = new DateTimeImmutable( $utc_datetime, new DateTimeZone( 'UTC' ) );
return $utc
->setTimezone( new DateTimeZone( self::DISPLAY_TZ ) )
->format( 'd/m/Y \à\s H:i' );
}
}Resultados
Output reutilizável
Padrão "UTC as single source of truth, convert at display" documentado para o time. Classe portável para outros plugins internos.