From 39a57616f043918bc2a39ba2ad8e5544accbbef1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Elan=20Ruusam=C3=A4e?= <glen@delfi.ee>
Date: Tue, 1 May 2018 09:05:25 +0300
Subject: [PATCH 1/4] Move to Eventum\RPC namespace

---
 .php_cs                                   |  2 ++
 composer.json                             |  5 ++++-
 lib/Eventum_RPC.php                       | 18 ++++++++++++++++++
 lib/Eventum_RPC_Exception.php             | 18 ++++++++++++++++++
 src/{Eventum_RPC.php => XmlRpcClient.php} | 14 +++++++-------
 src/XmlRpcException.php                   | 20 ++++++++++++++++++++
 6 files changed, 69 insertions(+), 8 deletions(-)
 create mode 100644 lib/Eventum_RPC.php
 create mode 100644 lib/Eventum_RPC_Exception.php
 rename src/{Eventum_RPC.php => XmlRpcClient.php} (91%)
 create mode 100644 src/XmlRpcException.php

diff --git a/.php_cs b/.php_cs
index 4baa296..2dbc90d 100644
--- a/.php_cs
+++ b/.php_cs
@@ -122,3 +122,5 @@ return Symfony\CS\Config\Config::create()
 	))
 	->finder($finder)
 ;
