Merge pull request #383 from Art4/deprecate-abstractapi-post

Deprecate `AbstractApi::post()`

Author: Art4

CHANGELOG.md

@@ -13,6 +13,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - New interface `Redmine\Http\Request` for sending data with new minimalistic HTTP clients.
 - New method `Redmine\Api\...::getLastResponse()` to get the last response made by the API class.
 
+### Changed
+
+- Calling `Redmine\Api\IssueRelation::create()` without the mandatory parameter `issue_to_id` throws a `Redmine\Exception\MissingParameterException` instead of returning a error array
+
 ### Fixed
 
 - Parameter types for IDs were fixed in API for attachments, groups, issues, project, users and versions.
@@ -23,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Deprecated
 
 - `Redmine\Api\AbstractApi::get()` is deprecated, use `\Redmine\Http\HttpClient::request()` instead.
+- `Redmine\Api\AbstractApi::post()` is deprecated, use `\Redmine\Http\HttpClient::request()` instead.
 
 ## [v2.5.0](https://github.com/kbsali/php-redmine-api/compare/v2.4.0...v2.5.0) - 2024-02-05
 

src/Redmine/Api/AbstractApi.php

@@ -2,7 +2,6 @@
 
 namespace Redmine\Api;
 
-use Closure;
 use InvalidArgumentException;
 use Redmine\Api;
 use Redmine\Client\Client;
