Improve Xml- and JsonSerializer

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased](https://github.com/kbsali/php-redmine-api/compare/v2.2.0...v2.x)
 
+### Deprecated
+
+- `Redmine\Api\AbstractApi::attachCustomFieldXML()` is deprecated
+- `Redmine\Api\Project::prepareParamsXml()` is deprecated
+
 ## [v2.2.0](https://github.com/kbsali/php-redmine-api/compare/v2.1.1...v2.2.0) - 2022-03-01
 
 ### Added

src/Redmine/Api/AbstractApi.php

@@ -185,7 +185,7 @@ protected function retrieveAll($endpoint, array $params = [])
     }
 
     /**
-     * Retrieves all the elements of a given endpoint (even if the
+     * Retrieves as many elements as you want of a given endpoint (even if the
      * total number of elements is greater than 100).
      *
      * @param string $endpoint API end point
@@ -253,6 +253,8 @@ protected function retrieveData(string $endpoint, array $params = []): array
     /**
      * Attaches Custom Fields to a create/update query.
      *
+     * @deprecated the `attachCustomFieldXML()` method is deprecated.
+     *
      * @param SimpleXMLElement $xml    XML Element the custom fields are attached to
      * @param array            $fields array of fields to attach, each field needs name, id and value set
      *
@@ -262,6 +264,8 @@ protected function retrieveData(string $endpoint, array $params = []): array
      */
     protected function attachCustomFieldXML(SimpleXMLElement $xml, array $fields)
     {
+        @trigger_error('The '.__METHOD__.' method is deprecated.', E_USER_DEPRECATED);
+
         $_fields = $xml->addChild('custom_fields');
         $_fields->addAttribute('type', 'array');
         foreach ($fields as $field) {

src/Redmine/Api/Group.php

@@ -5,6 +5,7 @@
 use Exception;
 use Redmine\Exception\MissingParameterException;
 use Redmine\Serializer\PathSerializer;
+use Redmine\Serializer\XmlSerializer;
 
 /**
  * Handling of groups.
@@ -78,9 +79,10 @@ public function create(array $params = [])
             throw new MissingParameterException('Theses parameters are mandatory: `name`');
         }
 
-        $xml = $this->buildXML($params);
-
-        return $this->post('/groups.xml', $xml->asXML());
+        return $this->post(
+            '/groups.xml',
+            XmlSerializer::createFromArray(['group' => $params])->getEncoded()
+        );
     }
 
     /**
@@ -142,9 +144,10 @@ public function remove($id)
      */
     public function addUser($id, $userId)
     {
-        $xml = new \SimpleXMLElement('<?xml version="1.0"?><user_id>'.$userId.'</user_id>');
-
-        return $this->post('/groups/'.$id.'/users.xml', $xml->asXML());
+        return $this->post(
+            '/groups/'.$id.'/users.xml',
+            XmlSerializer::createFromArray(['user_id' => $userId])->getEncoded()
+        );
     }
 
     /**
@@ -161,29 +164,4 @@ public function removeUser($id, $userId)
     {
         return $this->delete('/groups/'.$id.'/users/'.$userId.'.xml');
     }
-
-    /**
-     * Build the XML for a group.
-     *
-     * @param array $params for the new/updated group data
-     *
-     * @return \SimpleXMLElement
-     */
-    private function buildXML(array $params = [])
-    {
-        $xml = new \SimpleXMLElement('<?xml version="1.0"?><group></group>');
-
-        foreach ($params as $k => $v) {
-            if ('user_ids' === $k && is_array($v)) {
-                $item = $xml->addChild($k);
-                foreach ($v as $role) {
-                    $item->addChild('user_id', $role);
-                }
-            } else {
-                $xml->addChild($k, $v);
-            }
-        }
-
-        return $xml;
-    }
 }

src/Redmine/Api/Issue.php

@@ -2,7 +2,9 @@
 
 namespace Redmine\Api;
 
+use Redmine\Serializer\JsonSerializer;
 use Redmine\Serializer\PathSerializer;
+use Redmine\Serializer\XmlSerializer;
 
 /**
  * Listing issues, searching, editing and closing your projects issues.
@@ -66,45 +68,6 @@ public function show($id, array $params = [])
         );
     }
 
-    /**
-     * Build the XML for an issue.
-     *
-     * @param array $params for the new/updated issue data
-     *
-     * @return \SimpleXMLElement
-     */
-    private function buildXML(array $params = [])
-    {
-        $xml = new \SimpleXMLElement('<?xml version="1.0"?><issue></issue>');
-
-        foreach ($params as $k => $v) {
-            if ('custom_fields' === $k && is_array($v)) {
-                $this->attachCustomFieldXML($xml, $v);
-            } elseif ('watcher_user_ids' === $k && is_array($v)) {
-                $watcherUserIds = $xml->addChild('watcher_user_ids', '');
-                $watcherUserIds->addAttribute('type', 'array');
-                foreach ($v as $watcher) {
-                    $watcherUserIds->addChild('watcher_user_id', (int) $watcher);
-                }
-            } elseif ('uploads' === $k && is_array($v)) {
-                $uploadsItem = $xml->addChild('uploads', '');
-                $uploadsItem->addAttribute('type', 'array');
-                foreach ($v as $upload) {
-                    $upload_item = $uploadsItem->addChild('upload', '');
-                    foreach ($upload as $upload_k => $upload_v) {
-                        $upload_item->addChild($upload_k, $upload_v);
-                    }
-                }
-            } else {
-                // "addChild" does not escape text for XML value, but the setter does.
-                // http://stackoverflow.com/a/555039/99904
-                $xml->$k = $v;
-            }
-        }
-
-        return $xml;
-    }
-
     /**
      * Create a new issue given an array of $params
      * The issue is assigned to the authenticated user.
@@ -135,9 +98,10 @@ public function create(array $params = [])
         $params = $this->cleanParams($params);
         $params = $this->sanitizeParams($defaults, $params);
 
-        $xml = $this->buildXML($params);
-
-        return $this->post('/issues.xml', $xml->asXML());
+        return $this->post(
+            '/issues.xml',
+            XmlSerializer::createFromArray(['issue' => $params])->getEncoded()
+        );
     }
 
     /**
@@ -171,9 +135,10 @@ public function update($id, array $params)
             $sanitizedParams['assigned_to_id'] = '';
         }
 
-        $xml = $this->buildXML($sanitizedParams);
-
-        return $this->put('/issues/'.$id.'.xml', $xml->asXML());
+        return $this->put(
+            '/issues/'.$id.'.xml',
+            XmlSerializer::createFromArray(['issue' => $sanitizedParams])->getEncoded()
+        );
     }
 
     /**
@@ -184,7 +149,10 @@ public function update($id, array $params)
      */
     public function addWatcher($id, $watcherUserId)
     {
-        return $this->post('/issues/'.$id.'/watchers.xml', '<user_id>'.$watcherUserId.'</user_id>');
+        return $this->post(
+            '/issues/'.$id.'/watchers.xml',
+            XmlSerializer::createFromArray(['user_id' => $watcherUserId])->getEncoded()
+        );
     }
 
     /**
@@ -207,10 +175,9 @@ public function removeWatcher($id, $watcherUserId)
     public function setIssueStatus($id, $status)
     {
         $api = $this->client->getApi('issue_status');
-        $statusId = $api->getIdByName($status);
 
         return $this->update($id, [
-            'status_id' => $statusId,
+            'status_id' => $api->getIdByName($status),
         ]);
     }
 
@@ -300,13 +267,15 @@ public function attach($id, array $attachment)
      */
     public function attachMany($id, array $attachments)
     {
-        $request = [];
-        $request['issue'] = [
+        $params = [
             'id' => $id,
             'uploads' => $attachments,
         ];
 
-        return $this->put('/issues/'.$id.'.json', json_encode($request));
+        return $this->put(
+            '/issues/'.$id.'.json',
+            JsonSerializer::createFromArray(['issue' => $params])->getEncoded()
+        );
     }
 
     /**

src/Redmine/Api/IssueCategory.php

@@ -4,6 +4,7 @@
 
 use Redmine\Exception\MissingParameterException;
 use Redmine\Serializer\PathSerializer;
+use Redmine\Serializer\XmlSerializer;
 
 /**
  * Listing issue categories, creating, editing.
@@ -112,12 +113,10 @@ public function create($project, array $params = [])
             throw new MissingParameterException('Theses parameters are mandatory: `name`');
         }
 
-        $xml = new \SimpleXMLElement('<?xml version="1.0"?><issue_category></issue_category>');
-        foreach ($params as $k => $v) {
-            $xml->addChild($k, $v);
-        }
-
-        return $this->post('/projects/'.$project.'/issue_categories.xml', $xml->asXML());
+        return $this->post(
+            '/projects/'.$project.'/issue_categories.xml',
+            XmlSerializer::createFromArray(['issue_category' => $params])->getEncoded()
+        );
     }
 
     /**
@@ -137,12 +136,10 @@ public function update($id, array $params)
         ];
         $params = $this->sanitizeParams($defaults, $params);
 
-        $xml = new \SimpleXMLElement('<?xml version="1.0"?><issue_category></issue_category>');
-        foreach ($params as $k => $v) {
-            $xml->addChild($k, $v);
-        }
-
-        return $this->put('/issue_categories/'.$id.'.xml', $xml->asXML());
+        return $this->put(
+            '/issue_categories/'.$id.'.xml',
+            XmlSerializer::createFromArray(['issue_category' => $params])->getEncoded()
+        );
     }
 
     /**

src/Redmine/Api/IssueRelation.php

@@ -85,9 +85,10 @@ public function create($issueId, array $params = [])
 
         $params = $this->sanitizeParams($defaults, $params);
 
-        $params = json_encode(['relation' => $params]);
-
-        $response = $this->post('/issues/'.urlencode($issueId).'/relations.json', $params);
+        $response = $this->post(
+            '/issues/'.urlencode($issueId).'/relations.json',
+            JsonSerializer::createFromArray(['relation' => $params])->getEncoded()
+        );
 
         return JsonSerializer::createFromString($response)->getNormalized();
     }

src/Redmine/Api/Membership.php

@@ -3,6 +3,7 @@
 namespace Redmine\Api;
 
 use Redmine\Exception\MissingParameterException;
+use Redmine\Serializer\XmlSerializer;
 
 /**
  * Handling project memberships.
@@ -56,9 +57,10 @@ public function create($project, array $params = [])
             throw new MissingParameterException('Theses parameters are mandatory: `user_id`, `role_ids`');
         }
 
-        $xml = $this->buildXML($params);
-
-        return $this->post('/projects/'.$project.'/memberships.xml', $xml->asXML());
+        return $this->post(
+            '/projects/'.$project.'/memberships.xml',
+            XmlSerializer::createFromArray(['membership' => $params])->getEncoded()
+        );
     }
 
     /**
@@ -84,9 +86,10 @@ public function update($id, array $params = [])
             throw new MissingParameterException('Missing mandatory parameters');
         }
 
-        $xml = $this->buildXML($params);
-
-        return $this->put('/memberships/'.$id.'.xml', $xml->asXML());
+        return $this->put(
+            '/memberships/'.$id.'.xml',
+            XmlSerializer::createFromArray(['membership' => $params])->getEncoded()
+        );
     }
 
     /**
@@ -129,30 +132,4 @@ public function removeMember($projectId, $userId, array $params = [])
 
         return $removed;
     }
-
-    /**
-     * Build the XML for a membership.
-     *
-     * @param array $params for the new/updated membership data
-     *
-     * @return \SimpleXMLElement
-     */
-    private function buildXML(array $params = [])
-    {
-        $xml = new \SimpleXMLElement('<?xml version="1.0"?><membership></membership>');
-
-        foreach ($params as $k => $v) {
-            if ('role_ids' === $k && is_array($v)) {
-                $item = $xml->addChild($k);
-                $item->addAttribute('type', 'array');
-                foreach ($v as $role) {
-                    $item->addChild('role_id', $role);
-                }
-            } else {
-                $xml->addChild($k, $v);
-            }
-        }
-
-        return $xml;
-    }
 }