From 7b94eadf81b9a271d8bf6203ec57a4be0deac00f Mon Sep 17 00:00:00 2001
From: Art4 <art4@wlabs.de>
Date: Wed, 10 Jul 2024 12:54:19 +0200
Subject: [PATCH 1/4] Improve code examples in docs

---
 docs/usage.md | 171 +++++++++++++++++++++++++++++++-------------------
 1 file changed, 106 insertions(+), 65 deletions(-)

diff --git a/docs/usage.md b/docs/usage.md
index cb1e70ef..6d199083 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -223,20 +223,26 @@ You can now use the `getApi()` method to create and get a specific Redmine API.
 
 To check for failed requests you can afterwards check the status code via `$client->getLastResponseStatusCode()`.
 
+#### Tracker API
+
 ```php
-// ----------------------------
-// Trackers
+
 $client->getApi('tracker')->list();
 $client->getApi('tracker')->listing();
+```
 
-// ----------------------------
-// Issue statuses
+#### IssueStatus API
+
+```php
 $client->getApi('issue_status')->list();
 $client->getApi('issue_status')->listing();
 $client->getApi('issue_status')->getIdByName('New');
 
-// ----------------------------
-// Project
+```
+
+#### Project API
+
+```php
 $client->getApi('project')->list();
 $client->getApi('project')->list([
     'limit' => 10,
@@ -258,9 +264,11 @@ $client->getApi('project')->reopen($projectId);
 $client->getApi('project')->archive($projectId);
 $client->getApi('project')->unarchive($projectId);
 $client->getApi('project')->remove($projectId);
+```
 
-// ----------------------------
-// Users
+#### User API
+
+```php
 $client->getApi('user')->list();
 $client->getApi('user')->listing();
 $client->getApi('user')->getCurrentUser([
@@ -290,9 +298,11 @@ $client->getApi('user')->create([
     'lastname' => 'test',
     'mail' => 'test@example.com',
 ]);
+```
 
-// ----------------------------
-// Issues
+#### Issue API
+
+```php
 $client->getApi('issue')->show($issueId);
 $client->getApi('issue')->list([
     'limit' => 100,
@@ -377,8 +387,39 @@ $client->getApi('issue')->create([
     ],
 ]);
 
-// ----------------------------
-// Issue categories
+// Issues' stats (see https://github.com/kbsali/php-redmine-api/issues/44)
+$issues['all'] = $client->getApi('issue')->list([
+    'limit' => 1,
+    'tracker_id' => 1,
+    'status_id' => '*',
+])['total_count'];
+
+$issues['opened'] = $client->getApi('issue')->list([
+    'limit' => 1,
+    'tracker_id' => 1,
+    'status_id' => 'open',
+])['total_count'];
+
+$issues['closed'] = $client->getApi('issue')->list([
+    'limit' => 1,
+    'tracker_id' => 1,
+    'status_id' => 'closed',
+])['total_count'];
+
+print_r($issues);
+/*
+Array
+(
+    [all] => 8
+    [opened] => 7
+    [closed] => 1
+)
+*/
+```
+
+#### IssueCategory API
+
+```php
 $client->getApi('issue_category')->listByProject('project1');
 $client->getApi('issue_category')->listing($projectId);
 $client->getApi('issue_category')->show($categoryId);
@@ -393,9 +434,11 @@ $client->getApi('issue_category')->remove($categoryId);
 $client->getApi('issue_category')->remove($categoryId, [
     'reassign_to_id' => $userId,
 ]);
+```
 
-// ----------------------------
-// Versions
+#### Version API
+
+```php
 $client->getApi('version')->listByProject('test');
 $client->getApi('version')->listing('test');
 $client->getApi('version')->show($versionId);
@@ -407,31 +450,41 @@ $client->getApi('version')->update($versionId, [
     'name' => 'v1121',
 ]);
 $client->getApi('version')->remove($versionId);
+```
 
-// ----------------------------
-// Attachments
+#### Attachment API
+
+```php
 $client->getApi('attachment')->show($attachmentId);
 
 $file_content = $client->getApi('attachment')->download($attachmentId);
 file_put_contents('example.png', $file_content);
+```
 
