date_sunset()

Introdução

date_sunset() é uma função PHP legada que retorna o horário do pôr do sol para uma data e localização geográfica específicas. Esta página explica o que ela retornava, como seus parâmetros funcionavam, por que foi removida do PHP moderno e o que usar em seu lugar. Se você está escrevendo código novo, vá direto para Migração para o PHP moderno — mas entender a assinatura original ainda é útil para manter bases de código mais antigas.

O que date_sunset() faz

date_sunset() calculava o momento em que o sol mergulhava abaixo do horizonte para uma data específica e um ponto específico na Terra. Ela precisava de quatro informações:

• Uma data, fornecida como um timestamp Unix.
• Uma latitude e longitude identificando a posição do observador.
• Um ângulo de zênite — o ângulo, medido de cima para baixo a partir do ponto diretamente acima, no qual o sol é considerado "posto". O valor padrão de 90,83° é ligeiramente superior a um ângulo reto porque compensa a refração atmosférica (que curva a luz solar e faz o sol parecer mais alto do que realmente está) e o raio aparente do disco solar.

Por padrão, a função retornava uma string como "18:12", mas com o sinalizador correto ela podia retornar o resultado como um timestamp Unix, que você pode então formatar com date() ou converter com qualquer outra função de data.

Sintaxe

date_sunset(
    int $timestamp,
    int $returnFormat = SUNFUNCS_RET_STRING,
    float $latitude = ini_get("date.default_latitude"),
    float $longitude = ini_get("date.default_longitude"),
    float $zenith = ini_get("date.sunset_zenith"),
    float $utcOffset = 0
): mixed

Parâmetros

• timestamp — O timestamp Unix do dia para o qual calcular o pôr do sol. Construa-o com strtotime() ou mktime().
• returnFormat — Uma das três constantes que controlam o tipo de retorno:
  • SUNFUNCS_RET_STRING — uma string "HH:MM" (o padrão).
  • SUNFUNCS_RET_DOUBLE — o horário em horas desde a meia-noite (um float, por exemplo 18.2).
  • SUNFUNCS_RET_TIMESTAMP — um timestamp Unix.
• latitude — A latitude do observador em graus (positivo = norte).
• longitude — A longitude do observador em graus (positivo = leste, negativo = oeste).
• zenith — O ângulo de zênite do sol no pôr do sol; padrão 90,83°.
• utcOffset — O deslocamento em relação ao UTC em horas; ignorado quando returnFormat é um timestamp.

A função retornava false para localizações e datas em que o sol nunca se põe ou nunca nasce (por exemplo, os polos no verão ou no inverno).

Exemplo (PHP 7.x legado)

O exemplo a seguir é executado no PHP 7.x ou anterior, onde a função ainda existe:

Saída:

Sunset on March 3, 2023 in San Francisco was at 18:12

Como o resultado é um timestamp, você pode reformatá-lo como desejar — date("g:i A", $sunset) imprimiria 6:12 PM em vez disso.

Migração para o PHP moderno

date_sunset() não existe mais, e a classe DateTime integrada do PHP lida com fusos horários e formatação, mas não calcula posições solares. Portanto, um aplicativo moderno tem duas opções práticas.

Opção 1 — Chamar uma API de nascer/pôr do sol

A abordagem portátil mais simples é consultar um serviço público e ler o timestamp que ele retorna. Isso funciona em qualquer versão do PHP e não requer cálculos da sua parte:

<?php
// Free, no-key API: https://sunrise-sunset.org/api
$lat = 37.7749;
$lng = -122.4194;
$date = '2023-03-03';

$url = "https://api.sunrise-sunset.org/json?lat={$lat}&lng={$lng}&date={$date}&formatted=0";
$response = json_decode(file_get_contents($url), true);

// The API returns ISO-8601 UTC strings
$sunsetUtc = new DateTime($response['results']['sunset']);
$sunsetUtc->setTimezone(new DateTimeZone('America/Los_Angeles'));

echo "Sunset: " . $sunsetUtc->format('H:i');
?>

Opção 2 — Usar uma biblioteca de astronomia

Para um cálculo offline e independente, instale um pacote Composer mantido que implemente o mesmo algoritmo de pôr do sol (pesquise no Packagist por "sunrise sunset"; opções populares incluem tienvx/php-sunrise-sunset e andreas-glaser/php-sun-info). Os nomes exatos das classes dependem do pacote, portanto sempre consulte o README — a estrutura geral é: construir um calculador a partir de uma latitude/longitude e, em seguida, solicitar o pôr do sol de uma determinada data.

Onde os horários de pôr do sol são usados

Seja chamando date_sunset() (legado) ou uma das alternativas modernas acima, os dados de pôr do sol aparecem em muitos tipos de aplicativos:

1. Aplicativos de clima — exibem o pôr do sol do dia junto com a previsão para uma localização.
2. Aplicativos de fotografia — derivam a "hora dourada", o período logo antes do pôr do sol quando a luz é suave e quente, subtraindo uma hora do horário do pôr do sol.
3. Aplicativos de eventos e agendamento — sinalizam eventos ao ar livre que se estendem até o crepúsculo, ou alternam um site para o estilo escuro após o anoitecer.
4. Casa inteligente e iluminação — acionam luzes ou rotinas no horário local do pôr do sol.

Combine o horário do pôr do sol com date_sunrise() para obter a janela completa de luz do dia para uma localização.

Conclusão

date_sunset() era uma maneira conveniente de obter horários de pôr do sol com uma única chamada no PHP 7.x, mas foi removida no PHP 8.1 e falhará em qualquer ambiente moderno. Para código novo, chame uma API de nascer/pôr do sol ou use uma biblioteca de astronomia mantida, e formate o resultado com a classe DateTime. Os casos de uso — clima, fotografia, eventos, automação — permanecem os mesmos; apenas a fonte do cálculo foi movida para fora do núcleo do PHP.

Prática