date_sun_info()

Introdução

A função date_sun_info() do PHP retorna os horários de nascer do sol, pôr do sol, trânsito e crepúsculo para uma data específica e localização geográfica. Em vez de buscar dados solares de um serviço externo, você passa um timestamp e um par de coordenadas e recebe de volta um array pronto com timestamps Unix. Esta página cobre a sintaxe, parâmetros, valores de retorno e um exemplo completo.

Nota: date_sun_info() foi descontinuada no PHP 8.1 e removida no PHP 8.2. Este tutorial é fornecido para manutenção de código legado. Para aplicações PHP modernas, considere um serviço externo (como a API Sunrise-Sunset) ou uma biblioteca dedicada como sunrise-sunset-php.

Sintaxe

date_sun_info(int $timestamp, float $latitude, float $longitude): array

Parâmetros

Valor de retorno

A função retorna um array associativo de timestamps Unix. Cada chave marca um evento solar para aquele dia nas coordenadas fornecidas:

Se o sol nunca nasce ou nunca se põe naquele dia (por exemplo, regiões polares no verão ou inverno), o valor relevante é true (sol está acima o dia todo) ou false (sol nunca nasce) em vez de um timestamp.

Usando a Função date_sun_info()

Como o primeiro argumento é um timestamp Unix, a abordagem mais simples é criar um objeto DateTime para o dia desejado e passar seu timestamp via getTimestamp(). O fluxo funciona assim:

graph TD;
    A[Create DateTime object] --> B[Get timestamp for the date];
    B --> C[Call date_sun_info with timestamp + coordinates];
    C --> D[Read sunrise / sunset / twilight from the result];

Aqui está um exemplo completo para Londres, Reino Unido:

Neste exemplo, criamos um objeto DateTime que representa uma data específica e especificamos a latitude e longitude de Londres, Reino Unido. Em seguida, chamamos a função date_sun_info() e passamos o timestamp do objeto DateTime, junto com a latitude e longitude.

A função date_sun_info() retorna um array que contém informações sobre o nascer do sol, pôr do sol e outros horários relacionados para a data e localização especificadas. Aqui está um exemplo da saída:

Array
(
    [sunrise] => 1646242025
    [sunset] => 1646282555
    [transit] => 1646262290
    [civil_twilight_begin] => 1646239733
    [civil_twilight_end] => 1646284847
    [nautical_twilight_begin] => 1646235838
    [nautical_twilight_end] => 1646288742
    [astronomical_twilight_begin] => 1646231998
    [astronomical_twilight_end] => 1646292582
)

Os valores são timestamps Unix brutos, então para exibi-los você formata cada um com date() ou date_format():

<?php
$sun_info = date_sun_info(strtotime('2023-03-03'), 51.5074, -0.1278);
echo 'Sunrise: ' . date('H:i:s', $sun_info['sunrise']) . "\n";
echo 'Sunset:  ' . date('H:i:s', $sun_info['sunset']) . "\n";
?>

Nota sobre fusos horários: A função espera um timestamp Unix (UTC). Os horários retornados também são timestamps UTC, calculados a partir das coordenadas fornecidas, independentemente do fuso horário local do servidor. Quando você os formata com date(), a saída usa o fuso horário definido por date_default_timezone_set(), então defina-o explicitamente se precisar de horários locais.

Funções relacionadas

• date_sunrise() — retorna apenas o horário do nascer do sol para uma localização.
• date_sunset() — retorna apenas o horário do pôr do sol para uma localização.
• Data e Hora no PHP — visão geral das ferramentas de data/hora do PHP.
• Fusos Horários no PHP — como o PHP lida com fusos horários.

Conclusão

date_sun_info() retorna o nascer do sol, pôr do sol, trânsito e as três fases do crepúsculo para uma data e localização específicas como um array de timestamps Unix UTC. Passe um timestamp mais latitude e longitude e, em seguida, formate os valores retornados com date() para exibi-los. É útil para recursos meteorológicos, de agendamento e baseados em localização — mas lembre-se de que foi removida no PHP 8.2, portanto, use uma API ou biblioteca externa em código moderno.

Prática