-// ----------------------------
-// News
+#### News API
+
+```php
 $client->getApi('news')->list();
 $client->getApi('news')->listByProject('test');
+```
 
-// ----------------------------
-// Roles
+#### Role API
+
+```php
 $client->getApi('role')->list();
 $client->getApi('role')->show(1);
 $client->getApi('role')->listing();
+```
 
-// ----------------------------
-// Queries
+#### Query API
+
+```php
 $client->getApi('query')->list();
+```
 
-// ----------------------------
-// Time entries
+#### TimeEntry API
+
+```php
 $client->getApi('time_entry')->list();
 $client->getApi('time_entry')->show($timeEntryId);
 $client->getApi('time_entry')->list([
@@ -471,19 +524,25 @@ $client->getApi('time_entry')->update($timeEntryId, [
     ],
 ]);
 $client->getApi('time_entry')->remove($timeEntryId);
+```
 
-// ----------------------------
-// Time entry activities
+#### TimeEntryActivity API
+
+```php
 $client->getApi('time_entry_activity')->list();
+```
 
-// ----------------------------
-// Issue relations
+#### IssueRelation API
+
+```php
 $client->getApi('issue_relation')->listByIssueId($issueId);
 $client->getApi('issue_relation')->show($issueRelationId);
 $client->getApi('issue_relation')->remove($issueRelationId);
+```
 
-// ----------------------------
-// Group (of members)
+#### Group of members API
+
+```php
 $client->getApi('group')->list();
 $client->getApi('group')->listing();
 $client->getApi('group')->show($groupId, ['include' => 'users,memberships']);
@@ -513,22 +572,28 @@ $client->getApi('group')->update($groupId, [
         ],
     ],
 ]);
+```
 
-// ----------------------------
-// Project memberships
+#### Project Membership API
+
+```php
 $client->getApi('membership')->listByProject($projectId);
 $client->getApi('membership')->create($projectId, [
     'user_id' => 1,
     'role_ids' => [5],
 ]);
 $client->getApi('membership')->remove($membershipId);
+```
 
-// ----------------------------
-// Issue priorities
+#### IssuePriority API
+
+```php
 $client->getApi('issue_priority')->list();
+```
 
-// ----------------------------
-// Wiki
+#### Wiki API
+
+```php
 $client->getApi('wiki')->listByProject('testProject');
 $client->getApi('wiki')->show('testProject', 'about');
 $client->getApi('wiki')->show('testProject', 'about', $version);
@@ -543,42 +608,18 @@ $client->getApi('wiki')->update('testProject', 'about', [
     'version' => null,
 ]);
 $client->getApi('wiki')->remove('testProject', 'about');
+```
 
-// ----------------------------
-// Issues' stats (see https://github.com/kbsali/php-redmine-api/issues/44)
-$issues['all'] = $client->getApi('issue')->list([
-    'limit' => 1,
-    'tracker_id' => 1,
-    'status_id' => '*',
-])['total_count'];
-
-$issues['opened'] = $client->getApi('issue')->list([
-    'limit' => 1,
-    'tracker_id' => 1,
-    'status_id' => 'open',
-])['total_count'];
-
-$issues['closed'] = $client->getApi('issue')->list([
-    'limit' => 1,
-    'tracker_id' => 1,
-    'status_id' => 'closed',
-])['total_count'];
-
-print_r($issues);
-/*
-Array
-(
-    [all] => 8
-    [opened] => 7
-    [closed] => 1
-)
-*/
+#### Search API
 
+```php
 // ----------------------------
 // Search
 $client->getApi('search')->search('Myproject', ['limit' => 100]);
 ```
 
+#### CustomField API
+
 #### API entry points implementation state:
 
 * :heavy_check_mark: Attachments

From 0af775a181e2ac7013e1ef24633efab0eaa8ba8b Mon Sep 17 00:00:00 2001
From: Art4 <art4@wlabs.de>
Date: Wed, 10 Jul 2024 13:23:39 +0200
Subject: [PATCH 2/4] Update code examples in docs

---
 docs/usage.md | 52 ++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 35 insertions(+), 17 deletions(-)

diff --git a/docs/usage.md b/docs/usage.md
index 6d199083..e8cbf5f1 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -228,15 +228,14 @@ To check for failed requests you can afterwards check the status code via `$clie
 ```php
 
 $client->getApi('tracker')->list();
