From 7d50e758ae08b220259715a20643c416e6c7116f Mon Sep 17 00:00:00 2001 From: Nicolas Joubert Date: Thu, 22 Oct 2026 18:50:04 +0200 Subject: [PATCH] #84 - Documentation: working `#[AsRestClient]` example, exceptions of the bundle in the reference pages Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 3 +++ docs/index.md | 10 ++++++++++ docs/reference/client.md | 9 ++++++++- docs/reference/tasks/request_task.md | 2 +- 4 files changed, 22 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fb6848b..45fac8a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,9 @@ Latest ------ +### Changes +* [#84](https://github.com/cleverage/rest-process-bundle/issues/84) Documentation: working `#[AsRestClient]` example, exceptions of the bundle in the reference pages. + v3.3.1 ------ diff --git a/docs/index.md b/docs/index.md index d54bd9a..ded81af 100644 --- a/docs/index.md +++ b/docs/index.md @@ -47,6 +47,9 @@ services: - { name: cleverage.rest.client, code: apicarto_ign } ``` +With autoconfiguration, the `#[AsRestClient(code: 'apicarto_ign')]` attribute on a class extending `Client` adds the +same tag (see [REST client](reference/client.md)). + The [RequestTask](reference/tasks/request_task.md) then references this client by its code: ```yaml @@ -72,3 +75,10 @@ No option can be configured under `cleverage_rest_process`: a key there is ignor - Tasks - [RequestTask](reference/tasks/request_task.md) - [CleverAge/ProcessBundle documentation](https://github.com/cleverage/process-bundle/blob/main/docs/index.md) + +## Exceptions + +The exceptions named without namespace in the reference pages (e.g. `UnexpectedValueException`) are the ones of the +bundle, `CleverAge\RestProcessBundle\Exception\*`: they extend the SPL exceptions of the same name and implement +`CleverAge\ProcessBundle\Exception\ProcessExceptionInterface`, so that all the errors of the process bundles can be +caught at once. diff --git a/docs/reference/client.md b/docs/reference/client.md index a4b63b6..6620b0f 100644 --- a/docs/reference/client.md +++ b/docs/reference/client.md @@ -51,7 +51,7 @@ The request is then built this way: - **URL**: `/`, the leading `/` of `url` being removed. Then each `{key}` of `url_parameters` is replaced by its value, converted to a string and encoded with [`rawurlencode()`](https://www.php.net/manual/en/function.rawurlencode.php) (a non-scalar value throws an - `\UnexpectedValueException`). + `UnexpectedValueException`). - **Method**: must be one of `HEAD`, `GET`, `POST`, `PUT`, `DELETE`, `OPTIONS`, `TRACE`, `PATCH` (case-sensitive), otherwise a `CleverAge\RestProcessBundle\Exception\RestRequestException` (` is not an HTTP method`) is thrown. - **Headers**: `headers`, plus `Content-Type: ` and `Accept: ` when these options are not empty @@ -84,10 +84,17 @@ The `#[AsRestClient]` attribute adds the same tag to an autoconfigured service: ```php use CleverAge\RestProcessBundle\Attribute\AsRestClient; use CleverAge\RestProcessBundle\Client\Client; +use Psr\Log\LoggerInterface; +use Symfony\Contracts\HttpClient\HttpClientInterface; #[AsRestClient(code: 'my_api')] class MyApiClient extends Client { + public function __construct(HttpClientInterface $httpClient, LoggerInterface $logger) + { + // The code must be the one of the attribute + parent::__construct($httpClient, $logger, 'my_api', 'https://api.example.com'); + } } ``` diff --git a/docs/reference/tasks/request_task.md b/docs/reference/tasks/request_task.md index 95b3a43..b46b623 100644 --- a/docs/reference/tasks/request_task.md +++ b/docs/reference/tasks/request_task.md @@ -18,7 +18,7 @@ Accepted inputs `array` or empty value (`null`, `[]`...): request options overriding the task options (shallow merge, the input wins). Allowed keys are `url`, `method`, `headers`, `url_parameters`, `sends`, `expects` and `data`: any other key is passed to the client, which rejects it (the default client throws an `UndefinedOptionsException`). Any other non-empty input -(e.g. a `string`) throws an `\UnexpectedValueException`. +(e.g. a `string`) throws an `UnexpectedValueException`. Possible outputs ----------------