docs: added library methods documentation

programmatordev · May 13, 2024 · 696e0cb · 696e0cb
1 parent 383cd3c
commit 696e0cb
Show file tree

Hide file tree

Showing 2 changed files with 72 additions and 113 deletions.
diff --git 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.
+Check the full documentation [here](https://github.com/programmatordev/php-api-sdk?tab=readme-ov-file#logger-psr-3).
diff --git 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]&#40;02-configuration.md#cache-ttl&#41; section for more information regarding default values.)
-
-[//]: # (Available for all APIs if `cache` is enabled in the [configuration]&#40;02-configuration.md#cache&#41;.)
+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