Skip to content

Commit 59238d1

Browse files
happyDemonhappyDemon
committed
Merge branch 'main' of github.com:happyDemon/saloon-utils
* 'main' of github.com:happyDemon/saloon-utils: docs: sync from gh-pages branch
2 parents 8eab148 + bd979e7 commit 59238d1

File tree

8 files changed

+437
-0
lines changed

8 files changed

+437
-0
lines changed

‎docs/README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Saloon Utils
2+
3+
[![Latest Version on Packagist](https://img.shields.io/packagist/v/happydemon/saloon-utils.svg?style=flat-square)](https://packagist.org/packages/happydemon/saloon-utils) [![Tests Status](https://github.com/happydemon/saloon-utils/actions/workflows/test.yml/badge.svg)](https://github.com/happyDemon/saloon-utils/actions/workflows/test.yml?query=branch%3Amain) ![Tests Coverage](https://raw.githubusercontent.com/happyDemon/saloon-utils/refs/heads/main/badge-coverage.svg)
4+
5+
Batteries for [Saloon](https://docs.saloon.dev/).
6+
7+
## Installation
8+
9+
Via Composer
10+
11+
```bash
12+
composer require happydemon/saloon-utils
13+
php artisan vendor:publish --tag saloon-utils.config
14+
```
15+
16+
## Features
17+
18+
<table data-card-size="large" data-view="cards"><thead><tr><th></th><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Flexible request logging</td><td><a href="request-logging/getting-started.md">getting-started.md</a></td><td><a href="request-logging/getting-started.md">getting-started.md</a></td></tr><tr><td>Connection management</td><td></td><td></td></tr></tbody></table>
19+
20+
## License
21+
22+
MIT

‎docs/SUMMARY.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Table of contents
2+
3+
* [Saloon Utils](README.md)
4+
5+
## Request logging
6+
7+
* [Getting started](request-logging/getting-started.md)
8+
* [Control log creation](request-logging/control-log-creation.md)
9+
* [Loggers](request-logging/loggers.md)
10+
* [PendingRequest configuration](request-logging/pendingrequest-configuration.md)
11+
* [Redacting request data](request-logging/redacting-request-data.md)
12+
13+
## Connection management
14+
15+
* [Environments](connection-management/environments.md)

‎docs/connection-management/environments.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Environments
2+
3+
{% tabs %}
4+
{% tab title="Tab 1" %}
5+
6+
{% endtab %}
7+
8+
{% tab title="Tab 2" %}
9+
10+
{% endtab %}
11+
{% endtabs %}

‎docs/request-logging/control-log-creation.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Control log creation
2+
3+
You have full control over when and how your requests are logged.
4+
5+
{% hint style="danger" %}
6+
Config file values take precedence over every thing.
7+
{% endhint %}
8+
9+
## Configuration
10+
11+
On a global level you are able to either disable logging completely or black list requests & connectors:
12+
13+
{% @github-files/github-code-block url="https://github.com/happyDemon/saloon-utils/blob/main/config/saloon-utils.php" %}
14+
15+
## Requests
16+
17+
Alternatively, you are able to define logging behaviour on requests individually.
18+
19+
#### Log only errors
20+
21+
You can limit logging to only errors by implementing the `OnlyLogErrorRequest` contract.
22+
23+
{% hint style="info" %}
24+
You are able to add `HappyDemon\SaloonUtils\Logger\Contracts\OnlyLogErrorRequest` to both `Request` and `Connector` classes.
25+
{% endhint %}
26+
27+
```php
28+
<?php
29+
30+
use HappyDemon\SaloonUtils\Logger\Contracts\OnlyLogErrorRequest;
31+
use Saloon\Enums\Method;
32+
use Saloon\Http\Request;
33+
34+
class GetServersRequest extends Request implements OnlyLogErrorRequest
35+
{
36+
protected Method $method = Method::GET;
37+
38+
public function resolveEndpoint(): string
39+
{
40+
return '/servers';
41+
}
42+
}
43+
```
44+
45+
#### Disable logging
46+
47+
You can ensure individual requests will never be recorded by implementing the `DoNotLogRequest` contract.
48+
49+
{% hint style="info" %}
50+
You are able to add `HappyDemon\SaloonUtils\Logger\Contracts\DoNotLogRequest` to both `Request` and `Connector` classes.
51+
{% endhint %}
52+
53+
```php
54+
<?php
55+
56+
use HappyDemon\SaloonUtils\Logger\Contracts\DoNotLogRequest;
57+
use Saloon\Enums\Method;
58+
use Saloon\Http\Request;
59+
60+
class GetServersRequest extends Request implements DoNotLogRequest
61+
{
62+
protected Method $method = Method::GET;
63+
64+
public function resolveEndpoint(): string
65+
{
66+
return '/servers';
67+
}
68+
}
69+
```
70+
71+
#### Conditional logging
72+
73+
If you want more fine-grained control over which requests should be logged, you can implement the `ConditionallyIgnoreLogs` contract.
74+
75+
{% hint style="info" %}
76+
You are able to add `HappyDemon\SaloonUtils\Logger\Contracts\ConditionallyIgnoreLogs` to both `Request` and `Connector` classes.
77+
{% endhint %}
78+
79+
This contract allows you to implement any logic to prevent a request from being logged by returning `false`.
80+
81+
```php
82+
<?php
83+
84+
use HappyDemon\SaloonUtils\Logger\Contracts\ConditionallyIgnoreLogs;
85+
use HappyDemon\SaloonUtils\Logger\LoggerPlugin;
86+
use Saloon\Http\Connector;
87+
88+
class ForgeConnector extends Connector implements ConditionallyIgnoreLogs
89+
{
90+
use LoggerPlugin;
91+
92+
public function resolveBaseUrl(): string
93+
{
94+
return 'https://forge.laravel.com/api/v1';
95+
}
96+
97+
public function shouldLogRequest(PendingRequest $pendingRequest): bool
98+
{
99+
return true;
100+
}
101+
}
102+
```
103+

‎docs/request-logging/getting-started.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
icon: circle-wifi
3+
---
4+
5+
# Getting started
6+
7+
Keep track of (all) the requests a connector executes.
8+
9+
Log those requests/responses to your database, keep the logs in-memory or bring your own storage implementation.
10+
11+
## Configuration
12+
13+
<kbd>.env</kbd> configuration:
14+
15+
```
16+
# Should any requests be logged? if not defined, defaults to true
17+
SALOON_REQUEST_LOGS=false
18+
```
19+
20+
21+
22+
```
23+
# If not set, the default database connection will be used
24+
SALOON_REQUEST_DB_CONNECTION=
25+
26+
# If not defined, defaults to 14 (how many days should requests be stored in the db)
27+
SALOON_REQUEST_PRUNE=14
28+
```
29+
30+
31+
32+
In the `saloon-utils.php` config file you can also define which requests or connectors will be ignored. \
33+
\
34+
Any requests or connectors defined under `saloon-utils.logs.ignore` will never be logged, checks defined on the request- or connector-level will be bypassed.
35+
36+
{% @github-files/github-code-block url="https://github.com/happyDemon/saloon-utils/blob/main/config/saloon-utils.php" visible="true" fullWidth="false" %}
37+
38+
## Setup
39+
40+
Ensure your [connector](https://docs.saloon.dev/the-basics/connectors) uses the `LoggerPlugin` trait.
41+
42+
```php
43+
<?php
44+
45+
use HappyDemon\SaloonUtils\Logger\LoggerPlugin;
46+
use Saloon\Http\Connector;
47+
48+
class ForgeConnector extends Connector
49+
{
50+
use LoggerPlugin;
51+
52+
public function resolveBaseUrl(): string
53+
{
54+
return 'https://forge.laravel.com/api/v1';
55+
}
56+
}
57+
```
58+
59+
Without any other configuration all requests this connector executes will be stored with the [database logger](loggers.md#database-logger).
60+
61+
62+
63+
## Pools & concurrency
64+
65+
Our `LoggerPlugin` plugin uses Saloon's middleware to track requests, however, when [pooling requests](https://docs.saloon.dev/digging-deeper/concurrency-and-pools), the response middlewares are not executed.
66+
67+
You can still pool requests with this plugin and have logging applied by creating a logged pool:
68+
69+
```php
70+
<?php
71+
72+
use HappyDemon\SaloonUtils\Logger\LoggerPool;
73+
use Saloon\Http\Pool;
74+
75+
$connector = new ForgeConnector;
76+
77+
/** @var LoggerPool | Pool $pool */
78+
$pool = $connector->loggedPool(
79+
iterable|callable $requests = [],
80+
int|callable $concurrency = 5,
81+
callable|null $responseHandler = null,
82+
callable|null $exceptionHandler = null
83+
)
84+
85+
$promise = $pool->send();
86+
$promise->wait();
87+
```
88+
89+
The `LoggerPool` can be considered identical to Saloon's `Pool` class.

‎docs/request-logging/loggers.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Loggers
2+
3+
## Configuring a logger
4+
5+
### Globally
6+
7+
If you want to replace the default logger you will have to bind an instance in the service container.
8+
9+
```php
10+
<?php
11+
12+
namespace App\Providers;
13+
14+
use Illuminate\Support\ServiceProvider;
15+
use HappyDemon\SaloonUtils\Logger\Contracts\Logger;
16+
use HappyDemon\SaloonUtils\Logger\Stores\DatabaseLogger;
17+
18+
class AppServiceProvider extends ServiceProvider
19+
{
20+
/**
21+
* Register any application services.
22+
*/
23+
public function register(): void
24+
{
25+
$this->app->bind(
26+
Logger::class,
27+
fn (Application $application) => new DatabaseLogger
28+
);
29+
}
30+
}
31+
32+
```
33+
34+
### Locally
35+
36+
If you have a special case for a specific connector, you could define which logger to use on the connector itself:
37+
38+
```php
39+
<?php
40+
41+
use HappyDemon\SaloonUtils\Logger\Contracts\Logger;
42+
use HappyDemon\SaloonUtils\Logger\Contracts\ProvidesLogger;
43+
use HappyDemon\SaloonUtils\Logger\LoggerPlugin;
44+
use HappyDemon\SaloonUtils\Logger\Stores\MemoryLogger;
45+
use Saloon\Http\Connector;
46+
47+
class ForgeConnector extends Connector implements ProvidesLogger
48+
{
49+
use LoggerPlugin;
50+
51+
public function resolveBaseUrl(): string
52+
{
53+
return 'https://forge.laravel.com/api/v1';
54+
}
55+
56+
public static function setUpRequestLogger(): Logger
57+
{
58+
return new MemoryLogger
59+
}
60+
}
61+
```
62+
63+
## Built in loggers
64+
65+
### Database logger
66+
67+
```
68+
HappyDemon\SaloonUtils\Logger\Stores\DatabaseLogger
69+
```
70+
71+
When using the **default** built-in database logger, you'll have to publish & run migrations;
72+
73+
```bash
74+
php artisan vendor:publish --tag saloon-utils.migrations
75+
php artisan migrate
76+
```
77+
78+
This logger will store each request in the `saloon_requests` table.
79+
80+
{% hint style="info" %}
81+
Be sure to schedule model pruning daily with a cronjob
82+
{% endhint %}
83+
84+
```php
85+
use HappyDemon\SaloonUtils\Logger\SaloonRequest;
86+
Schedule::command('model:prune', ['--model' => config('saloon-utils.logs.database_model')])->daily();
87+
```
88+
89+
You are able to overwrite the model class altogether by defining your own model in the `saloon-utils.logs.database_model` config.
90+
91+
92+
93+
This is the default-bundled model:
94+
95+
{% @github-files/github-code-block url="https://github.com/happyDemon/saloon-utils/blob/main/src/Logger/SaloonRequest.php" %}
96+
97+
### Memory logger
98+
99+
```
100+
HappyDemon\SaloonUtils\Logger\Stores\MemoryLogger
101+
```
102+
103+
This logger can be helpful when debugging or running tests.\
104+
It will setup a cache store under `saloon-utils` with the array driver.
105+
106+
You can retrieve the requests that were sent on the logger itself:
107+
108+
```php
109+
app(MemoryLogger::class)->logs();
110+
(new MemoryLogger)->logs();
111+
```
112+
113+
### Build your own
114+
115+
You can easily build your own logger and set it as the default.
116+
117+
Ensure your custom logger implements the `Logger` interface.
118+
119+
{% hint style="info" %}
120+
Be sure to make use of the `HappyDemon\SaloonUtils\Logger\Stores\ParsesRequestData` trait when implementing your own logger. It provides helper methods for data conversion and redaction.
121+
{% endhint %}
122+
123+
{% @github-files/github-code-block url="https://github.com/happyDemon/saloon-utils/blob/main/src/Logger/Contracts/Logger.php" visible="true" %}

0 commit comments

Comments
 (0)