Merge pull request #38 from programmatordev/1.x

1.x

Author: andrepimpao

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 programmatordev
+Copyright (c) 2023 Programmator
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -62,7 +62,7 @@ echo $currentWeather->getTemperature();
 
 ## Contributing
 
-Any form of contribution to improve this library will be welcome and appreciated.
+Any form of contribution to improve this library (including requests) will be welcome and appreciated.
 Make sure to open a pull request or issue.
 
 ## License

composer.json

@@ -17,6 +17,7 @@
         "php-http/client-common": "^2.7",
         "php-http/discovery": "^1.18",
         "php-http/logger-plugin": "^1.3",
+        "programmatordev/yet-another-php-validator": "^0.1.1",
         "psr/cache": "^2.0 || ^3.0",
         "psr/http-client": "^1.0",
         "psr/http-factory": "^1.0",

docs/03-supported-apis.md

@@ -2,58 +2,70 @@
 
 - [APIs](#apis)
   - [One Call](#one-call)
-    - [getWeather](#getweatherfloat-latitude-float-longitude)
-    - [getHistoryMoment](#gethistorymomentfloat-latitude-float-longitude-datetimeinterface-datetime)
-    - [getHistoryAggregate](#gethistoryaggregatefloat-latitude-float-longitude-datetimeinterface-date)
+    - [getWeather](#getweather)
+    - [getHistoryMoment](#gethistorymoment)
+    - [getHistoryAggregate](#gethistoryaggregate)
   - [Weather](#weather)
-    - [getCurrent](#getcurrentfloat-latitude-float-longitude)
-    - [getForecast](#getforecastfloat-latitude-float-longitude-int-numresults--40)
+    - [getCurrent](#getcurrent)
+    - [getForecast](#getforecast)
   - [Air Pollution](#air-pollution)
-    - [getCurrent](#getcurrentfloat-latitude-float-longitude-1)
-    - [getForecast](#getforecastfloat-latitude-float-longitude)
-    - [getHistory](#gethistoryfloat-latitude-float-longitude-datetimeinterface-startdate-datetimeinterface-enddate)
+    - [getCurrent](#getcurrent-1)
+    - [getForecast](#getforecast-1)
+    - [getHistory](#gethistory)
   - [Geocoding](#geocoding)
-    - [getByLocationName](#getbylocationnamestring-locationname-int-numresults--5)
-    - [getByZipCode](#getbyzipcodestring-zipcode-string-countrycode)
-    - [getByCoordinate](#getbycoordinatefloat-latitude-float-longitude-int-numresults--5)
+    - [getByLocationName](#getbylocationname)
+    - [getByZipCode](#getbyzipcode)
+    - [getByCoordinate](#getbycoordinate)
 - [Common Methods](#common-methods)
-  - [withUnitSystem](#withunitsystemstring-unitsystem)
-  - [withLanguage](#withlanguagestring-language)
-  - [withCacheTtl](#withcachettlint-time)
+  - [withUnitSystem](#withunitsystem)
+  - [withLanguage](#withlanguage)
+  - [withCacheTtl](#withcachettl)
 
 ## APIs
 
 ### One Call
 
-#### `getWeather(float $latitude, float $longitude)`
+#### `getWeather`
+
+```php
+getWeather(float $latitude, float $longitude): OneCall
+```
 
 Get current and forecast (minutely, hourly and daily) weather data.
 
-Returns a [`OneCall`](05-objects.md#onecall) object.
+Returns a [`OneCall`](05-objects.md#onecall) object:
 
 ```php
 $weather = $openWeatherMap->getOneCall()->getWeather(50, 50);
 
 echo $weather->getCurrent()->getTemperature();
 ```
 
-#### `getHistoryMoment(float $latitude, float $longitude, \DateTimeInterface $dateTime)`
+#### `getHistoryMoment`
+
+```php
+getHistoryMoment(float $latitude, float $longitude, \DateTimeInterface $dateTime): WeatherLocation
+```
 
 Get weather data from a single moment in the past.
 
-Returns a [`WeatherLocation`](05-objects.md#weatherlocation) object.
+Returns a [`WeatherLocation`](05-objects.md#weatherlocation) object:
 
 ```php
 $weather = $openWeatherMap->getOneCall()->getHistoryMoment(50, 50, new \DateTime('2023-01-01 12:00:00'));
 
 echo $weather->getTemperature();
 ```
 
-#### `getHistoryAggregate(float $latitude, float $longitude, \DateTimeInterface $date)`
+#### `getHistoryAggregate`
+
+```php
+getHistoryAggregate(float $latitude, float $longitude, \DateTimeInterface $date): WeatherAggregate
+```
 
 Get aggregated weather data from a single day in the past.
 
-Returns a [`WeatherAggregate`](05-objects.md#weatheraggregate) object.
+Returns a [`WeatherAggregate`](05-objects.md#weatheraggregate) object:
 
 ```php
 $weather = $openWeatherMap->getOneCall()->getHistoryAggregate(50, 50, new \DateTime('1985-07-19'));
@@ -63,23 +75,31 @@ echo $weather->getTemperature();
 
 ### Weather
 
-#### `getCurrent(float $latitude, float $longitude)`
+#### `getCurrent`
+
+```php
+getCurrent(float $latitude, float $longitude): WeatherLocation
+```
 
 Get current weather data.
 
-Returns a [`WeatherLocation`](05-objects.md#weatherlocation-1) object.
+Returns a [`WeatherLocation`](05-objects.md#weatherlocation-1) object:
 
 ```php
 $weather = $openWeatherMap->getWeather()->getCurrent(50, 50);
 
 echo $weather->getTemperature();
 ```
 
-#### `getForecast(float $latitude, float $longitude, int $numResults = 40)`
+#### `getForecast`
+
+```php
+getForecast(float $latitude, float $longitude, int $numResults = 40): WeatherLocationList
+```
 
 Get weather forecast data per 3-hour steps for the next 5 days.
 
-Returns a [`WeatherLocationList`](05-objects.md#weatherlocationlist) object.
+Returns a [`WeatherLocationList`](05-objects.md#weatherlocationlist) object:
 
 ```php
 // Since it returns 3-hour steps,
@@ -94,11 +114,15 @@ foreach ($weatherForecast->getList() as $weather) {
 
 ### Air Pollution
 
-#### `getCurrent(float $latitude, float $longitude)`
+#### `getCurrent`
+
+```php
+getCurrent(float $latitude, float $longitude): AirPollutionLocation
+```
 
 Get current air pollution data.
 
-Returns a [`AirPollutionLocation`](05-objects.md#airpollutionlocation) object.
+Returns a [`AirPollutionLocation`](05-objects.md#airpollutionlocation) object:
 
 ```php
 $airPollution = $openWeatherMap->getAirPollution()->getCurrent(50, 50);
@@ -107,11 +131,15 @@ echo $airPollution->getAirQuality()->getQualitativeName();
 echo $airPollution->getCarbonMonoxide();
 ```
 
-#### `getForecast(float $latitude, float $longitude)`
+#### `getForecast`
+
+```php
+getForecast(float $latitude, float $longitude): AirPollutionLocationList
+```
 
 Get air pollution forecast data per 1-hour for the next 24 hours.
 
-Returns a [`AirPollutionLocationList`](05-objects.md#airpollutionlocationlist) object.
+Returns a [`AirPollutionLocationList`](05-objects.md#airpollutionlocationlist) object:
 
 ```php
 $airPollutionForecast = $openWeatherMap->getAirPollution()->getForecast(50, 50);
@@ -123,11 +151,15 @@ foreach ($airPollutionForecast->getList() as $airPollution) {
 }
 ```
 
-#### `getHistory(float $latitude, float $longitude, \DateTimeInterface $startDate, \DateTimeInterface $endDate)`
+#### `getHistory`
+
+```php
+getHistory(float $latitude, float $longitude, \DateTimeInterface $startDate, \DateTimeInterface $endDate): AirPollutionLocationList
+```
 
 Get air pollution history data between two dates.
 
-Returns a [`AirPollutionLocationList`](05-objects.md#airpollutionlocationlist) object.
+Returns a [`AirPollutionLocationList`](05-objects.md#airpollutionlocationlist) object:
 
 ```php
 $startDate = new \DateTime('-7 days'); // 7 days ago
@@ -143,11 +175,18 @@ foreach ($airPollutionHistory->getList() as $airPollution) {
 
 ### Geocoding
 
-#### `getByLocationName(string $locationName, int $numResults = 5)`
+#### `getByLocationName`
+
+```php
+/**
+ * @return Location[]
+ */
+getByLocationName(string $locationName, int $numResults = 5): array
+```
 
 Get locations data by location name.
 
-Returns an array of [`Location`](05-objects.md#location) objects.
+Returns an array of [`Location`](05-objects.md#location) objects:
 
 ```php
 $locations = $openWeatherMap->getGeocoding()->getByLocationName('lisbon');
@@ -158,23 +197,34 @@ foreach ($locations as $location) {
 }
 ```
 
-#### `getByZipCode(string $zipCode, string $countryCode)`
+#### `getByZipCode`
+
+```php
+getByZipCode(string $zipCode, string $countryCode): ZipCodeLocation
+```
 
 Get location data by zip/post code.
 
-Returns a [`ZipCodeLocation`](05-objects.md#zipcodelocation) object.
+Returns a [`ZipCodeLocation`](05-objects.md#zipcodelocation) object:
 
 ```php
 $location = $openWeatherMap->getGeocoding()->getByZipCode('1000-001', 'pt');
 
 echo $location->getName();
 ```
 
-#### `getByCoordinate(float $latitude, float $longitude, int $numResults = 5)`
+#### `getByCoordinate`
+
+```php
+/**
+ * @return Location[]
+ */
+getByCoordinate(float $latitude, float $longitude, int $numResults = 5): array
+```
 
 Get locations data by coordinate.
 
-Returns an array of [`Location`](05-objects.md#location) objects.
+Returns an array of [`Location`](05-objects.md#location) objects:
 
 ```php
 $locations = $openWeatherMap->getGeocoding()->getByCoordinate(50, 50);
@@ -187,7 +237,11 @@ foreach ($locations as $location) {
 
 ## Common Methods
 
-#### `withUnitSystem(string $unitSystem)`
+#### `withUnitSystem`
+
+```php
+withUnitSystem(string $unitSystem): self
+```
 
 Makes a request with a different unit system from the one globally defined in the [configuration](02-configuration.md#unitsystem).
 
@@ -202,7 +256,11 @@ $openWeatherMap->getWeather()
     ->getCurrent(50, 50);
 ```
 
-#### `withLanguage(string $language)`
+#### `withLanguage`
+
+```php
+withLanguage(string $language): self
+```
 
 Makes a request with a different language from the one globally defined in the [configuration](02-configuration.md#language).
 
@@ -217,7 +275,11 @@ $openWeatherMap->getWeather()
     ->getCurrent(50, 50);
 ```
 
-#### `withCacheTtl(?int $time)`
+#### `withCacheTtl`
+
+```php
+withCacheTtl(?int $time): self
+```
 
 Makes a request and saves into cache with the provided time duration value (in seconds). 
 Check the [Cache TTL](02-configuration.md#cache-ttl) section for more information regarding default values.

docs/04-error-handling.md

@@ -73,19 +73,18 @@ catch (ApiErrorException $exception) {
 
 ## Validation Errors
 
-To catch invalid input data (like an out of range coordinate, blank location name, etc.), 
-the `ValidationException` is available:
+To catch invalid input data (like an out of range coordinate, blank location name, etc.), the `ValidationException` is available:
 
 ```php
-use ProgrammatorDev\OpenWeatherMap\Exception\ValidationException;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\ValidationException;
 
 try {
     // An invalid latitude value is given
     $weather = $openWeatherMap->getWeather()->getCurrent(999, 50);
 }
 catch (ValidationException $exception) {
     // Should print:
-    // The "latitude" value "999" is invalid. Must be between "-90" and "90".
+    // The "latitude" value should be between "-90" and "90", "999" given.
     echo $exception->getMessage();
 }
 ```

src/Config.php

@@ -2,21 +2,17 @@
 
 namespace ProgrammatorDev\OpenWeatherMap;
 
-use ProgrammatorDev\OpenWeatherMap\Exception\ValidationException;
 use ProgrammatorDev\OpenWeatherMap\HttpClient\HttpClientBuilder;
 use ProgrammatorDev\OpenWeatherMap\Language\Language;
 use ProgrammatorDev\OpenWeatherMap\UnitSystem\UnitSystem;
-use ProgrammatorDev\OpenWeatherMap\Validator\BlankValidatorTrait;
-use ProgrammatorDev\OpenWeatherMap\Validator\ChoiceValidatorTrait;
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\ValidationException;
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
 use Psr\Cache\CacheItemPoolInterface;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\OptionsResolver\OptionsResolver;
 
 class Config
 {
-    use BlankValidatorTrait;
-    use ChoiceValidatorTrait;
-
     private array $options;
 
     public function __construct(array $options = [])
@@ -62,7 +58,7 @@ public function getApplicationKey(): string
      */
     public function setApplicationKey(string $applicationKey): self
     {
-        $this->validateBlank('applicationKey', $applicationKey);
+        Validator::notBlank()->assert($applicationKey, 'applicationKey');
 
         $this->options['applicationKey'] = $applicationKey;
 
@@ -79,7 +75,7 @@ public function getUnitSystem(): string
      */
     public function setUnitSystem(string $unitSystem): self
     {
-        $this->validateChoice('unitSystem', $unitSystem, UnitSystem::getList());
+        Validator::choice(UnitSystem::getList())->assert($unitSystem, 'unitSystem');
 
         $this->options['unitSystem'] = $unitSystem;
 
@@ -96,7 +92,7 @@ public function getLanguage(): string
      */
     public function setLanguage(string $language): self
     {
-        $this->validateChoice('language', $language, Language::getList());
+        Validator::choice(Language::getList())->assert($language, 'language');
 
         $this->options['language'] = $language;