From 696e0cb2354f07fff2aa5b3104bffb05f52a3dc8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andre=CC=81=20Pimpa=CC=83o?= Date: Mon, 13 May 2024 16:44:20 +0100 Subject: [PATCH] docs: added library methods documentation --- docs/02-configuration.md | 180 +++++++++++++++----------------------- docs/03-supported-apis.md | 5 +- 2 files changed, 72 insertions(+), 113 deletions(-) diff --git a/docs/02-configuration.md b/docs/02-configuration.md index 42ef512..bcee3ed 100644 --- a/docs/02-configuration.md +++ b/docs/02-configuration.md @@ -4,9 +4,17 @@ - [Options](#options) - [unitSystem](#unitsystem) - [language](#language) +- [Methods](#methods) + - [setClientBuilder](#setclientbuilder) + - [setCacheBuilder](#setcachebuilder) + - [setLoggerBuilder](#setloggerbuilder) ## Default Configuration +```php +OpenWeatherMap(string $apiKey, array $options => []); +``` + ```php use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap; @@ -23,7 +31,10 @@ $api = new OpenWeatherMap('yourapikey', [ Unit system used when retrieving data. Affects temperature and speed values. -Available options are `metric`, `imperial` and `standard`. +Available options: +- `metric` +- `imperial` +- `standard` Example: @@ -54,147 +65,96 @@ $api = new OpenWeatherMap('yourapikey', [ ]); ``` -### `httpClientBuilder` - -Configure a PSR-18 HTTP client and PSR-17 HTTP factory adapters. +## Methods -By default, and for convenience, this library makes use of the [HTTPlug's Discovery](https://github.com/php-http/discovery) library. -This means that it will automatically find and install a well-known PSR-18 and PSR-17 implementation for you (if one was not found on your project): -- [List of PSR-18 compatible implementations](https://packagist.org/providers/psr/http-client-implementation) -- [List of PSR-17 compatible implementations](https://packagist.org/providers/psr/http-factory-implementation) +> [!IMPORTANT] +> The [PHP API SDK](https://github.com/programmatordev/php-api-sdk) library was used to create the OpenWeatherMap PHP API. +> To get to know about all available methods, make sure to check the documentation [here](https://github.com/programmatordev/php-api-sdk?tab=readme-ov-file#php-api-sdk). -If you want to manually provide one, it should look like this: +The following sections have examples of some of the most important methods, +particularly related with the configuration of the client, cache and logger. -```php -use ProgrammatorDev\OpenWeatherMap\Config; -use ProgrammatorDev\OpenWeatherMap\HttpClient\HttpClientBuilder; -use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap; +### `setClientBuilder` -$httpClient = new Symfony\Component\HttpClient\Psr18Client(); -$httpFactory = new Nyholm\Psr7\Factory\Psr17Factory(); - -// HttpClientBuilder( -// ?ClientInterface $client = null, -// ?RequestFactoryInterface $requestFactory = null, -// ?StreamFactoryInterface $streamFactory = null -// ); -$httpClientBuilder = new HttpClientBuilder($httpClient, $httpFactory, $httpFactory); - -$openWeatherMap = new OpenWeatherMap( - new Config([ - 'applicationKey' => 'yourappkey', - 'httpClientBuilder' => $httpClientBuilder - ]) -); -``` +By default, this library makes use of the [HTTPlug's Discovery](https://github.com/php-http/discovery) library. +This means that it will automatically find and install a well-known PSR-18 client and PSR-17 factory implementation for you +(if they were not found on your project): +- [PSR-18 compatible implementations](https://packagist.org/providers/psr/http-client-implementation) +- [PSR-17 compatible implementations](https://packagist.org/providers/psr/http-factory-implementation) -> **Note** -> All `HttpClientBuilder` parameters are optional. -> If you only pass an HTTP client, an HTTP factory will still be discovered for you. - -#### Plugin System - -[HTTPlug's plugin system](https://docs.php-http.org/en/latest/plugins/index.html) is also implemented to give you full control of what happens during the request/response workflow. - -For example, to attempt to re-send a request in case of failure (service temporarily down because of unreliable connections/servers, etc.), -the [RetryPlugin](https://docs.php-http.org/en/latest/plugins/retry.html) can be added: +If you don't want to rely on the discovery of implementations, you can set the ones you want: ```php -use ProgrammatorDev\OpenWeatherMap\Config; -use ProgrammatorDev\OpenWeatherMap\HttpClient\HttpClientBuilder; +use Nyholm\Psr7\Factory\Psr17Factory; use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap; +use Symfony\Component\HttpClient\Psr18Client; -$httpClientBuilder = new HttpClientBuilder(); -$httpClientBuilder->addPlugin( - new \Http\Client\Common\Plugin\RetryPlugin([ - 'retries' => 3 - ]) -); +$api = new OpenWeatherMap('yourapikey'); -$openWeatherMap = new OpenWeatherMap( - new Config([ - 'applicationKey' => 'yourappkey', - 'httpClientBuilder' => $httpClientBuilder - ]) +$client = new Psr18Client(); +$requestFactory = $streamFactory = new Psr17Factory(); + +$api->setClientBuilder( + new ClientBuilder( + client: $client, + requestFactory: $requestFactory, + streamFactory: $streamFactory + ) ); ``` -You can check their [plugin list](https://docs.php-http.org/en/latest/plugins/index.html) or [create your own](https://docs.php-http.org/en/latest/plugins/build-your-own.html). - -> **Note** -> This library already uses HTTPlug's `CachePlugin` and `LoggerPlugin`. -> Re-adding those may lead to an unexpected behaviour. - -### `cache` +Check the full documentation [here](https://github.com/programmatordev/php-api-sdk?tab=readme-ov-file#http-client-psr-18-and-http-factories-psr-17). -Configure a PSR-6 cache adapter. +### `setCacheBuilder` -By default, no responses are cached. -To enable cache, you must provide a PSR-6 implementation: -- [List of PSR-6 compatible implementations](https://packagist.org/providers/psr/cache-implementation) +This library allows configuring the cache layer of the client for making API requests. +It uses a standard PSR-6 implementation and provides methods to fine-tune how HTTP caching behaves: +- [PSR-6 compatible implementations](https://packagist.org/providers/psr/cache-implementation) -In the example below, a filesystem-based cache is used: +Example: ```php -use ProgrammatorDev\OpenWeatherMap\Config; use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap; +use Symfony\Component\Cache\Adapter\FilesystemAdapter; -$cache = new \Symfony\Component\Cache\Adapter\FilesystemAdapter(); - -$openWeatherMap = new OpenWeatherMap( - new Config([ - 'applicationKey' => 'yourappkey', - 'cache' => $cache - ]) -); -``` - -#### Cache TTL - -By default, all responses are cached for `10 minutes`, with the exception to `Geocoding` requests -where responses are cached for `30 days` (due to the low update frequency, since location data doesn't change that often). +$api = new OpenWeatherMap('yourapikey'); -It is possible to change the cache duration per request: +$pool = new FilesystemAdapter(); -```php -// Response will be cached for 1 hour -$currentWeather = $openWeatherMap->weather() - ->withCacheTtl(3600) - ->getCurrent(50, 50); +// set a file-based cache adapter with a 1-hour default cache lifetime +$api->setCacheBuilder( + new CacheBuilder( + pool: $pool, + ttl: 3600 + ) +); ``` -### `logger` +Check the full documentation [here](https://github.com/programmatordev/php-api-sdk?tab=readme-ov-file#cache-psr-6). -Configure a PSR-3 logger adapter. +### `setLoggerBuilder` -By default, no logs are saved. To enable logs, you must provide a PSR-3 implementation: -- [List of PSR-3 compatible implementations](https://packagist.org/providers/psr/log-implementation) +This library allows configuring a logger to save data for making API requests. +It uses a standard PSR-3 implementation and provides methods to fine-tune how logging behaves: +- [PSR-3 compatible implementations](https://packagist.org/providers/psr/log-implementation) -In the example below, a file-based logger is used... +Example: ```php -use ProgrammatorDev\OpenWeatherMap\Config; +use Monolog\Logger; +use Monolog\Handler\StreamHandler; use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap; -$logger = new \Monolog\Logger('openweathermap'); -$logger->pushHandler( - new \Monolog\Handler\StreamHandler(__DIR__ . '/logs/openweathermap.log') -); +$api = new OpenWeatherMap('yourapikey'); -$openWeatherMap = new OpenWeatherMap( - new Config([ - 'applicationKey' => 'yourappkey', - 'logger' => $logger - ]) -); -``` +$logger = new Logger('openweathermap'); +$logger->pushHandler(new StreamHandler('/logs/api.log')); -...and will provide logs similar to this: - -``` -[2023-07-12T12:25:02.235721+00:00] openweathermap.INFO: Sending request: GET https://api.openweathermap.org/data/3.0/onecall?lat=50&lon=50&units=metric&lang=en&appid=[REDACTED] 1.1 {"request":{},"uid":"64ae9b9e394ff6.24668056"} -[2023-07-12T12:25:02.682278+00:00] openweathermap.INFO: Received response: 200 OK 1.1 {"milliseconds":447,"uid":"64ae9b9e394ff6.24668056"} +$api->setLoggerBuilder( + new LoggerBuilder( + logger: $logger + ) +); ``` -> **Note** -> If a `cache` implementation is configured, cache events will also be logged. \ No newline at end of file +Check the full documentation [here](https://github.com/programmatordev/php-api-sdk?tab=readme-ov-file#logger-psr-3). \ No newline at end of file diff --git a/docs/03-supported-apis.md b/docs/03-supported-apis.md index 21db682..3e124d6 100644 --- a/docs/03-supported-apis.md +++ b/docs/03-supported-apis.md @@ -251,9 +251,8 @@ Semantics of values: > [!NOTE] > Setting cache to `null` or `0` seconds will **not** invalidate any existing cache. -[//]: # (Check the [Cache TTL](02-configuration.md#cache-ttl) section for more information regarding default values.) - -[//]: # (Available for all APIs if `cache` is enabled in the [configuration](02-configuration.md#cache).) +Available for all APIs if a cache adapter is set. +Check the following [documentation](02-configuration.md#cache) for more information. ```php // cache will be saved for 1 hour for this request alone