Skip to content

Commit 696e0cb

Browse files
andrepimpaoandrepimpao
committed
docs: added library methods documentation
1 parent 383cd3c commit 696e0cb

File tree

2 files changed

+72
-113
lines changed

2 files changed

+72
-113
lines changed

‎docs/02-configuration.md

+70-110
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,17 @@
44
- [Options](#options)
55
- [unitSystem](#unitsystem)
66
- [language](#language)
7+
- [Methods](#methods)
8+
- [setClientBuilder](#setclientbuilder)
9+
- [setCacheBuilder](#setcachebuilder)
10+
- [setLoggerBuilder](#setloggerbuilder)
711

812
## Default Configuration
913

14+
```php
15+
OpenWeatherMap(string $apiKey, array $options => []);
16+
```
17+
1018
```php
1119
use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap;
1220

@@ -23,7 +31,10 @@ $api = new OpenWeatherMap('yourapikey', [
2331
Unit system used when retrieving data.
2432
Affects temperature and speed values.
2533

26-
Available options are `metric`, `imperial` and `standard`.
34+
Available options:
35+
- `metric`
36+
- `imperial`
37+
- `standard`
2738

2839
Example:
2940

@@ -54,147 +65,96 @@ $api = new OpenWeatherMap('yourapikey', [
5465
]);
5566
```
5667

57-
### `httpClientBuilder`
58-
59-
Configure a PSR-18 HTTP client and PSR-17 HTTP factory adapters.
68+
## Methods
6069

61-
By default, and for convenience, this library makes use of the [HTTPlug's Discovery](https://github.com/php-http/discovery) library.
62-
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):
63-
- [List of PSR-18 compatible implementations](https://packagist.org/providers/psr/http-client-implementation)
64-
- [List of PSR-17 compatible implementations](https://packagist.org/providers/psr/http-factory-implementation)
70+
> [!IMPORTANT]
71+
> The [PHP API SDK](https://github.com/programmatordev/php-api-sdk) library was used to create the OpenWeatherMap PHP API.
72+
> 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).
6573
66-
If you want to manually provide one, it should look like this:
74+
The following sections have examples of some of the most important methods,
75+
particularly related with the configuration of the client, cache and logger.
6776

68-
```php
69-
use ProgrammatorDev\OpenWeatherMap\Config;
70-
use ProgrammatorDev\OpenWeatherMap\HttpClient\HttpClientBuilder;
71-
use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap;
77+
### `setClientBuilder`
7278

73-
$httpClient = new Symfony\Component\HttpClient\Psr18Client();
74-
$httpFactory = new Nyholm\Psr7\Factory\Psr17Factory();
75-
76-
// HttpClientBuilder(
77-
// ?ClientInterface $client = null,
78-
// ?RequestFactoryInterface $requestFactory = null,
79-
// ?StreamFactoryInterface $streamFactory = null
80-
// );
81-
$httpClientBuilder = new HttpClientBuilder($httpClient, $httpFactory, $httpFactory);
82-
83-
$openWeatherMap = new OpenWeatherMap(
84-
new Config([
85-
'applicationKey' => 'yourappkey',
86-
'httpClientBuilder' => $httpClientBuilder
87-
])
88-
);
89-
```
79+
By default, this library makes use of the [HTTPlug's Discovery](https://github.com/php-http/discovery) library.
80+
This means that it will automatically find and install a well-known PSR-18 client and PSR-17 factory implementation for you
81+
(if they were not found on your project):
82+
- [PSR-18 compatible implementations](https://packagist.org/providers/psr/http-client-implementation)
83+
- [PSR-17 compatible implementations](https://packagist.org/providers/psr/http-factory-implementation)
9084

91-
> **Note**
92-
> All `HttpClientBuilder` parameters are optional.
93-
> If you only pass an HTTP client, an HTTP factory will still be discovered for you.
94-
95-
#### Plugin System
96-
97-
[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.
98-
99-
For example, to attempt to re-send a request in case of failure (service temporarily down because of unreliable connections/servers, etc.),
100-
the [RetryPlugin](https://docs.php-http.org/en/latest/plugins/retry.html) can be added:
85+
If you don't want to rely on the discovery of implementations, you can set the ones you want:
10186

10287
```php
103-
use ProgrammatorDev\OpenWeatherMap\Config;
104-
use ProgrammatorDev\OpenWeatherMap\HttpClient\HttpClientBuilder;
88+
use Nyholm\Psr7\Factory\Psr17Factory;
10589
use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap;
90+
use Symfony\Component\HttpClient\Psr18Client;
10691

107-
$httpClientBuilder = new HttpClientBuilder();
108-
$httpClientBuilder->addPlugin(
109-
new \Http\Client\Common\Plugin\RetryPlugin([
110-
'retries' => 3
111-
])
112-
);
92+
$api = new OpenWeatherMap('yourapikey');
11393

114-
$openWeatherMap = new OpenWeatherMap(
115-
new Config([
116-
'applicationKey' => 'yourappkey',
117-
'httpClientBuilder' => $httpClientBuilder
118-
])
94+
$client = new Psr18Client();
95+
$requestFactory = $streamFactory = new Psr17Factory();
96+
97+
$api->setClientBuilder(
98+
new ClientBuilder(
99+
client: $client,
100+
requestFactory: $requestFactory,
101+
streamFactory: $streamFactory
102+
)
119103
);
120104
```
121105

122-
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).
123-
124-
> **Note**
125-
> This library already uses HTTPlug's `CachePlugin` and `LoggerPlugin`.
126-
> Re-adding those may lead to an unexpected behaviour.
127-
128-
### `cache`
106+
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).
129107

130-
Configure a PSR-6 cache adapter.
108+
### `setCacheBuilder`
131109

132-
By default, no responses are cached.
133-
To enable cache, you must provide a PSR-6 implementation:
134-
- [List of PSR-6 compatible implementations](https://packagist.org/providers/psr/cache-implementation)
110+
This library allows configuring the cache layer of the client for making API requests.
111+
It uses a standard PSR-6 implementation and provides methods to fine-tune how HTTP caching behaves:
112+
- [PSR-6 compatible implementations](https://packagist.org/providers/psr/cache-implementation)
135113

136-
In the example below, a filesystem-based cache is used:
114+
Example:
137115

138116
```php
139-
use ProgrammatorDev\OpenWeatherMap\Config;
140117
use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap;
118+
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
141119

142-
$cache = new \Symfony\Component\Cache\Adapter\FilesystemAdapter();
143-
144-
$openWeatherMap = new OpenWeatherMap(
145-
new Config([
146-
'applicationKey' => 'yourappkey',
147-
'cache' => $cache
148-
])
149-
);
150-
```
151-
152-
#### Cache TTL
153-
154-
By default, all responses are cached for `10 minutes`, with the exception to `Geocoding` requests
155-
where responses are cached for `30 days` (due to the low update frequency, since location data doesn't change that often).
120+
$api = new OpenWeatherMap('yourapikey');
156121

157-
It is possible to change the cache duration per request:
122+
$pool = new FilesystemAdapter();
158123

159-
```php
160-
// Response will be cached for 1 hour
161-
$currentWeather = $openWeatherMap->weather()
162-
->withCacheTtl(3600)
163-
->getCurrent(50, 50);
124+
// set a file-based cache adapter with a 1-hour default cache lifetime
125+
$api->setCacheBuilder(
126+
new CacheBuilder(
127+
pool: $pool,
128+
ttl: 3600
129+
)
130+
);
164131
```
165132

166-
### `logger`
133+
Check the full documentation [here](https://github.com/programmatordev/php-api-sdk?tab=readme-ov-file#cache-psr-6).
167134

168-
Configure a PSR-3 logger adapter.
135+
### `setLoggerBuilder`
169136

170-
By default, no logs are saved. To enable logs, you must provide a PSR-3 implementation:
171-
- [List of PSR-3 compatible implementations](https://packagist.org/providers/psr/log-implementation)
137+
This library allows configuring a logger to save data for making API requests.
138+
It uses a standard PSR-3 implementation and provides methods to fine-tune how logging behaves:
139+
- [PSR-3 compatible implementations](https://packagist.org/providers/psr/log-implementation)
172140

173-
In the example below, a file-based logger is used...
141+
Example:
174142

175143
```php
176-
use ProgrammatorDev\OpenWeatherMap\Config;
144+
use Monolog\Logger;
145+
use Monolog\Handler\StreamHandler;
177146
use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap;
178147

179-
$logger = new \Monolog\Logger('openweathermap');
180-
$logger->pushHandler(
181-
new \Monolog\Handler\StreamHandler(__DIR__ . '/logs/openweathermap.log')
182-
);
148+
$api = new OpenWeatherMap('yourapikey');
183149

184-
$openWeatherMap = new OpenWeatherMap(
185-
new Config([
186-
'applicationKey' => 'yourappkey',
187-
'logger' => $logger
188-
])
189-
);
190-
```
150+
$logger = new Logger('openweathermap');
151+
$logger->pushHandler(new StreamHandler('/logs/api.log'));
191152

192-
...and will provide logs similar to this:
193-
194-
```
195-
[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"}
196-
[2023-07-12T12:25:02.682278+00:00] openweathermap.INFO: Received response: 200 OK 1.1 {"milliseconds":447,"uid":"64ae9b9e394ff6.24668056"}
153+
$api->setLoggerBuilder(
154+
new LoggerBuilder(
155+
logger: $logger
156+
)
157+
);
197158
```
198159

199-
> **Note**
200-
> If a `cache` implementation is configured, cache events will also be logged.
160+
Check the full documentation [here](https://github.com/programmatordev/php-api-sdk?tab=readme-ov-file#logger-psr-3).

‎docs/03-supported-apis.md

+2-3
Original file line numberDiff line numberDiff line change
@@ -251,9 +251,8 @@ Semantics of values:
251251
> [!NOTE]
252252
> Setting cache to `null` or `0` seconds will **not** invalidate any existing cache.
253253
254-
[//]: # (Check the [Cache TTL](02-configuration.md#cache-ttl) section for more information regarding default values.)
255-
256-
[//]: # (Available for all APIs if `cache` is enabled in the [configuration](02-configuration.md#cache).)
254+
Available for all APIs if a cache adapter is set.
255+
Check the following [documentation](02-configuration.md#cache) for more information.
257256

258257
```php
259258
// cache will be saved for 1 hour for this request alone

0 commit comments

Comments
 (0)