Merge pull request #63 from programmatordev/OPA-58-weather-overview-resource

Weather overview endpoint

Author: andrepimpao

composer.json

@@ -14,7 +14,7 @@
     "require": {
         "php": ">=8.1",
         "myclabs/deep-copy": "^1.13",
-        "programmatordev/php-api-sdk": "^2.0",
+        "programmatordev/php-api-sdk": "^2.1",
         "symfony/options-resolver": "^6.4|^7.3"
     },
     "require-dev": {

docs/03-supported-apis.md

@@ -5,6 +5,7 @@
     - [getWeather](#getweather)
     - [getWeatherByDate](#getweatherbydate)
     - [getWeatherSummaryByDate](#getweathersummarybydate)
+    - [getWeatherOverviewByDate](#getweatheroverviewbydate)
   - [Weather](#weather)
     - [getCurrent](#getcurrent)
     - [getForecast](#getforecast)
@@ -68,6 +69,21 @@ Returns a [`WeatherSummary`](05-entities.md#weathersummary) object:
 $weatherSummary = $api->oneCall()->getWeatherSummaryByDate(50, 50, new \DateTime('1985-07-19'));
 ```
 
+#### `getWeatherOverviewByDate`
+
+```php
+getWeatherOverviewByDate(float $latitude, float $longitude, \DateTimeInterface $date): WeatherOverview
+```
+
+Get the weather overview with a human-readable summary for today and tomorrow's forecast, 
+using OpenWeather AI.
+
+Returns a [`WeatherOverview`](05-entities.md#weatheroverview) object:
+
+```php
+$weatherOverview = $api->oneCall()->getWeatherOverviewByDate(50, 50, new \DateTime('today'));
+```
+
 ### Weather
 
 #### `getCurrent`

docs/05-entities.md

@@ -78,6 +78,13 @@
 - `getAtmosphericPressure()`: `int`
 - `getWind()`: [`Wind`](#wind)
 
+### WeatherOverview
+
+- `getCoordinate()`: [`Coordinate`](#coordinate)
+- `getTimezone()`: [`Timezone`](#timezone)
+- `getDateTime()`: `\DateTimeImmutable`
+- `getOverview()`: `string`
+
 ### WeatherData
 
 - `getDateTime()`: `\DateTimeImmutable`

src/Entity/AirPollution/AirPollutionCollection.php

@@ -18,7 +18,7 @@ class AirPollutionCollection
 
     public function __construct(array $data)
     {
-        $this->numResults = \count($data['list']);
+        $this->numResults = count($data['list']);
         $this->coordinate = new Coordinate($data['coord']);
         $this->data = $this->createEntityList(AirPollutionData::class, $data['list']);
     }

src/Entity/AirPollution/AirQuality.php

@@ -28,12 +28,12 @@ private function findQualitativeName(int $index): string
     {
         // levels based on https://openweathermap.org/api/air-pollution
         return match ($index) {
-            0 => 'Undefined',
             1 => 'Good',
             2 => 'Fair',
             3 => 'Moderate',
             4 => 'Poor',
-            5 => 'Very Poor'
+            5 => 'Very Poor',
+            default => 'Undefined'
         };
     }
 }

src/Entity/OneCall/DayData.php

@@ -28,7 +28,7 @@ public function __construct(array $data)
 
         $this->temperature = new Temperature($data['temp']);
         $this->temperatureFeelsLike = new Temperature($data['feels_like']);
-        $this->precipitationProbability = \round($data['pop'] * 100);
+        $this->precipitationProbability = round($data['pop'] * 100);
         $this->summary = $data['summary'];
         $this->moonPhase = new MoonPhase($data);
         $this->moonriseAt = \DateTimeImmutable::createFromFormat('U', $data['moonrise']);

src/Entity/OneCall/HourData.php

@@ -19,7 +19,7 @@ public function __construct(array $data)
         $this->temperature = $data['temp'];
         $this->temperatureFeelsLike = $data['feels_like'];
         $this->visibility = $data['visibility'];
-        $this->precipitationProbability = \round($data['pop'] * 100);
+        $this->precipitationProbability = round($data['pop'] * 100);
     }
 
     public function getTemperature(): float

src/Entity/OneCall/MoonPhase.php

@@ -23,7 +23,7 @@ public function __construct(array $data)
     {
         $this->value = $data['moon_phase'];
         $this->systemName = $this->findSystemName($this->value);
-        $this->name = \ucwords(\strtolower(\str_replace('_', ' ', $this->systemName)));
+        $this->name = ucwords(strtolower(str_replace('_', ' ', $this->systemName)));
     }
 
     public function getValue(): float

src/Entity/OneCall/WeatherOverview.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace ProgrammatorDev\OpenWeatherMap\Entity\OneCall;
+
+use ProgrammatorDev\OpenWeatherMap\Entity\Coordinate;
+use ProgrammatorDev\OpenWeatherMap\Entity\Timezone;
+
+class WeatherOverview
+{
+    private Coordinate $coordinate;
+
+    private Timezone $timezone;
+
+    private \DateTimeImmutable $dateTime;
+
+    private string $overview;
+
+    public function __construct(array $data)
+    {
+        $this->coordinate = new Coordinate($data);
+
+        $this->timezone = new Timezone([
+            'timezone_offset' => \DateTimeImmutable::createFromFormat('P', $data['tz'])->getOffset()
+        ]);
+
+        $this->dateTime = \DateTimeImmutable::createFromFormat(
+            'Y-m-d H:i:s P',
+            sprintf('%s 00:00:00 %s', $data['date'], $data['tz'])
+        );
+
+        $this->overview = $data['weather_overview'];
+    }
+
+    public function getCoordinate(): Coordinate
+    {
+        return $this->coordinate;
+    }
+
+    public function getTimezone(): Timezone
+    {
+        return $this->timezone;
+    }
+
+    public function getDateTime(): \DateTimeImmutable
+    {
+        return $this->dateTime;
+    }
+
+    public function getOverview(): string
+    {
+        return $this->overview;
+    }
+}

src/Entity/OneCall/WeatherSummary.php

@@ -36,7 +36,7 @@ public function __construct(array $data)
 
         $this->dateTime = \DateTimeImmutable::createFromFormat(
             'Y-m-d H:i:s P',
-            \sprintf('%s 00:00:00 %s', $data['date'], $data['tz'])
+            sprintf('%s 00:00:00 %s', $data['date'], $data['tz'])
         );
 
         $this->cloudiness = \round($data['cloud_cover']['afternoon']);
@@ -52,11 +52,11 @@ public function __construct(array $data)
             'max' => $data['temperature']['max']
         ]);
 
-        $this->atmosphericPressure = \round($data['pressure']['afternoon']);
+        $this->atmosphericPressure = round($data['pressure']['afternoon']);
 
         $this->wind = new Wind([
             'speed' => $data['wind']['max']['speed'],
-            'deg' => \round($data['wind']['max']['direction'])
+            'deg' => round($data['wind']['max']['direction'])
         ]);
     }
 
@@ -70,9 +70,6 @@ public function getTimezone(): Timezone
         return $this->timezone;
     }
 
-    /**
-     * DateTime in UTC
-     */
     public function getDateTime(): \DateTimeImmutable
     {
         return $this->dateTime;