-$client->getApi('tracker')->listing();
+$client->getApi('tracker')->listNames();
 ```
 
 #### IssueStatus API
 
 ```php
 $client->getApi('issue_status')->list();
-$client->getApi('issue_status')->listing();
-$client->getApi('issue_status')->getIdByName('New');
+$client->getApi('issue_status')->listNames();
 
 ```
 
@@ -247,10 +246,8 @@ $client->getApi('project')->list();
 $client->getApi('project')->list([
     'limit' => 10,
 ]);
-$client->getApi('project')->listing();
-$client->getApi('project')->listing();
+$client->getApi('project')->listNames();
 $client->getApi('project')->show($projectId);
-$client->getApi('project')->getIdByName('Elvis');
 $client->getApi('project')->create([
     'name' => 'some name',
     'identifier' => 'the_identifier',
@@ -270,7 +267,7 @@ $client->getApi('project')->remove($projectId);
 
 ```php
 $client->getApi('user')->list();
-$client->getApi('user')->listing();
+$client->getApi('user')->listLogins();
 $client->getApi('user')->getCurrentUser([
     'include' => [
         'memberships',
@@ -279,7 +276,6 @@ $client->getApi('user')->getCurrentUser([
         'status',
     ],
 ]);
-$client->getApi('user')->getIdByUsername('kbsali');
 $client->getApi('user')->show($userId, [
     'include' => [
         'memberships',
@@ -358,8 +354,11 @@ $client->getApi('issue')->update($issueId, [
     'priority_id' => 5,
     'due_date' => date('Y-m-d'),
 ]);
+$client->getApi('issue')->addWatcher($issueId, $userId);
+$client->getApi('issue')->removeWatcher($issueId, $userId);
 $client->getApi('issue')->setIssueStatus($issueId, 'Resolved');
 $client->getApi('issue')->addNoteToIssue($issueId, 'some comment');
+$client->getApi('issue')->addNoteToIssue($issueId, 'private note', true);
 $client->getApi('issue')->remove($issueId);
 
 // To upload a file + attach it to an existing issue with $issueId
@@ -421,9 +420,8 @@ Array
 
 ```php
 $client->getApi('issue_category')->listByProject('project1');
-$client->getApi('issue_category')->listing($projectId);
+$client->getApi('issue_category')->listNamesByProject($projectId);
 $client->getApi('issue_category')->show($categoryId);
-$client->getApi('issue_category')->getIdByName($projectId, 'Administration');
 $client->getApi('issue_category')->create('otherProject', [
     'name' => 'test category',
 ]);
@@ -440,9 +438,8 @@ $client->getApi('issue_category')->remove($categoryId, [
 
 ```php
 $client->getApi('version')->listByProject('test');
-$client->getApi('version')->listing('test');
+$client->getApi('version')->listNamesByProject('test');
 $client->getApi('version')->show($versionId);
-$client->getApi('version')->getIdByName('test', 'v2');
 $client->getApi('version')->create('test', [
     'name' => 'v3432',
 ]);
@@ -456,9 +453,17 @@ $client->getApi('version')->remove($versionId);
 
 ```php
 $client->getApi('attachment')->show($attachmentId);
+$client->getApi('attachment')->upload(file_get_contents('example.png'), [
+    'filename' => 'example.png',
+]);
+$client->getApi('attachment')->update($attachmentId, [
+    'filename' => 'example.png',
+]);
 
 $file_content = $client->getApi('attachment')->download($attachmentId);
 file_put_contents('example.png', $file_content);
+
+$client->getApi('attachment')->remove($attachmentId);
 ```
 
 #### News API
@@ -472,8 +477,8 @@ $client->getApi('news')->listByProject('test');
 
 ```php
 $client->getApi('role')->list();
+$client->getApi('role')->listNames();
 $client->getApi('role')->show(1);
-$client->getApi('role')->listing();
 ```
 
 #### Query API
@@ -530,6 +535,7 @@ $client->getApi('time_entry')->remove($timeEntryId);
 
 ```php
 $client->getApi('time_entry_activity')->list();
+$client->getApi('time_entry_activity')->listNames();
 ```
 
 #### IssueRelation API
@@ -537,6 +543,10 @@ $client->getApi('time_entry_activity')->list();
 ```php
 $client->getApi('issue_relation')->listByIssueId($issueId);
 $client->getApi('issue_relation')->show($issueRelationId);
+$client->getApi('issue_relation')->create($issueId, [
+    'relation_type' => 'relates',
+    'issue_to_id' => $issueToId,
+]);
 $client->getApi('issue_relation')->remove($issueRelationId);
 ```
 
@@ -544,7 +554,7 @@ $client->getApi('issue_relation')->remove($issueRelationId);
 
 ```php
 $client->getApi('group')->list();
-$client->getApi('group')->listing();
+$client->getApi('group')->listNames();
 $client->getApi('group')->show($groupId, ['include' => 'users,memberships']);
 $client->getApi('group')->remove($groupId);
 $client->getApi('group')->addUser($groupId, $userId);
@@ -582,7 +592,12 @@ $client->getApi('membership')->create($projectId, [
     'user_id' => 1,
     'role_ids' => [5],
 ]);
+$client->getApi('membership')->update($membershipId, [
+    'user_id' => 1,
+    'role_ids' => [5],
+]);
 $client->getApi('membership')->remove($membershipId);
+$client->getApi('membership')->removeMember($projectId, $userId);
 ```
 
 #### IssuePriority API
@@ -613,13 +628,16 @@ $client->getApi('wiki')->remove('testProject', 'about');
 #### Search API
 
 ```php
-// ----------------------------
-// Search
-$client->getApi('search')->search('Myproject', ['limit' => 100]);
+$client->getApi('search')->listByQuery('search query', ['limit' => 100]);
 ```
 
 #### CustomField API
 
+```php
+$client->getApi('custom_field')->list();
+$client->getApi('custom_field')->listNames();
+```
+
 #### API entry points implementation state:
 
 * :heavy_check_mark: Attachments

From a1106faaec00637e786b693575fae9bb284e2c86 Mon Sep 17 00:00:00 2001
From: Art4 <art4@wlabs.de>
Date: Wed, 10 Jul 2024 13:24:04 +0200
Subject: [PATCH 3/4] Remove outdates implementation list

---
 docs/usage.md | 22 ----------------------
 1 file changed, 22 deletions(-)

diff --git a/docs/usage.md b/docs/usage.md
index e8cbf5f1..a2c3b6c7 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -638,28 +638,6 @@ $client->getApi('custom_field')->list();
 $client->getApi('custom_field')->listNames();
 ```
 
-#### API entry points implementation state:
-
-* :heavy_check_mark: Attachments
-* :heavy_check_mark: Groups
-* :heavy_check_mark: Custom Fields
-* :heavy_check_mark: Issues
-* :heavy_check_mark: Issue Categories
-* :heavy_check_mark: Issue Priorities
-* :x: *Issue Relations - only partially implemented*
-* :heavy_check_mark: Issue Statuses
-* :heavy_check_mark: News
-* :heavy_check_mark: Projects
-* :heavy_check_mark: Project Memberships
-* :heavy_check_mark: Queries
-* :heavy_check_mark: Roles
-* :heavy_check_mark: Time Entries
-* :heavy_check_mark: Time Entry Activities
-* :heavy_check_mark: Trackers
-* :heavy_check_mark: Users
-* :heavy_check_mark: Versions
-* :heavy_check_mark: Wiki
-
 If some features are missing in `getApi()` you are welcome to create a PR. Besides, it is always possible to use the low-level API.
 
 ### Low-level API

From 3a864ae45fcf99d01e3cbb57fd79876e4daf74a7 Mon Sep 17 00:00:00 2001
From: Art4 <art4@wlabs.de>
Date: Wed, 10 Jul 2024 13:25:00 +0200
Subject: [PATCH 4/4] Update README.md

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index bb604c92..ac6023c0 100644
--- a/README.md
+++ b/README.md
@@ -308,7 +308,7 @@ You can now use the `getApi()` method to create and get a specific Redmine API.
 <?php
 
 $client->getApi('user')->list();
-$client->getApi('user')->listing();
+$client->getApi('user')->listLogins();
 
 $client->getApi('issue')->create([
     'project_id'  => 'test',