From 8f4532308ed93a21763e15fc0532d8cefd3408f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andre=CC=81=20Pimpa=CC=83o?= Date: Mon, 6 May 2024 20:03:00 +0100 Subject: [PATCH] docs: fixed typos and some improvements --- README.md | 2 +- docs/02-configuration.md | 4 ++-- docs/03-supported-apis.md | 22 ++++++++++----------- docs/04-error-handling.md | 41 ++++++++++++++++++++------------------- docs/05-entities.md | 2 +- 5 files changed, 36 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 0dfbe75..d54fbd1 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ echo $weather->getTemperature(); - [Configuration](docs/02-configuration.md) - [Supported APIs](docs/03-supported-apis.md) - [Error Handling](docs/04-error-handling.md) -- [Entities](docs/05-entities) +- [Entities](docs/05-entities.md) ## Contributing diff --git a/docs/02-configuration.md b/docs/02-configuration.md index 893c589..42ef512 100644 --- a/docs/02-configuration.md +++ b/docs/02-configuration.md @@ -31,7 +31,7 @@ Example: use ProgrammatorDev\OpenWeatherMap\UnitSystem\UnitSystem; use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap; -$api = new OpenWeatherMap('yourapikey', +$api = new OpenWeatherMap('yourapikey', [ 'unitSystem' => UnitSystem::IMPERIAL ]); ``` @@ -49,7 +49,7 @@ Example: use ProgrammatorDev\OpenWeatherMap\Language\Language; use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap; -$api = new OpenWeatherMap('yourapikey', +$api = new OpenWeatherMap('yourapikey', [ 'language' => Language::PORTUGUESE ]); ``` diff --git a/docs/03-supported-apis.md b/docs/03-supported-apis.md index 633dd99..afd06a1 100644 --- a/docs/03-supported-apis.md +++ b/docs/03-supported-apis.md @@ -33,7 +33,7 @@ getWeather(float $latitude, float $longitude): OneCall Get current and forecast (minutely, hourly and daily) weather data. -Returns a [`OneCall`](05-entities#onecall) object: +Returns a [`OneCall`](05-entities.md#onecall) object: ```php $weather = $openWeatherMap->oneCall()->getWeather(50, 50); @@ -49,7 +49,7 @@ getHistoryMoment(float $latitude, float $longitude, \DateTimeInterface $dateTime Get weather data from a single moment in the past. -Returns a [`WeatherLocation`](05-entities#weatherlocation) object: +Returns a [`WeatherLocation`](05-entities.md#weatherlocation) object: ```php $weather = $openWeatherMap->oneCall()->getHistoryMoment(50, 50, new \DateTime('2023-01-01 12:00:00')); @@ -65,7 +65,7 @@ getHistoryAggregate(float $latitude, float $longitude, \DateTimeInterface $date) Get aggregated weather data from a single day in the past. -Returns a [`WeatherAggregate`](05-entities#weatheraggregate) object: +Returns a [`WeatherAggregate`](05-entities.md#weatheraggregate) object: ```php $weather = $openWeatherMap->oneCall()->getHistoryAggregate(50, 50, new \DateTime('1985-07-19')); @@ -83,7 +83,7 @@ getCurrent(float $latitude, float $longitude): WeatherLocation Get current weather data. -Returns a [`WeatherLocation`](05-entities#weatherlocation-1) object: +Returns a [`WeatherLocation`](05-entities.md#weatherlocation-1) object: ```php $weather = $openWeatherMap->weather()->getCurrent(50, 50); @@ -99,7 +99,7 @@ getForecast(float $latitude, float $longitude, int $numResults = 40): WeatherLoc Get weather forecast data per 3-hour steps for the next 5 days. -Returns a [`WeatherLocationList`](05-entities#weatherlocationlist) object: +Returns a [`WeatherLocationList`](05-entities.md#weatherlocationlist) object: ```php // Since it returns 3-hour steps, @@ -122,7 +122,7 @@ getCurrent(float $latitude, float $longitude): AirPollutionLocation Get current air pollution data. -Returns a [`AirPollutionLocation`](05-entities#airpollutionlocation) object: +Returns a [`AirPollutionLocation`](05-entities.md#airpollutionlocation) object: ```php $airPollution = $openWeatherMap->airPollution()->getCurrent(50, 50); @@ -139,7 +139,7 @@ getForecast(float $latitude, float $longitude): AirPollutionLocationList Get air pollution forecast data per 1-hour for the next 24 hours. -Returns a [`AirPollutionLocationList`](05-entities#airpollutionlocationlist) object: +Returns a [`AirPollutionLocationList`](05-entities.md#airpollutionlocationlist) object: ```php $airPollutionForecast = $openWeatherMap->airPollution()->getForecast(50, 50); @@ -159,7 +159,7 @@ getHistory(float $latitude, float $longitude, \DateTimeInterface $startDate, \Da Get air pollution history data between two dates. -Returns a [`AirPollutionLocationList`](05-entities#airpollutionlocationlist) object: +Returns a [`AirPollutionLocationList`](05-entities.md#airpollutionlocationlist) object: ```php $startDate = new \DateTime('-7 days'); // 7 days ago @@ -177,7 +177,7 @@ foreach ($airPollutionHistory->getList() as $airPollution) { #### `getByLocationName` -Get locations by location name. Returns an array of [`Location`](05-entities#location) entities: +Get locations by location name. Returns an array of [`Location`](05-entities.md#location) entities: ```php /** @@ -192,7 +192,7 @@ $api->geocoding()->getByLocationName('lisbon'); #### `getByCoordinate` -Get locations by coordinate. Returns an array of [`Location`](05-entities#location) entities: +Get locations by coordinate. Returns an array of [`Location`](05-entities.md#location) entities: ```php /** @@ -207,7 +207,7 @@ $api->geocoding()->getByCoordinate(50, 50); #### `getByZipCode` -Get location by zip code. Returns a [`Location`](05-entities#location) entity: +Get location by zip code. Returns a [`Location`](05-entities.md#location) entity: ```php getByZipCode(string $zipCode, string $countryCode): Location diff --git a/docs/04-error-handling.md b/docs/04-error-handling.md index 27327a7..5121d6f 100644 --- a/docs/04-error-handling.md +++ b/docs/04-error-handling.md @@ -15,36 +15,36 @@ use ProgrammatorDev\OpenWeatherMap\Exception\UnauthorizedException; use ProgrammatorDev\OpenWeatherMap\Exception\UnexpectedErrorException; try { - $location = $openWeatherMap->geocoding()->getByZipCode('1000-001', 'pt'); + $location = $api->geocoding()->getByZipCode('1000-001', 'pt'); + $coordinate = $location->getCoordinate(); - $weather = $openWeatherMap->oneCall()->getWeather( - $location->getCoordinate()->getLatitude(), - $location->getCoordinate()->getLongitude() + $weather = $api->oneCall()->getWeather( + $coordinate->getLatitude(), + $coordinate->getLongitude() ); } -// Bad requests to the API -// If this library is making a good job validating input data, this should not happen +// bad request to the api catch (BadRequestException $exception) { echo $exception->getCode(); // 400 echo $exception->getMessage(); } -// Invalid API key or trying to request an endpoint with no granted access +// invalid API key or trying to request an endpoint with no granted access catch (UnauthorizedException $exception) { echo $exception->getCode(); // 401 echo $exception->getMessage(); } -// Resource not found -// For example, when trying to get a location with a zip/post code that does not exist +// resource not found +// for example, when trying to get a location with a zip code that does not exist catch (NotFoundException $exception) { echo $exception->getCode(); // 404 echo $exception->getMessage(); } -// API key requests quota exceeded +// api key requests quota exceeded catch (TooManyRequestsException $exception) { echo $exception->getCode(); // 429 echo $exception->getMessage(); } -// Any other error, probably an internal error +// any other error, probably an internal error catch (UnexpectedErrorException $exception) { echo $exception->getCode(); // 5xx echo $exception->getMessage(); @@ -57,14 +57,15 @@ To catch all API errors with a single exception, `ApiErrorException` is availabl use ProgrammatorDev\OpenWeatherMap\Exception\ApiErrorException; try { - $location = $openWeatherMap->geocoding()->getByZipCode('1000-001', 'pt'); + $location = $api->geocoding()->getByZipCode('1000-001', 'pt'); + $coordinate = $location->getCoordinate(); - $weather = $openWeatherMap->oneCall()->getWeather( - $location->getCoordinate()->getLatitude(), - $location->getCoordinate()->getLongitude() + $weather = $api->oneCall()->getWeather( + $coordinate->getLatitude(), + $coordinate->getLongitude() ); } -// Catches all API response errors +// catches all api response errors catch (ApiErrorException $exception) { echo $exception->getCode(); echo $exception->getMessage(); @@ -76,14 +77,14 @@ catch (ApiErrorException $exception) { To catch invalid input data (like an out of range coordinate, blank location name, etc.), the `ValidationException` is available: ```php -use ProgrammatorDev\YetAnotherPhpValidator\Exception\ValidationException; +use ProgrammatorDev\Validator\Exception\ValidationException; try { - // An invalid latitude value is given - $weather = $openWeatherMap->weather()->getCurrent(999, 50); + // an invalid latitude value is given + $weather = $api->weather()->getCurrent(999, 50); } catch (ValidationException $exception) { - // Should print: + // should print: // The latitude value should be between -90 and 90, 999 given. echo $exception->getMessage(); } diff --git a/docs/05-entities.md b/docs/05-entities.md index 79e9487..739e8ab 100644 --- a/docs/05-entities.md +++ b/docs/05-entities.md @@ -217,12 +217,12 @@ ### Location -- `getId()`: `?int` - `getName()`: `?string` - `getState()`: `?string` - `getCountryCode()`: `?string` - `getLocalNames()`: `?array` - `getLocalName(string $countryCode)`: `?string` +- `getZipCode()`: `?string` - `getCoordinate()`: [`Coordinate`](#coordinate) ### MoonPhase