Check response status codes

CHANGELOG.md

@@ -10,6 +10,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Add support for Redmine 7.0.
+- `\Redmine\Client\NativeCurlClient::enableFutureMode()` to opt-in to throwing `UnexpectedResponseException` on unexpected status codes.
+- `\Redmine\Client\Psr18Client::enableFutureMode()` to opt-in to throwing `UnexpectedResponseException` on unexpected status codes.
+- API methods that create, update, or delete resources now verify the HTTP response status code. The return value only changes if `enableFutureMode()` was called – unexpected status codes then throw `UnexpectedResponseException` instead of returning the response body.
 
 ### Changed
 

README.md

@@ -69,8 +69,6 @@ you are welcome to [create an issue](https://github.com/kbsali/php-redmine-api/i
 ## Todo
 
 * Tracking of Redmine API feature support in [#305](https://github.com/kbsali/php-redmine-api/issues/305)
-* Check header's response code (especially for POST/PUT/DELETE requests)
-    * See https://stackoverflow.com/questions/9183178/php-curl-retrieving-response-headers-and-body-in-a-single-request/9183272#9183272
 
 ## Limitations / Missing Redmine-API
 

docs/usage.md

@@ -215,6 +215,34 @@ try {
 }
 ```
 
+### Forward compatibility mode
+
+By default, API methods that create, update, or delete resources return the raw response body even if the HTTP status code indicates an error. This preserves backwards compatibility with existing code.
+
+You can opt-in to stricter behavior by enabling the forward compatibility mode on the client:
+
+```php
+$client->enableFutureMode();
+```
+
+After calling `enableFutureMode()`, any unexpected status code (e.g. a 422 validation error) throws `\Redmine\Exception\UnexpectedResponseException` instead of returning the response body. This allows you to catch and handle errors more reliably.
+
+```php
+$client->enableFutureMode();
+
+try {
+    $client->getApi('issue')->create([
+        'project_id' => 1,
+        'subject' => 'test',
+    ]);
+} catch (\Redmine\Exception\UnexpectedResponseException $e) {
+    // Handle unexpected response (wrong status code)
+    $response = $e->getResponse();
+    $statusCode = $response->getStatusCode();
+    $body = $response->getContent();
+}
+```
+
 ## API
 
 ### Mid-level API

src/Redmine/Api/Attachment.php

@@ -7,6 +7,7 @@
 use Redmine\Client\Client;
 use Redmine\Exception\SerializerException;
 use Redmine\Exception\UnexpectedResponseException;
+use Redmine\Future;
 use Redmine\Http\HttpClient;
 use Redmine\Http\HttpFactory;
 use Redmine\Serializer\JsonSerializer;
@@ -156,7 +157,17 @@ public function upload($attachment, $params = [])
             $attachment,
         ));
 
-        return $this->lastResponse->getContent();
+        $body = $this->lastResponse->getContent();
+
+        if ($this->lastResponse->getStatusCode() !== 201) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
+
+        return $body;
     }
 
     /**
@@ -175,6 +186,17 @@ public function remove($id)
             '/attachments/' . urlencode(strval($id)) . '.xml',
         ));
 
-        return $this->lastResponse->getContent();
+        $body = $this->lastResponse->getContent();
+        $statusCode = $this->lastResponse->getStatusCode();
+
+        if ($statusCode !== 200 && $statusCode !== 204) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
+
+        return $body;
     }
 }

src/Redmine/Api/Group.php

@@ -9,6 +9,7 @@
 use Redmine\Exception\MissingParameterException;
 use Redmine\Exception\SerializerException;
 use Redmine\Exception\UnexpectedResponseException;
+use Redmine\Future;
 use Redmine\Http\HttpClient;
 use Redmine\Http\HttpFactory;
 use Redmine\Serializer\JsonSerializer;
@@ -195,6 +196,15 @@ public function create(array $params = [])
         ));
 
         $body = $this->lastResponse->getContent();
+        $statusCode = $this->lastResponse->getStatusCode();
+
+        if ($statusCode !== 201) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
 
         if ($body === '') {
             return $body;
@@ -229,7 +239,18 @@ public function update(int $id, array $params = [])
             XmlSerializer::createFromArray(['group' => $params])->getEncoded(),
         ));
 
-        return $this->lastResponse->getContent();
+        $body = $this->lastResponse->getContent();
+        $statusCode = $this->lastResponse->getStatusCode();
+
+        if ($statusCode !== 200 && $statusCode !== 204) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
+
+        return $body;
     }
 
     /**
@@ -280,7 +301,18 @@ public function remove($id)
             '/groups/' . strval($id) . '.xml',
         ));
 
-        return $this->lastResponse->getContent();
+        $body = $this->lastResponse->getContent();
+        $statusCode = $this->lastResponse->getStatusCode();
+
+        if ($statusCode !== 200 && $statusCode !== 204) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
+
+        return $body;
     }
 
     /**
@@ -302,6 +334,15 @@ public function addUser($id, $userId)
         ));
 
         $body = $this->lastResponse->getContent();
+        $statusCode = $this->lastResponse->getStatusCode();
+
+        if ($statusCode !== 201) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
 
         if ($body === '') {
             return $body;
@@ -327,6 +368,17 @@ public function removeUser($id, $userId)
             '/groups/' . strval($id) . '/users/' . strval($userId) . '.xml',
         ));
 
-        return $this->lastResponse->getContent();
+        $body = $this->lastResponse->getContent();
+        $statusCode = $this->lastResponse->getStatusCode();
+
+        if ($statusCode !== 200 && $statusCode !== 204) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
+
+        return $body;
     }
 }

src/Redmine/Api/Issue.php

@@ -10,6 +10,7 @@
 use Redmine\Exception;
 use Redmine\Exception\SerializerException;
 use Redmine\Exception\UnexpectedResponseException;
+use Redmine\Future;
 use Redmine\Http\HttpClient;
 use Redmine\Http\HttpFactory;
 use Redmine\Serializer\JsonSerializer;
@@ -256,8 +257,16 @@ public function create(array $params = [])
 
         $body = $this->lastResponse->getContent();
 
-        if ($body === '') {
-            return $body;
+        if ($this->lastResponse->getStatusCode() !== 201) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                if ($body === '') {
+                    return $body;
+                }
+
+                return new SimpleXMLElement($body);
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
         }
 
         return new SimpleXMLElement($body);
@@ -306,7 +315,18 @@ public function update($id, array $params)
             XmlSerializer::createFromArray(['issue' => $sanitizedParams])->getEncoded(),
         ));
 
-        return $this->lastResponse->getContent();
+        $body = $this->lastResponse->getContent();
+        $statusCode = $this->lastResponse->getStatusCode();
+
+        if ($statusCode !== 200 && $statusCode !== 204) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
+
+        return $body;
     }
 
     /**
@@ -324,6 +344,15 @@ public function addWatcher($id, $watcherUserId)
         ));
 
         $body = $this->lastResponse->getContent();
+        $statusCode = $this->lastResponse->getStatusCode();
+
+        if ($statusCode !== 201) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
 
         if ($body === '') {
             return $body;
@@ -345,7 +374,18 @@ public function removeWatcher($id, $watcherUserId)
             '/issues/' . urlencode(strval($id)) . '/watchers/' . urlencode(strval($watcherUserId)) . '.xml',
         ));
 
-        return $this->lastResponse->getContent();
+        $body = $this->lastResponse->getContent();
+        $statusCode = $this->lastResponse->getStatusCode();
+
+        if ($statusCode !== 200 && $statusCode !== 204) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
+
+        return $body;
     }
 
     /**
@@ -498,7 +538,18 @@ public function attachMany($id, array $attachments)
             JsonSerializer::createFromArray(['issue' => $params])->getEncoded(),
         ));
 
-        return $this->lastResponse->getContent();
+        $body = $this->lastResponse->getContent();
+        $statusCode = $this->lastResponse->getStatusCode();
+
+        if ($statusCode !== 200 && $statusCode !== 201 && $statusCode !== 204) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
+
+        return $body;
     }
 
     /**
@@ -515,7 +566,18 @@ public function remove($id)
             '/issues/' . urlencode(strval($id)) . '.xml',
         ));
 
-        return $this->lastResponse->getContent();
+        $body = $this->lastResponse->getContent();
+        $statusCode = $this->lastResponse->getStatusCode();
+
+        if ($statusCode !== 200 && $statusCode !== 204) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
+
+        return $body;
     }
 
     /**

src/Redmine/Api/IssueCategory.php

@@ -10,6 +10,7 @@
 use Redmine\Exception\MissingParameterException;
 use Redmine\Exception\SerializerException;
 use Redmine\Exception\UnexpectedResponseException;
+use Redmine\Future;
 use Redmine\Http\HttpClient;
 use Redmine\Http\HttpFactory;
 use Redmine\Serializer\JsonSerializer;
@@ -267,6 +268,18 @@ public function create($project, array $params = [])
 
         $body = $this->lastResponse->getContent();
 
+        if ($this->lastResponse->getStatusCode() !== 201) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                if ($body === '') {
+                    return $body;
+                }
+
+                return new SimpleXMLElement($body);
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
+
         if ($body === '') {
             return $body;
         }
@@ -298,7 +311,18 @@ public function update($id, array $params)
             XmlSerializer::createFromArray(['issue_category' => $params])->getEncoded(),
         ));
 
-        return $this->lastResponse->getContent();
+        $body = $this->lastResponse->getContent();
+        $statusCode = $this->lastResponse->getStatusCode();
+
+        if ($statusCode !== 200 && $statusCode !== 204) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
+
+        return $body;
     }
 
     /**
@@ -320,7 +344,18 @@ public function remove($id, array $params = [])
             PathSerializer::create('/issue_categories/' . urlencode(strval($id)) . '.xml', $params)->getPath(),
         ));
 
-        return $this->lastResponse->getContent();
+        $body = $this->lastResponse->getContent();
+        $statusCode = $this->lastResponse->getStatusCode();
+
+        if ($statusCode !== 200 && $statusCode !== 204) {
+            if (!Future::isForwardCompatibilityEnabled()) {
+                return $body;
+            }
+
+            throw UnexpectedResponseException::create($this->lastResponse);
+        }
+
+        return $body;
     }
 
     /**