Improve exceptions (#300)

Co-authored-by: Kevin Saliou <[email protected]>

Author: Art4

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased](https://github.com/kbsali/php-redmine-api/compare/v2.0.1...v2.x)
 
+### Added
+
+- New interface `Redmine\Exception` that is implemented by every library-related exception
+- New exception `Redmine\Exception\ClientException` for client related exceptions
+- New exception `Redmine\Exception\InvalidApiNameException` if an invalid API instance is requested
+- New exception `Redmine\Exception\InvalidParameterException` for invalid parameter provided to an API instance
+- New exception `Redmine\Exception\MissingParameterException` for missing parameter while using an API instance
+
 ### Changed
 
 - Switched from Travis-CI to Github Actions

docs/migrate-to-psr18client.md

@@ -1,6 +1,6 @@
 # Migrate from `Redmine\Client` to `Redmine\Client\Psr18Client`
 
-Since `php-redmine-api` v1.7.0 there is a new PSR-18 based client `Redmine\Client\Psr18Client`. This guide will help you to migrate your code if you want to use an app-wide PSR-18 HTTP client.
+Since `v1.7.0` there is a new PSR-18 based client `Redmine\Client\Psr18Client`. This guide will help you to migrate your code if you want to use an app-wide PSR-18 HTTP client.
 
 ## 1. Use new client methods
 

docs/usage.md

@@ -51,6 +51,8 @@ client.
 
 #### Native cURL Client `Redmine\Client\NativeCurlClient`
 
+> :bulb: The `Redmine\Client\NativeCurlClient` class was introduced in `v1.8.0`.
+
 Every client requires a URL to your Redmine instance and either a valid
 Apikey...
 
@@ -100,6 +102,8 @@ $client = new \Redmine\Client('https://redmine.example.com', '1234567890abcdfgh'
 
 #### Psr-18 compatible Client `Redmine\Client\Psr18Client`
 
+> :bulb: The `Redmine\Client\Psr18Client` class was introduced in `v1.7.0`.
+
 The `Psr18Client` requires
 
 - a `Psr\Http\Client\ClientInterface` implementation (like guzzlehttp/guzzle) ([possible implementations](https://packagist.org/providers/psr/http-client-implementation))
@@ -117,7 +121,7 @@ The `Psr18Client` requires
 require_once 'vendor/autoload.php';
 +
 +$guzzle = \GuzzleHttp\Client();
-+$psr17Factory = new \Nyholm\Psr7\Factory\Psr17Factory();
++$psr17Factory = new \GuzzleHttp\Psr7\HttpFactory();
 +
 +// Instantiate with ApiKey
 +$client = new Redmine\Client\Prs18Client($guzzle, $psr17Factory, $psr17Factory, 'https://redmine.example.com', '1234567890abcdfgh');
@@ -147,7 +151,7 @@ require_once 'vendor/autoload.php';
 +use Psr\Http\Message\ResponseInterface;
 +
 $guzzle = \GuzzleHttp\Client();
-$psr17Factory = new \Nyholm\Psr7\Factory\Psr17Factory();
+$psr17Factory = new \GuzzleHttp\Psr7\HttpFactory();
 
 +$guzzleWrapper = new class(\GuzzleHttp\Client $guzzle) implements ClientInterface
 +{
@@ -195,6 +199,22 @@ $client->startImpersonateUser('kim');
 $client->stopImpersonateUser();
 ```
 
+## Error handling
+
+Every exception implement the interface `Redmine\Exception` making it easy to catch Redmine specific issues.
+
+> :bulb: The `Redmine\Exception` interface was introduced in `v2.1.0`.
+
+```php
+try {
+    $client->getApi('issue')->create($data);
+} catch (\Redmine\Exception $e) {
+    // exceptions from kbsali/redmine-api
+} catch (\Throwable $e) {
+    // other errors
+}
+```
+
 ## API
 
 You can now use the `getApi()` method to create and get a specific Redmine API.

src/Redmine/Api/Group.php

@@ -2,6 +2,9 @@
 
 namespace Redmine\Api;
 
+use Exception;
+use Redmine\Exception\MissingParameterException;
+
 /**
  * Handling of groups.
  *
@@ -56,7 +59,7 @@ public function listing($forceUpdate = false)
      *
      * @param array $params the new group data
      *
-     * @throws \Exception Missing mandatory parameters
+     * @throws MissingParameterException Missing mandatory parameters
      *
      * @return \SimpleXMLElement
      */
@@ -71,7 +74,7 @@ public function create(array $params = [])
         if (
             !isset($params['name'])
         ) {
-            throw new \Exception('Missing mandatory parameters');
+            throw new MissingParameterException('Theses parameters are mandatory: `name`');
         }
 
         $xml = $this->buildXML($params);
@@ -86,11 +89,11 @@ public function create(array $params = [])
      *
      * @param int $id
      *
-     * @throws \Exception Not implemented
+     * @throws Exception Not implemented
      */
     public function update($id, array $params = [])
     {
-        throw new \Exception('Not implemented');
+        throw new Exception('Not implemented');
     }
 
     /**

src/Redmine/Api/IssueCategory.php

@@ -2,6 +2,8 @@
 
 namespace Redmine\Api;
 
+use Redmine\Exception\MissingParameterException;
+
 /**
  * Listing issue categories, creating, editing.
  *
@@ -91,7 +93,7 @@ public function show($id)
      * @param string|int $project project id or literal identifier
      * @param array      $params  the new issue category data
      *
-     * @throws \Exception Missing mandatory parameters
+     * @throws MissingParameterException Missing mandatory parameters
      *
      * @return string|false
      */
@@ -106,7 +108,7 @@ public function create($project, array $params = [])
         if (
             !isset($params['name'])
         ) {
-            throw new \Exception('Missing mandatory parameters');
+            throw new MissingParameterException('Theses parameters are mandatory: `name`');
         }
 
         $xml = new \SimpleXMLElement('<?xml version="1.0"?><issue_category></issue_category>');

src/Redmine/Api/Membership.php

@@ -2,6 +2,8 @@
 
 namespace Redmine\Api;
 
+use Redmine\Exception\MissingParameterException;
+
 /**
  * Handling project memberships.
  *
@@ -38,7 +40,7 @@ public function all($project, array $params = [])
      * @param string|int $project project id or literal identifier
      * @param array      $params  the new membership data
      *
-     * @throws \Exception Missing mandatory parameters
+     * @throws MissingParameterException Missing mandatory parameters
      *
      * @return string|false
      */
@@ -51,7 +53,7 @@ public function create($project, array $params = [])
         $params = $this->sanitizeParams($defaults, $params);
 
         if (!isset($params['user_id']) || !isset($params['role_ids'])) {
-            throw new \Exception('Missing mandatory parameters');
+            throw new MissingParameterException('Theses parameters are mandatory: `user_id`, `role_ids`');
         }
 
         $xml = $this->buildXML($params);
@@ -67,7 +69,7 @@ public function create($project, array $params = [])
      * @param int   $id     id of the membership
      * @param array $params the new membership data
      *
-     * @throws \Exception Missing mandatory parameters
+     * @throws MissingParameterException Missing mandatory parameters
      *
      * @return string|false
      */
@@ -79,7 +81,7 @@ public function update($id, array $params = [])
         $params = $this->sanitizeParams($defaults, $params);
 
         if (!isset($params['role_ids'])) {
-            throw new \Exception('Missing mandatory parameters');
+            throw new MissingParameterException('Missing mandatory parameters');
         }
 
         $xml = $this->buildXML($params);

src/Redmine/Api/Project.php

@@ -2,6 +2,8 @@
 
 namespace Redmine\Api;
 
+use Redmine\Exception\MissingParameterException;
+
 /**
  * Listing projects, creating, editing.
  *
@@ -98,7 +100,7 @@ public function show($id, array $params = [])
      *
      * @param array $params the new project data
      *
-     * @throws \Exception
+     * @throws MissingParameterException
      *
      * @return \SimpleXMLElement
      */
@@ -115,7 +117,7 @@ public function create(array $params = [])
             !isset($params['name'])
          || !isset($params['identifier'])
         ) {
-            throw new \Exception('Missing mandatory parameters');
+            throw new MissingParameterException('Theses parameters are mandatory: `name`, `identifier`');
         }
 
         $xml = $this->prepareParamsXml($params);

src/Redmine/Api/TimeEntry.php

@@ -2,6 +2,8 @@
 
 namespace Redmine\Api;
 
+use Redmine\Exception\MissingParameterException;
+
 /**
  * Listing time entries, creating, editing.
  *
@@ -50,7 +52,7 @@ public function show($id)
      *
      * @param array $params the new time entry data
      *
-     * @throws \Exception Missing mandatory parameters
+     * @throws MissingParameterException Missing mandatory parameters
      *
      * @return string|false
      */
@@ -70,7 +72,7 @@ public function create(array $params = [])
             (!isset($params['issue_id']) && !isset($params['project_id']))
          || !isset($params['hours'])
         ) {
-            throw new \Exception('Missing mandatory parameters');
+            throw new MissingParameterException('Theses parameters are mandatory: `issue_id` or `project_id`, `hours`');
         }
 
         $xml = new \SimpleXMLElement('<?xml version="1.0"?><time_entry></time_entry>');

src/Redmine/Api/User.php

@@ -2,6 +2,8 @@
 
 namespace Redmine\Api;
 
+use Redmine\Exception\MissingParameterException;
+
 /**
  * Listing users, creating, editing.
  *
@@ -129,7 +131,7 @@ public function show($id, array $params = [])
      *
      * @param array $params the new user data
      *
-     * @throws \Exception Missing mandatory parameters
+     * @throws MissingParameterException Missing mandatory parameters
      *
      * @return string|false
      */
@@ -150,7 +152,7 @@ public function create(array $params = [])
          || !isset($params['firstname'])
          || !isset($params['mail'])
         ) {
-            throw new \Exception('Missing mandatory parameters');
+            throw new MissingParameterException('Theses parameters are mandatory: `login`, `lastname`, `firstname`, `mail`');
         }
         $xml = new \SimpleXMLElement('<?xml version="1.0"?><user></user>');
         foreach ($params as $k => $v) {

src/Redmine/Api/Version.php

@@ -2,6 +2,9 @@
 
 namespace Redmine\Api;
 
+use Redmine\Exception\InvalidParameterException;
+use Redmine\Exception\MissingParameterException;
+
 /**
  * Listing versions, creating, editing.
  *
@@ -94,7 +97,7 @@ public function show($id)
      * @param string|int $project project id or literal identifier
      * @param array      $params  the new issue category data
      *
-     * @throws \Exception Missing mandatory parameters
+     * @throws MissingParameterException Missing mandatory parameters
      *
      * @return string|false
      */
@@ -112,7 +115,7 @@ public function create($project, array $params = [])
         if (
             !isset($params['name'])
         ) {
-            throw new \Exception('Missing mandatory parameters');
+            throw new MissingParameterException('Theses parameters are mandatory: `name`');
         }
         $this->validateStatus($params);
         $this->validateSharing($params);
@@ -171,7 +174,7 @@ private function validateStatus(array $params = [])
             'closed',
         ];
         if (isset($params['status']) && !in_array($params['status'], $arrStatus)) {
-            throw new \Exception('Possible values for status : '.implode(', ', $arrStatus));
+            throw new InvalidParameterException('Possible values for status : '.implode(', ', $arrStatus));
         }
     }
 
@@ -185,7 +188,7 @@ private function validateSharing(array $params = [])
             'system' => 'With all projects',
         ];
         if (isset($params['sharing']) && !isset($arrSharing[$params['sharing']])) {
-            throw new \Exception('Possible values for sharing : '.implode(', ', array_keys($arrSharing)));
+            throw new InvalidParameterException('Possible values for sharing : '.implode(', ', array_keys($arrSharing)));
         }
     }
 

src/Redmine/Client/Client.php

@@ -2,16 +2,16 @@
 
 namespace Redmine\Client;
 
-use InvalidArgumentException;
 use Redmine\Api;
+use Redmine\Exception\InvalidApiNameException;
 
 /**
  * client interface.
  */
 interface Client
 {
     /**
-     * @throws InvalidArgumentException if $name is not a valid api name
+     * @throws InvalidApiNameException if $name is not a valid api name
      */
     public function getApi(string $name): Api;
 

src/Redmine/Client/ClientApiTrait.php

@@ -2,8 +2,8 @@
 
 namespace Redmine\Client;
 
-use InvalidArgumentException;
 use Redmine\Api;
+use Redmine\Exception\InvalidApiNameException;
 
 /**
  * Provide API instantiation to clients.
@@ -38,12 +38,12 @@ trait ClientApiTrait
     ];
 
     /**
-     * @throws InvalidArgumentException if $name is not a valid api name
+     * @throws InvalidApiNameException if $name is not a valid api name
      */
     public function getApi(string $name): Api
     {
         if (!isset($this->apiClassnames[$name])) {
-            throw new InvalidArgumentException(sprintf('`%s` is not a valid api. Possible apis are `%s`', $name, implode('`, `', array_keys($this->apiClassnames))));
+            throw new InvalidApiNameException(sprintf('`%s` is not a valid api. Possible apis are `%s`', $name, implode('`, `', array_keys($this->apiClassnames))));
         }
         if (isset($this->apiInstances[$name])) {
             return $this->apiInstances[$name];

src/Redmine/Client/NativeCurlClient.php

@@ -4,8 +4,8 @@
 
 namespace Redmine\Client;
 
-use Exception;
 use Redmine\Api;
+use Redmine\Exception\ClientException;
 
 /**
  * Native cURL client.
@@ -210,7 +210,7 @@ private function unsetHttpHeader(string $name): void
     }
 
     /**
-     * @throws Exception If anything goes wrong on curl request
+     * @throws ClientException If anything goes wrong on curl request
      */
     private function request(string $method, string $path, string $body = ''): bool
     {
@@ -225,7 +225,7 @@ private function request(string $method, string $path, string $body = ''): bool
         $curlErrorNumber = curl_errno($curl);
 
         if (CURLE_OK !== $curlErrorNumber) {
-            $e = new Exception(curl_error($curl), $curlErrorNumber);
+            $e = new ClientException(curl_error($curl), $curlErrorNumber);
             curl_close($curl);
             throw $e;
         }