diff --git a/CHANGELOG.md b/CHANGELOG.md index a6de5dc3..8eb52de6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased](https://github.com/kbsali/php-redmine-api/compare/v2.7.0...v2.x) +### Added + +- New class `Redmine\Http\HttpFactory` to create `Redmine\Http\Request` and `Redmine\Http\Response` instances. + ## [v2.7.0](https://github.com/kbsali/php-redmine-api/compare/v2.6.0...v2.7.0) - 2024-07-10 ### Added diff --git a/README.md b/README.md index ac6023c0..7d2b805b 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,13 @@ like [Guzzle](https://github.com/guzzle/guzzle) for handling http connections ``` * [low-level API](docs/usage.md#low-level-api) e.g. ```php - $client->requestPost('/issues.json', '{"issue":{"project_id":1,"subject":"issue title"}}'); + $response = $client->request( + HttpFactory::makeJsonRequest( + 'POST', + '/issues.json', + '{"issue":{"project_id":1,"subject":"issue title"}}', + ), + ); ``` ## Supported Redmine versions diff --git a/docs/usage.md b/docs/usage.md index a2c3b6c7..ec157164 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -219,9 +219,15 @@ try { ### Mid-level API -You can now use the `getApi()` method to create and get a specific Redmine API. This simplifies common use-cases and gives you some features like caching and assigning a user to an issue by username instead of the user ID. +You can now use the `getApi()` method to create and get a specific Redmine API. -To check for failed requests you can afterwards check the status code via `$client->getLastResponseStatusCode()`. +```php +$api = $client->getApi('issue'); +``` + +This simplifies common use-cases and gives you some features like caching and assigning a user to an issue by username instead of the user ID. + +To check for failed requests you can afterwards check the status code via `$api->getLastResponse()->getStatusCode()`. #### Tracker API @@ -646,68 +652,76 @@ The low-level API allows you to send highly customized requests to the Redmine s > :bulb: See the [Redmine REST-API docs](https://www.redmine.org/projects/redmine/wiki/Rest_api) for available endpoints and required parameters. -The client has 4 methods for requests: +The client has a method for requests: -- `requestGet()` -- `requestPost()` -- `requestPut()` -- `requestDelete()` +- `request(\Redmine\Http\Request $request): \Redmine\Http\Response` -Using this methods you can use every Redmine API endpoint. The following example shows you how to rename a project and add a custom field. To build the XML body you can use the `XmlSerializer`. +There is also a `HttpFactory` to create `Request` objects: + +- `\Redmine\Http\HttpFactory::makeJsonRequest()` creates a `\Redmine\Http\Request` instance for JSON requests +- `\Redmine\Http\HttpFactory::makeXmlRequest()` creates a `\Redmine\Http\Request` instance for XML requests + +Using this method and the `HttpFactory` you can use every Redmine API endpoint. The following example shows you how to rename a project and add a custom field. To build the XML body you can use the `XmlSerializer`. ```php -$client->requestPut( - '/projects/1.xml', - (string) \Redmine\Serializer\XmlSerializer::createFromArray([ - 'project' => [ - 'name' => 'renamed project', - 'custom_fields' => [ - [ - 'id' => 123, - 'name' => 'cf_name', - 'field_format' => 'string', - 'value' => [1, 2, 3], +$response = $client->request( + \Redmine\Http\HttpFactory::makeXmlRequest( + 'PUT', + '/projects/1.xml', + (string) \Redmine\Serializer\XmlSerializer::createFromArray([ + 'project' => [ + 'name' => 'renamed project', + 'custom_fields' => [ + [ + 'id' => 123, + 'name' => 'cf_name', + 'field_format' => 'string', + 'value' => [1, 2, 3], + ], ], ], - ] - ]) + ]), + ), ); ``` -> :bulb: Use `\Redmine\Serializer\JsonSerializer` if you want to use the JSON endpoint. +> :bulb: Use `\Redmine\Serializer\JsonSerializer` and `HttpFactory::makeJsonRequest()` if you want to use the JSON endpoint. -Or to fetch data with complex query parameters you can use `requestGet()` with the `PathSerializer`: +Or to fetch data with complex query parameters you can use the `PathSerializer`: ```php -$client->requestGet( - (string) \Redmine\Serializer\PathSerializer::create( - '/time_entries.json', - [ - 'f' => ['spent_on'], - 'op' => ['spent_on' => '><'], - 'v' => [ - 'spent_on' => [ - '2016-01-18', - '2016-01-22', +$response = $client->request( + \Redmine\Http\HttpFactory::makeJsonRequest( + 'GET', + (string) \Redmine\Serializer\PathSerializer::create( + '/time_entries.json', + [ + 'f' => ['spent_on'], + 'op' => ['spent_on' => '><'], + 'v' => [ + 'spent_on' => [ + '2016-01-18', + '2016-01-22', + ], ], ], - ], - ) + ), + ), ); ``` -After the request you can use these 3 methods to work with the response: +After the request you can use these 3 methods to work with the `\Redmine\Http\Response` instance: -- `getLastResponseStatusCode()` -- `getLastResponseContentType()` -- `getLastResponseBody()` +- `getStatusCode()` +- `getContentType()` +- `getContent()` -To parse the response body from the last example to an array you can use `XmlSerializer`: +To parse the response body to an array you can use `XmlSerializer`: ```php -if ($client->getLastResponseStatusCode() === 200) { +if ($response->getStatusCode() === 200) { $responseAsArray = \Redmine\Serializer\XmlSerializer::createFromString( - $client->getLastResponseBody() + $response->getContent(), )->getNormalized(); } ``` diff --git a/src/Redmine/Http/HttpFactory.php b/src/Redmine/Http/HttpFactory.php index 039ca39a..b7cc4478 100644 --- a/src/Redmine/Http/HttpFactory.php +++ b/src/Redmine/Http/HttpFactory.php @@ -6,8 +6,6 @@ /** * Factory for HTTP objects. - * - * @internal */ final class HttpFactory {