+
+// vim:ft=php
diff --git a/composer.json b/composer.json
index fae02a3..4343cff 100644
--- a/composer.json
+++ b/composer.json
@@ -13,7 +13,10 @@
 		"phpxmlrpc/phpxmlrpc": "^4.2.2"
 	},
 	"autoload": {
-		"classmap": [ "src" ]
+		"psr-4": {
+			"Eventum\\RPC\\": "src/"
+		},
+		"classmap": [ "lib" ]
 	},
 	"autoload-dev": {
 		"psr-4": {
diff --git a/lib/Eventum_RPC.php b/lib/Eventum_RPC.php
new file mode 100644
index 0000000..71f2571
--- /dev/null
+++ b/lib/Eventum_RPC.php
@@ -0,0 +1,18 @@
+<?php
+
+/*
+ * This file is part of the Eventum (Issue Tracking System) package.
+ *
+ * @copyright (c) Eventum Team
+ * @license GNU General Public License, version 2 or later (GPL-2+)
+ *
+ * For the full copyright and license information,
+ * please see the COPYING and AUTHORS files
+ * that were distributed with this source code.
+ */
+
+use Eventum\RPC\XmlRpcClient;
+
+class Eventum_RPC extends XmlRpcClient
+{
+}
diff --git a/lib/Eventum_RPC_Exception.php b/lib/Eventum_RPC_Exception.php
new file mode 100644
index 0000000..b222cef
--- /dev/null
+++ b/lib/Eventum_RPC_Exception.php
@@ -0,0 +1,18 @@
+<?php
+
+/*
+ * This file is part of the Eventum (Issue Tracking System) package.
+ *
+ * @copyright (c) Eventum Team
+ * @license GNU General Public License, version 2 or later (GPL-2+)
+ *
+ * For the full copyright and license information,
+ * please see the COPYING and AUTHORS files
+ * that were distributed with this source code.
+ */
+
+use Eventum\RPC\XmlRpcException;
+
+class Eventum_RPC_Exception extends XmlRpcException
+{
+}
diff --git a/src/Eventum_RPC.php b/src/XmlRpcClient.php
similarity index 91%
rename from src/Eventum_RPC.php
rename to src/XmlRpcClient.php
index a8e8e91..ca430e6 100644
--- a/src/Eventum_RPC.php
+++ b/src/XmlRpcClient.php
@@ -11,11 +11,11 @@
  * that were distributed with this source code.
  */
 
-class Eventum_RPC_Exception extends Exception
-{
-}
+namespace Eventum\RPC;
+
+use PhpXmlRpc;
 
-class Eventum_RPC
+class XmlRpcClient
 {
     const VERSION = '4.1.1';
 
@@ -70,7 +70,7 @@ public function encodeBinary($value)
      * @param string $method
      * @param array $args
      * @return mixed
-     * @throws Eventum_RPC_Exception
+     * @throws XmlRpcException
      */
     public function __call($method, $args = array())
     {
@@ -94,10 +94,10 @@ public function __call($method, $args = array())
         $result = $this->client->send($req);
 
         if ($result === 0) {
-            throw new Eventum_RPC_Exception($this->client->errstr);
+            throw new XmlRpcException($this->client->errstr);
         }
         if (is_object($result) && $result->faultCode()) {
-            throw new Eventum_RPC_Exception($result->faultString());
+            throw new XmlRpcException($result->faultString(), $result->faultCode());
         }
 
         return $this->encoder->decode($result->value());
diff --git a/src/XmlRpcException.php b/src/XmlRpcException.php
new file mode 100644
index 0000000..23be46a
--- /dev/null
+++ b/src/XmlRpcException.php
@@ -0,0 +1,20 @@
+<?php
+
+/*
+ * This file is part of the Eventum (Issue Tracking System) package.
+ *
+ * @copyright (c) Eventum Team
+ * @license GNU General Public License, version 2 or later (GPL-2+)
+ *
+ * For the full copyright and license information,
+ * please see the COPYING and AUTHORS files
+ * that were distributed with this source code.
+ */
+
+namespace Eventum\RPC;
+
+use RuntimeException;
+
+class XmlRpcException extends RuntimeException
+{
+}

From 9607ddd4e9356cb8dba6c4debd9ba8b4fc4963e7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Elan=20Ruusam=C3=A4e?= <glen@delfi.ee>
Date: Tue, 1 May 2018 09:15:11 +0300
Subject: [PATCH 2/4] swap exception stacking

test that both exception classes can be catched
---
 lib/Eventum_RPC.php           |  3 +++
 lib/Eventum_RPC_Exception.php |  7 ++++---
 src/XmlRpcClient.php          |  2 +-
 src/XmlRpcException.php       |  4 ++--
 tests/ClientTest.php          | 20 ++++++++++++++++++++
 5 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/lib/Eventum_RPC.php b/lib/Eventum_RPC.php
index 71f2571..98f0161 100644
--- a/lib/Eventum_RPC.php
+++ b/lib/Eventum_RPC.php
@@ -13,6 +13,9 @@
 
 use Eventum\RPC\XmlRpcClient;
 
+/**
+ * @deprecated since 4.2.0, use \Eventum\RPC\XmlRpcClient
+ */
 class Eventum_RPC extends XmlRpcClient
 {
 }
diff --git a/lib/Eventum_RPC_Exception.php b/lib/Eventum_RPC_Exception.php
index b222cef..576b0f8 100644
--- a/lib/Eventum_RPC_Exception.php
+++ b/lib/Eventum_RPC_Exception.php
@@ -11,8 +11,9 @@
  * that were distributed with this source code.
  */
 
-use Eventum\RPC\XmlRpcException;
-
-class Eventum_RPC_Exception extends XmlRpcException
+/**
+ * @deprecated since 4.2.0, use \Eventum\RPC\XmlRpcException instead
+ */
+class Eventum_RPC_Exception extends RuntimeException
 {
 }
diff --git a/src/XmlRpcClient.php b/src/XmlRpcClient.php
index ca430e6..566965e 100644
--- a/src/XmlRpcClient.php
+++ b/src/XmlRpcClient.php
@@ -17,7 +17,7 @@
 
 class XmlRpcClient
 {
-    const VERSION = '4.1.1';
+    const VERSION = '4.2.0';
 
     /** @var PhpXmlRpc\Client */
     private $client;
diff --git a/src/XmlRpcException.php b/src/XmlRpcException.php
index 23be46a..13e7931 100644
--- a/src/XmlRpcException.php
+++ b/src/XmlRpcException.php
@@ -13,8 +13,8 @@
 
 namespace Eventum\RPC;
 
-use RuntimeException;
+use Eventum_RPC_Exception;
 
-class XmlRpcException extends RuntimeException
+class XmlRpcException extends Eventum_RPC_Exception
 {
 }
diff --git a/tests/ClientTest.php b/tests/ClientTest.php
index f7c9ddb..936e033 100644
--- a/tests/ClientTest.php
+++ b/tests/ClientTest.php
@@ -13,7 +13,9 @@
 
 namespace Eventum\RPC\Test;
 
+use Eventum\RPC\XmlRpcException;
 use Eventum_RPC;
+use Eventum_RPC_Exception;
 
 class ClientTest extends TestCase
 {
@@ -40,5 +42,23 @@ public function testRequest()
         $client = new Eventum_RPC($url);
         $methods = $client->__call($method);
         $this->assertContains($method, $methods);
+
+        // test  that legacy exception class is catchable
+        try {
+            $client->unknownMethod($method);
+            $this->fail('Exception not thrown');
+        } catch (Eventum_RPC_Exception $e) {
+            $this->assertEquals('Unknown method', $e->getMessage());
+            $this->assertEquals(1, $e->getCode());
+        }
+
+        // test that new exception class is catchable
+        try {
+            $client->unknownMethod($method);
+            $this->fail('Exception not thrown');
+        } catch (XmlRpcException $e) {
+            $this->assertEquals('Unknown method', $e->getMessage());
+            $this->assertEquals(1, $e->getCode());
+        }
     }
 }

From 857d7e7581aa03574432c9391be79ab586a27397 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Elan=20Ruusam=C3=A4e?= <glen@delfi.ee>
Date: Tue, 1 May 2018 09:18:29 +0300
Subject: [PATCH 3/4] add EventumXmlRpcClient with method annotations

---
 XMLRPC.md                   | 11 ++++---
 lib/Eventum_RPC.php         |  6 ++--
 src/EventumXmlRpcClient.php | 60 +++++++++++++++++++++++++++++++++++++
 3 files changed, 70 insertions(+), 7 deletions(-)
 create mode 100644 src/EventumXmlRpcClient.php

diff --git a/XMLRPC.md b/XMLRPC.md
index ec972ef..95d3894 100644
--- a/XMLRPC.md
+++ b/XMLRPC.md
@@ -1,10 +1,10 @@
 ## Available XMLRPC methods ##
 
-Here are available XMLRPC methods in [Eventum](https://github.com/eventum/eventum) as of version 3.0.2.
+Here are available XMLRPC methods in [Eventum](https://github.com/eventum/eventum) as of version 3.4.0.
 The methods themselves are defined in [RemoteApi](https://github.com/eventum/eventum/blob/master/lib/eventum/rpc/RemoteApi.php) class in Eventum codebase.
 This output is created with Eventum [CLI](https://github.com/eventum/cli) application [DumpMethods](https://github.com/eventum/cli/blob/master/src/Command/DumpMethodsCommand.php) command.
 
-Methods marked `@access public` do not require authentication, while `@access restricted` (default) require that you either use `setCredentials` to pass authentication credentials, or put `login` and `password` as first two parameters for the call.
+Methods marked `@access public` do not require authentication, while `@access protected` (default) require that you either use `setCredentials` to pass authentication credentials, or put `login` and `password` as first two parameters for the call.
 
 ```php
     /**
@@ -57,6 +57,7 @@ Methods marked `@access public` do not require authentication, while `@access re
      * @param string $note
      * @return string
      * @access protected
+     * @since 3.3.0 checks user access and issue close state
      */
     function closeIssue(int, string, int, boolean, string): string
 
@@ -231,11 +232,11 @@ Methods marked `@access public` do not require authentication, while `@access re
      * @param DateTime $start
      * @param DateTime $end
      * @param struct $options
-     * @return string
+     * @return struct
      * @access protected
      * @since 3.0.2
      */
-    function getWeeklyReportData(int, string, string, struct): string
+    function getWeeklyReportData(int, string, string, struct): struct
 
     /**
      * @param string $email
@@ -249,6 +250,7 @@ Methods marked `@access public` do not require authentication, while `@access re
      * @param string $command
      * @return string
      * @access protected
+     * @deprecated since 3.3.0 this method does nothing
      */
     function logCommand(string): string
 
@@ -328,3 +330,4 @@ Methods marked `@access public` do not require authentication, while `@access re
      * @access protected
      */
     function unredeemIssue(int, array): string
+```
diff --git a/lib/Eventum_RPC.php b/lib/Eventum_RPC.php
index 98f0161..abc4439 100644
--- a/lib/Eventum_RPC.php
+++ b/lib/Eventum_RPC.php
@@ -11,11 +11,11 @@
  * that were distributed with this source code.
  */
 
-use Eventum\RPC\XmlRpcClient;
+use Eventum\RPC\EventumXmlRpcClient;
 
 /**
- * @deprecated since 4.2.0, use \Eventum\RPC\XmlRpcClient
+ * @deprecated since 4.2.0, use \Eventum\RPC\EventumXmlRpcClient
  */
-class Eventum_RPC extends XmlRpcClient
+class Eventum_RPC extends EventumXmlRpcClient
 {
 }
diff --git a/src/EventumXmlRpcClient.php b/src/EventumXmlRpcClient.php
new file mode 100644
index 0000000..25dc334
--- /dev/null
+++ b/src/EventumXmlRpcClient.php
@@ -0,0 +1,60 @@
+<?php
+
+/*
+ * This file is part of the Eventum (Issue Tracking System) package.
+ *
+ * @copyright (c) Eventum Team
+ * @license GNU General Public License, version 2 or later (GPL-2+)
+ *
+ * For the full copyright and license information,
+ * please see the COPYING and AUTHORS files
+ * that were distributed with this source code.
+ */
+
+namespace Eventum\RPC;
+
+use DateTime;
+
+/**
+ * @method string addAuthorizedReplier(int $issue_id, int $project_id, string $new_replier)
+ * @method struct addFile(int $issue_id, string $filename, string $mimetype, base64 $contents, string $file_description, bool $internal_only)
+ * @method string assignIssue(int $issue_id, int $project_id, string $developer)
+ * @method boolean checkAuthentication()
+ * @method string closeIssue(int $issue_id, string $new_status, int $resolution_id, bool $send_notification, string $note)
+ * @method string convertNote(int $issue_id, int $note_id, string $target, bool $authorize_sender)
+ * @method struct getAbbreviationAssocList(int $prj_id, bool $show_closed)
+ * @method struct getClosedAbbreviationAssocList(int $prj_id)
+ * @method struct getDeveloperList(int $prj_id)
+ * @method struct getDraft(int $issue_id, int $draft_id)
+ * @method array getDraftListing(int $issue_id)
+ * @method array getEmail(int $issue_id, int $email_id)
+ * @method array getEmailListing(int $issue_id)
+ * @method struct getFile(int $file_id)
+ * @method array getFileList(int $issue_id)
+ * @method array getIncidentTypes(int $issue_id, bool $redeemed_only)
+ * @method struct getIssueDetails(int $issue_id)
+ * @method array getNote(int $issue_id, int $note_id)
+ * @method array getNoteListing(int $issue_id)
+ * @method array getOpenIssues(int $prj_id, bool $show_all_issues, string $status)
+ * @method array getResolutionAssocList()
+ * @method string getServerParameter(string $parameter)
+ * @method struct getSimpleIssueDetails(int $issue_id)
+ * @method struct getTimeTrackingCategories(int $issue_id)
+ * @method array getUserAssignedProjects(bool $only_customer_projects)
+ * @method string getWeeklyReport(int $week, string $start, string $end, bool $separate_closed, int $prj_id)
+ * @method struct getWeeklyReportData(int $prj_id, DateTime $start, DateTime $end, struct $options)
+ * @method boolean isValidLogin(string $email, string $password)
+ * @method string logCommand(string $command)
+ * @method string lookupCustomer(int $prj_id, string $field, string $value)
+ * @method string mayChangeIssue(int $issue_id)
+ * @method string recordTimeWorked(int $issue_id, int $cat_id, string $summary, int $time_spent)
+ * @method string redeemIssue(int $issue_id, array $types)
+ * @method string sendDraft(int $issue_id, int $draft_id)
+ * @method string setIssueStatus(int $issue_id, string $new_status)
+ * @method string takeIssue(int $issue_id, int $project_id)
+ * @method string timeClock(string $action)
+ * @method string unredeemIssue(int $issue_id, array $types)
+ */
+class EventumXmlRpcClient extends XmlRpcClient
+{
+}

From fedfb2db1be4637c179a9bcf5a9f76b1da1af51a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Elan=20Ruusam=C3=A4e?= <glen@delfi.ee>
Date: Tue, 1 May 2018 09:24:01 +0300
Subject: [PATCH 4/4] update changelog/doc

---
 CHANGELOG.md | 8 ++++++++
 README.md    | 9 ++++-----
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5c3d5c5..e3f3a7b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Eventum RPC Client Library
 
+## [4.2.0] - 2018-05-01
+
+- Move classes to `Eventum\RPC` namespace, deprecate root namespace [#4]
+- Update xmlrpc methods doc, include `@method` annotation, [#4]
+
+[4.2.0]: https://github.com/eventum/rpc/compare/v4.1.1...v4.2.0
+[#4]: https://github.com/eventum/rpc/pull/4
+
 ## [4.1.1] - 2017-10-15
 
 - add `addUserAgent` method for public access
diff --git a/README.md b/README.md
index 4551d1d..d999cba 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,4 @@
-eventum-rpc
-===========
+# Eventum RPC
 
 Eventum RPC Client Library.
 
@@ -46,18 +45,18 @@ require __DIR__ . '/vendor/autoload.php';
 require __DIR__ . '/vendor/autoload.php';
 
 $rpc_url = "http://example.org/rpc/xmlrpc.php";
-$client = new Eventum_RPC($rpc_url);
+$client = new \Eventum\RPC\EventumXmlRpcClient($rpc_url);
 $client->setCredentials("user@example.org", "password");
 
 // add user@example.org as authorized replier in issue $issue_id belonging to project $project_id
 $client->addAuthorizedReplier($issue_id, $project_id, "user@example.org");
 ```
 
-The available XMLRPC Methods can be seen from [here](XMLRPC.md).
+The available XMLRPC Methods can also be seen from [XMLRPC.md](XMLRPC.md).
 
 ## Copyright and License ##
 
-This software is Copyright (c) 2008 - 2017 Eventum Team.
+This software is Copyright (c) 2008 - 2018 Eventum Team.
 
 This is free software, licensed under the GNU General Public License
 version 2.