Skip to content

weather.md

Latest commit

 

History

History
158 lines (125 loc) · 4.58 KB

weather.md

File metadata and controls

158 lines (125 loc) · 4.58 KB
Raw

Weather

Current

See the official Current Weather API documentation for API details.

Use current() with a latitude and longitude.

use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap;

$api = new OpenWeatherMap($_ENV['OPENWEATHERMAP_API_KEY']);

$current = $api->weather()->current(
    latitude: 38.7223,
    longitude: -9.1393,
);

current() returns a Current entity. Every property may be absent or explicitly null; missing or null condition lists become empty arrays. Coordinates are available through coordinates().

echo $current->name();
echo $current->coordinates()?->latitude();
echo $current->coordinates()?->longitude();
echo $current->temperature();
echo $current->feelsLikeTemperature();
echo $current->minimumTemperature();
echo $current->maximumTemperature();
echo $current->pressure();
echo $current->humidity();
echo $current->visibility();

minimumTemperature() and maximumTemperature() are OpenWeather's optional minimum and maximum temperatures for the city at the current moment. They are mainly useful for large cities and often match temperature(). They are not the day's forecast low and high.

Conditions, wind, and clouds are exposed as nested entities. A condition keeps the raw OpenWeather icon code and provides its absolute image URL. A response can contain multiple conditions; OpenWeather defines the first as the primary condition.

foreach ($current->conditions() as $condition) {
    echo $condition->group();
    echo $condition->description();
    echo $condition->icon();
    echo $condition->iconUrl();
}

echo $current->wind()?->speed();
echo $current->wind()?->direction();
echo $current->wind()?->gust();
echo $current->clouds()?->coverage();

Rain and snow are conditional. When present, lastHour() returns the precipitation reported for the preceding hour in millimetres per hour.

echo $current->rain()?->lastHour();
echo $current->snow()?->lastHour();

Observation, sunrise, and sunset timestamps are nullable UTC DateTimeImmutable values. timezoneOffset() provides the location's offset from UTC in seconds.

Forecast

See the official forecast documentation for API details.

Use forecast() with a latitude and longitude to retrieve up to five days of weather forecasts, with one period every three hours. The optional count limits the number of periods returned and must be positive.

$forecast = $api->weather()->forecast(
    latitude: 38.7223,
    longitude: -9.1393,
    count: 8,
);

forecast() returns a Forecast entity containing its periods and city metadata. Missing or null period lists become empty arrays.

use ProgrammatorDev\OpenWeatherMap\Enum\PartOfDay;

foreach ($forecast->periods() as $period) {
    echo $period->dateTime()?->format(DATE_ATOM);
    echo $period->temperature();
    echo $period->precipitationProbability();
    echo $period->wind()?->speed();
    echo $period->rain()?->lastThreeHours();
    echo $period->snow()?->lastThreeHours();

    if ($period->partOfDay() === PartOfDay::DAY) {
        // This period occurs during daytime at the forecast location.
    }
}

echo $forecast->city()?->name();
echo $forecast->city()?->coordinates()?->latitude();
echo $forecast->city()?->coordinates()?->longitude();
echo $forecast->city()?->timezoneOffset();

Precipitation probability follows the same getter pattern as other measurements:

$period->precipitationProbability();          // 60.0
$period->precipitationProbabilityUnit();      // Unit::PERCENT
$period->precipitationProbabilityWithUnit();  // '60 %'

Forecast, sunrise, and sunset timestamps are nullable UTC DateTimeImmutable values. The city timezone offset remains separate.

Units And Language

Weather requests use the API configuration by default. Configure units and language for a request with withUnits() and withLanguage().

use ProgrammatorDev\OpenWeatherMap\Enum\Language;
use ProgrammatorDev\OpenWeatherMap\Enum\Units;

$current = $api
    ->weather()
    ->withUnits(Units::METRIC)
    ->withLanguage(Language::PORTUGUESE)
    ->current(
        latitude: 38.7223,
        longitude: -9.1393,
    );

Measurement getters remain numeric. Companion Unit and WithUnit methods provide the unit and a formatted value. For example, when a metric response contains a temperature of 22.55:

$current->temperature();               // 22.55
$current->temperatureUnit();           // Unit::CELSIUS
$current->temperatureUnit()->symbol(); // '°C'
$current->temperatureWithUnit();       // '22.55 °C'