Merge pull request #262 from Art4/add-nativecurlclient

Add new NativeCurlClient

Author: Art4

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- New native cURL client `Redmine\Client\NativeCurlClient` as a replacement for  `Redmine\Client`
 - This `CHANGELOG.md` file
 
 ### Changed

README.md

@@ -7,53 +7,59 @@ Uses [Redmine API](http://www.redmine.org/projects/redmine/wiki/Rest_api/).
 ## Features
 
 * Follows PSR-4 conventions and coding standard: autoload friendly
-* API entry points implementation state :
-* OK Attachments
-* OK Groups
-* OK Custom Fields
-* OK Issues
-* OK Issue Categories
-* OK Issue Priorities
-* *NOK Issue Relations - only partially implemented*
-* OK Issue Statuses
-* OK News
-* OK Projects
-* OK Project Memberships
-* OK Queries
-* OK Roles
-* OK Time Entries
-* OK Time Entry Activities
-* OK Trackers
-* OK Users
-* OK Versions
-* OK Wiki
+* Choose between using native `cURL` function or any
+[PSR-18](https://www.php-fig.org/psr/psr-18/) http client like
+[Guzzle](https://github.com/guzzle/guzzle) for handling http connections
+* API entry points implementation state:
+  * OK Attachments
+  * OK Groups
+  * OK Custom Fields
+  * OK Issues
+  * OK Issue Categories
+  * OK Issue Priorities
+  * *NOK Issue Relations - only partially implemented*
+  * OK Issue Statuses
+  * OK News
+  * OK Projects
+  * OK Project Memberships
+  * OK Queries
+  * OK Roles
+  * OK Time Entries
+  * OK Time Entry Activities
+  * OK Trackers
+  * OK Users
+  * OK Versions
+  * OK Wiki
 
 ## Todo
 
 * Check header's response code (especially for POST/PUT/DELETE requests)
 * See http://stackoverflow.com/questions/9183178/php-curl-retrieving-response-headers-and-body-in-a-single-request/9183272#9183272
-* Maybe Guzzle for handling http connections
-* https://github.com/guzzle/guzzle
 
-## Limitations
+## Limitations / Missing Redmine-API
 
-Redmine is missing some APIs for a full remote management of the data :
-* List of activities & roles : http://www.redmine.org/issues/11464
-* ...
+Redmine is missing some APIs for a full remote management of the data:
+* List of activities & roles: http://www.redmine.org/issues/11464
+* Closing a project: https://www.redmine.org/issues/13725
 
-A possible solution to this would be to create an extra APIs implementing the missing entry points. See existing effort in doing so : https://github.com/rschobbert/redmine-miss-api
+A possible solution to this would be to create an extra APIs implementing the
+missing entry points. See existing effort in doing so:
+https://github.com/rschobbert/redmine-miss-api
 
 ## Requirements
 
 * PHP ^7.4 || ^8.0
-* The PHP [cURL](http://php.net/manual/en/book.curl.php) extension
 * The PHP [SimpleXML](http://php.net/manual/en/book.simplexml.php) extension
 * The PHP [JSON](http://php.net/manual/en/book.json.php) extension
-* [PHPUnit](https://phpunit.de/) >= 9.0 (optional) to run the test suite
 * "Enable REST web service" for your Redmine project (/settings/edit?tab=authentication)
 * then obtain your *API access key* in your profile page : /my/account
 * or use your *username & password* (not recommended)
 
+### Optional
+
+* The PHP [cURL](http://php.net/manual/en/book.curl.php) extension if you want to use the native `cURL` functions.
+* [PHPUnit](https://phpunit.de/) >= 9.0 (optional) to run the test suite
+
 ## Install
 
 ### Composer
@@ -75,7 +81,7 @@ For example,
 // This file is generated by Composer
 require_once 'vendor/autoload.php';
 
-$client = new Redmine\Client('http://redmine.example.com', 'username', 'password');
+$client = new \Redmine\Client\NativeCurlClient('http://redmine.example.com', 'username', 'password');
 ```
 
 ### Manual
@@ -100,7 +106,7 @@ example,
 // This file ships with php-redmine-api
 require 'vendor/php-redmine-api-1.6.0/vendor/autoload.php';
 
-$client = new Redmine\Client('http://redmine.example.com', 'username', 'password');
+$client = new \Redmine\Client\NativeCurlClient('http://redmine.example.com', 'username', 'password');
 ```
 
 ### Running the test suite
@@ -141,21 +147,26 @@ Create your project e.g. in the `index.php` by require the `vendor/autoload.php`
 
 ### Instantiate a Redmine Client
 
-You can choose between the navite curl client or the PSR-18 compatible client.
+You can choose between:
+
+1. a native curl client or
+2. the PSR-18 compatible client.
 
-> :bulb: Since `php-redmine-api` v1.7.0 there is a new PSR-18 based client `Redmine\Client\Psr18Client`. [See this guide if you want to switch to this client.](docs/migrate-to-psr18client.md).
+#### 1. Native curl Client `Redmine\Client\NativeCurlClient`
 
-#### Native curl Client `Redmine\Client`
+> :bulb: This client was introduced in `php-redmine-api` v1.8.0. If you are
+> using the old `Redmine\Client` please [see this migration guide for help to
+> upgrade your code](docs/migrate-to-nativecurlclient.md).
 
-Every Client requires a URL to your Redmine instance and either a valid Apikey...
+You will need a URL to your Redmine instance and either a valid Apikey...
 
 ```diff
 <?php
 
 require_once 'vendor/autoload.php';
 +
 +// Instantiate with ApiKey
-+$client = new Redmine\Client('http://localhost', '1234567890abcdfgh');
++$client = new \Redmine\Client\NativeCurlClient('http://localhost', '1234567890abcdfgh');
 ```
 
 ... or valid username/password.
@@ -167,7 +178,7 @@ require_once 'vendor/autoload.php';
 require_once 'vendor/autoload.php';
 +
 +// Instantiate with Username/Password (not recommended)
-+$client = new Redmine\Client('http://redmine.example.com', 'username', 'password');
++$client = new \Redmine\Client\NativeCurlClient('http://redmine.example.com', 'username', 'password');
 ```
 
 > :bulb: For security reason it is recommended that you use an ApiKey rather than your username/password.
@@ -192,7 +203,9 @@ $client = new Redmine\Client('https://redmine.example.com', '1234567890abcdfgh')
 +$client->setCustomHost('https://localhost:8080');
 
 ```
-#### Psr-18 compatible Client `Redmine\Client\Psr18Client`
+#### 2. Psr-18 compatible Client `Redmine\Client\Psr18Client`
+
+> :bulb: This client was introduced in `v1.7.0` of this library. If you are using the old `Redmine\Client` please [follow this migration guide](docs/migrate-to-psr18client.md). 
 
 The `Psr18Client` requires
 
@@ -214,9 +227,9 @@ require_once 'vendor/autoload.php';
 +$psr17Factory = new \Nyholm\Psr7\Factory\Psr17Factory();
 +
 +// Instantiate with ApiKey
-+$client = new Redmine\Client\Prs18Client($guzzle, $psr17Factory, $psr17Factory, 'https://redmine.example.com', '1234567890abcdfgh');
++$client = new \Redmine\Client\Prs18Client($guzzle, $psr17Factory, $psr17Factory, 'https://redmine.example.com', '1234567890abcdfgh');
 +// ...or Instantiate with Username/Password (not recommended)
-+$client = new Redmine\Client\Prs18Client($guzzle, $psr17Factory, $psr17Factory, 'https://redmine.example.com', 'username', 'password');
++$client = new \Redmine\Client\Prs18Client($guzzle, $psr17Factory, $psr17Factory, 'https://redmine.example.com', 'username', 'password');
 ```
 
 ##### Guzzle configuration
@@ -267,8 +280,8 @@ $psr17Factory = new \Nyholm\Psr7\Factory\Psr17Factory();
 +};
 +
 // Instantiate with ApiKey
--$client = new Redmine\Client\Prs18Client($guzzle, $psr17Factory, $psr17Factory, 'https://redmine.example.com', '1234567890abcdfgh');
-+$client = new Redmine\Client\Prs18Client($guzzleWrapper, $psr17Factory, $psr17Factory, 'https://redmine.example.com', '1234567890abcdfgh');
+-$client = new \Redmine\Client\Prs18Client($guzzle, $psr17Factory, $psr17Factory, 'https://redmine.example.com', '1234567890abcdfgh');
++$client = new \Redmine\Client\Prs18Client($guzzleWrapper, $psr17Factory, $psr17Factory, 'https://redmine.example.com', '1234567890abcdfgh');
 
 ```
 

composer.json

@@ -26,7 +26,8 @@
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^2.0",
         "phpunit/phpunit": "^9.5",
-        "guzzlehttp/psr7": "^1.7"
+        "guzzlehttp/psr7": "^1.7",
+        "php-mock/php-mock-phpunit": "^2.6"
     },
     "autoload": {
         "psr-4": {