Merge pull request #429 from Art4/428-publish-httpfactory

Publish `HttpFactory`

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

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

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();
 }
 ```

src/Redmine/Http/HttpFactory.php

@@ -6,8 +6,6 @@
 
 /**
  * Factory for HTTP objects.
- *
- * @internal
  */
 final class HttpFactory
 {