@@ -142,13 +141,17 @@ protected function get($path, $decodeIfJson = true)
     /**
      * Perform the client post() method.
      *
+     * @deprecated since v2.6.0, use `\Redmine\Http\HttpClient::request()` instead
+     *
      * @param string $path
      * @param string $data
      *
      * @return string|SimpleXMLElement|false
      */
     protected function post($path, $data)
     {
+        @trigger_error('`' . __METHOD__ . '()` is deprecated since v2.6.0, use `\Redmine\Http\HttpClient::request()` instead.', E_USER_DEPRECATED);
+
         $this->lastResponse = $this->getHttpClient()->request(HttpFactory::makeRequest(
             'POST',
             strval($path),

src/Redmine/Api/Attachment.php

@@ -6,6 +6,7 @@
 use Redmine\Http\HttpFactory;
 use Redmine\Serializer\JsonSerializer;
 use Redmine\Serializer\PathSerializer;
+use SimpleXMLElement;
 
 /**
  * Attachment details.
@@ -80,10 +81,14 @@ public function download($id)
      */
     public function upload($attachment, $params = [])
     {
-        return $this->post(
+        $this->lastResponse = $this->getHttpClient()->request(HttpFactory::makeRequest(
+            'POST',
             PathSerializer::create('/uploads.json', $params)->getPath(),
+            'application/octet-stream',
             $attachment
-        );
+        ));
+
+        return $this->lastResponse->getContent();
     }
 
     /**
@@ -93,7 +98,7 @@ public function upload($attachment, $params = [])
      *
      * @param int $id id of the attachment
      *
-     * @return false|\SimpleXMLElement|string
+     * @return false|SimpleXMLElement|string
      */
     public function remove($id)
     {

src/Redmine/Api/Group.php

@@ -120,10 +120,19 @@ public function create(array $params = [])
             throw new MissingParameterException('Theses parameters are mandatory: `name`');
         }
 
-        return $this->post(
+        $this->lastResponse = $this->getHttpClient()->request(HttpFactory::makeXmlRequest(
+            'POST',
             '/groups.xml',
             XmlSerializer::createFromArray(['group' => $params])->getEncoded()
-        );
+        ));
+
+        $body = $this->lastResponse->getContent();
+
+        if ($body === '') {
+            return $body;
+        }
+
+        return new SimpleXMLElement($body);
     }
 
     /**
@@ -205,14 +214,23 @@ public function remove($id)
      * @param int $id     id of the group
      * @param int $userId id of the user
      *
-     * @return string
+     * @return SimpleXMLElement|string
      */
     public function addUser($id, $userId)
     {
-        return $this->post(
+        $this->lastResponse = $this->getHttpClient()->request(HttpFactory::makeXmlRequest(
+            'POST',
             '/groups/' . $id . '/users.xml',
             XmlSerializer::createFromArray(['user_id' => $userId])->getEncoded()
-        );
+        ));
+
+        $body = $this->lastResponse->getContent();
+
+        if ($body === '') {
+            return $body;
+        }
+
+        return new SimpleXMLElement($body);
     }
 
     /**

src/Redmine/Api/Issue.php

@@ -189,10 +189,24 @@ public function create(array $params = [])
         $params = $this->cleanParams($params);
         $params = $this->sanitizeParams($defaults, $params);
 
-        return $this->post(
+        // FIXME: Throw exception on missing mandatory parameters
+        // if (!isset($params['subject']) || !isset($params['project_id']) || !isset($params['tracker_id']) || !isset($params['priority_id']) || !isset($params['status_id'])) {
+        //     throw new MissingParameterException('Theses parameters are mandatory: `subject`, `project_id|project`, `tracker_id|tracker`, `priority_id|priority`, `status_id|status`');
+        // }
+
+        $this->lastResponse = $this->getHttpClient()->request(HttpFactory::makeXmlRequest(
+            'POST',
             '/issues.xml',
             XmlSerializer::createFromArray(['issue' => $params])->getEncoded()
-        );
+        ));
+
+        $body = $this->lastResponse->getContent();
+
+        if ($body === '') {
+            return $body;
+        }
+
+        return new SimpleXMLElement($body);
     }
 
     /**
@@ -236,21 +250,30 @@ public function update($id, array $params)
      * @param int $id
      * @param int $watcherUserId
      *
-     * @return false|string
+     * @return SimpleXMLElement|string
      */
     public function addWatcher($id, $watcherUserId)
     {
-        return $this->post(
+        $this->lastResponse = $this->getHttpClient()->request(HttpFactory::makeXmlRequest(
+            'POST',
             '/issues/' . urlencode(strval($id)) . '/watchers.xml',
             XmlSerializer::createFromArray(['user_id' => urlencode(strval($watcherUserId))])->getEncoded()
-        );
+        ));
+
+        $body = $this->lastResponse->getContent();
+
+        if ($body === '') {
+            return $body;
+        }
+
+        return new SimpleXMLElement($body);
     }
 
     /**
      * @param int $id
      * @param int $watcherUserId
      *
-     * @return false|\SimpleXMLElement|string
+     * @return false|SimpleXMLElement|string
      */
     public function removeWatcher($id, $watcherUserId)
     {
@@ -385,7 +408,7 @@ public function attachMany($id, array $attachments)
      *
      * @param int $id the issue number
      *
-     * @return false|\SimpleXMLElement|string
+     * @return false|SimpleXMLElement|string
      */
     public function remove($id)
     {

src/Redmine/Api/IssueCategory.php

@@ -11,6 +11,7 @@
 use Redmine\Serializer\JsonSerializer;
 use Redmine\Serializer\PathSerializer;
 use Redmine\Serializer\XmlSerializer;
+use SimpleXMLElement;
 
 /**
  * Listing issue categories, creating, editing.
@@ -161,7 +162,7 @@ public function show($id)
      *
      * @throws MissingParameterException Missing mandatory parameters
      *
-     * @return string|false
+     * @return SimpleXMLElement|string
      */
     public function create($project, array $params = [])
     {
@@ -177,10 +178,19 @@ public function create($project, array $params = [])
             throw new MissingParameterException('Theses parameters are mandatory: `name`');
         }
 
-        return $this->post(
+        $this->lastResponse = $this->getHttpClient()->request(HttpFactory::makeXmlRequest(
+            'POST',
             '/projects/' . $project . '/issue_categories.xml',
             XmlSerializer::createFromArray(['issue_category' => $params])->getEncoded()
-        );
+        ));
+
+        $body = $this->lastResponse->getContent();
+
+        if ($body === '') {
+            return $body;
+        }
+
+        return new SimpleXMLElement($body);
     }
 
     /**

src/Redmine/Api/IssueRelation.php

@@ -3,6 +3,7 @@
 namespace Redmine\Api;
 
 use Redmine\Exception;
+use Redmine\Exception\MissingParameterException;
 use Redmine\Exception\SerializerException;
 use Redmine\Exception\UnexpectedResponseException;
 use Redmine\Http\HttpFactory;
@@ -127,10 +128,17 @@ public function remove($id)
      * Create a new issue relation.
      *
      * @see http://www.redmine.org/projects/redmine/wiki/Rest_IssueRelations#POST
+     * available $params:
+     * - issue_to_id (required): the id of the related issue
+     * - relation_type (required to explicit : default "relates"): the type of relation
+     *   (in: "relates", "duplicates", "duplicated", "blocks", "blocked", "precedes", "follows", "copied_to", "copied_from")
+     * - delay (optional): the delay for a "precedes" or "follows" relation
      *
      * @param int   $issueId the ID of the issue we are creating the relation on
      * @param array $params  the new issue relation data
      *
+     * @throws MissingParameterException Missing mandatory parameters
+     *
      * @return array
      */
     public function create($issueId, array $params = [])
@@ -143,11 +151,18 @@ public function create($issueId, array $params = [])
 
         $params = $this->sanitizeParams($defaults, $params);
 
-        $response = $this->post(
+        if (!isset($params['issue_to_id'])) {
+            throw new MissingParameterException('Theses parameters are mandatory: `issue_to_id`');
+        }
+
+        $this->lastResponse = $this->getHttpClient()->request(HttpFactory::makeJsonRequest(
+            'POST',
             '/issues/' . urlencode(strval($issueId)) . '/relations.json',
             JsonSerializer::createFromArray(['relation' => $params])->getEncoded()
-        );
+        ));
+
+        $body = $this->lastResponse->getContent();
 
-        return JsonSerializer::createFromString($response)->getNormalized();
+        return JsonSerializer::createFromString($body)->getNormalized();
     }
 }

src/Redmine/Api/Membership.php

@@ -7,7 +7,9 @@
 use Redmine\Exception\MissingParameterException;
 use Redmine\Exception\SerializerException;
 use Redmine\Exception\UnexpectedResponseException;
+use Redmine\Http\HttpFactory;
 use Redmine\Serializer\XmlSerializer;
+use SimpleXMLElement;
 
 /**
  * Handling project memberships.
@@ -92,7 +94,7 @@ public function all($project, array $params = [])
      *
      * @throws MissingParameterException Missing mandatory parameters
      *
-     * @return string|false
+     * @return SimpleXMLElement|string
      */
     public function create($project, array $params = [])
     {
@@ -106,10 +108,19 @@ public function create($project, array $params = [])
             throw new MissingParameterException('Theses parameters are mandatory: `user_id`, `role_ids`');
         }
 
-        return $this->post(
+        $this->lastResponse = $this->getHttpClient()->request(HttpFactory::makeXmlRequest(
+            'POST',
             '/projects/' . $project . '/memberships.xml',
             XmlSerializer::createFromArray(['membership' => $params])->getEncoded()
-        );
+        ));
+
+        $body = $this->lastResponse->getContent();
+
+        if ('' !== $body) {
+            return new SimpleXMLElement($body);
+        }
+
+        return $body;
     }
 
     /**

src/Redmine/Api/Project.php

@@ -162,7 +162,7 @@ public function show($id, array $params = [])
      *
      * @throws MissingParameterException
      *
-     * @return string|SimpleXMLElement|false
+     * @return SimpleXMLElement|string
      */
     public function create(array $params = [])
     {
@@ -180,10 +180,19 @@ public function create(array $params = [])
             throw new MissingParameterException('Theses parameters are mandatory: `name`, `identifier`');
         }
 
