feat: add weather overview endpoint

Author: andrepimpao

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;

src/Exception/ApiErrorException.php

@@ -8,7 +8,9 @@ class ApiErrorException extends \Exception
 
     public function __construct(array $error)
     {
-        parent::__construct($error['message'], $error['cod']);
+        $code = $error['cod'] ?? $error['code'];
+
+        parent::__construct($error['message'], $code);
 
         $this->parameters = $error['parameters'] ?? null;
     }

src/Resource/OneCallResource.php

@@ -5,6 +5,7 @@
 use ProgrammatorDev\Api\Method;
 use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\Weather;
 use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\WeatherMoment;
+use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\WeatherOverview;
 use ProgrammatorDev\OpenWeatherMap\Entity\OneCall\WeatherSummary;
 use ProgrammatorDev\OpenWeatherMap\Resource\Util\LanguageTrait;
 use ProgrammatorDev\OpenWeatherMap\Resource\Util\UnitSystemTrait;
@@ -77,4 +78,24 @@ public function getWeatherSummaryByDate(float $latitude, float $longitude, \Date
 
         return new WeatherSummary($data);
     }
+
+    /**
+     * Get the weather overview with a human-readable summary for today and tomorrow's forecast, using OpenWeather AI
+     *
+     * @throws ClientExceptionInterface
+     */
+    public function getWeatherOverviewByDate(float $latitude, float $longitude, \DateTimeInterface $date): WeatherOverview
+    {
+        $data = $this->api->request(
+            method: Method::GET,
+            path: '/data/3.0/onecall/overview',
+            query: [
+                'lat' => $latitude,
+                'lon' => $longitude,
+                'date' => $date->format('Y-m-d')
+            ]
+        );
+
+        return new WeatherOverview($data);
+    }
 }