-        return $this->post(
+        $this->lastResponse = $this->getHttpClient()->request(HttpFactory::makeXmlRequest(
+            'POST',
             '/projects.xml',
             XmlSerializer::createFromArray(['project' => $params])->getEncoded()
-        );
+        ));
+
+        $body = $this->lastResponse->getContent();
+
+        if ('' !== $body) {
+            return new SimpleXMLElement($body);
+        }
+
+        return $body;
     }
 
     /**

src/Redmine/Api/TimeEntry.php

@@ -9,6 +9,7 @@
 use Redmine\Http\HttpFactory;
 use Redmine\Serializer\JsonSerializer;
 use Redmine\Serializer\XmlSerializer;
+use SimpleXMLElement;
 
 /**
  * Listing time entries, creating, editing.
@@ -111,7 +112,7 @@ public function show($id)
      *
      * @throws MissingParameterException Missing mandatory parameters
      *
-     * @return string|false
+     * @return SimpleXMLElement|string
      */
     public function create(array $params = [])
     {
@@ -132,10 +133,19 @@ public function create(array $params = [])
             throw new MissingParameterException('Theses parameters are mandatory: `issue_id` or `project_id`, `hours`');
         }
 
-        return $this->post(
+        $this->lastResponse = $this->getHttpClient()->request(HttpFactory::makeXmlRequest(
+            'POST',
             '/time_entries.xml',
             XmlSerializer::createFromArray(['time_entry' => $params])->getEncoded()
-        );
+        ));
+
+        $body = $this->lastResponse->getContent();
+
+        if ('' !== $body) {
+            return new SimpleXMLElement($body);
+        }
+
+        return $body;
     }
 
     /**