From 007117cbfc6aa28c60e49b10f5b3e5997e15e589 Mon Sep 17 00:00:00 2001
From: malle-pietje <erik@slooff.net>
Date: Sun, 11 Feb 2024 17:24:31 +0100
Subject: [PATCH] API client class v1.1.89 - added `create_tag()`,
 `set_tagged_devices()`, `get_tag()`, and `delete_tag()` methods to manage
 tags, contributed by @brenard, #205

---
 src/Client.php | 75 ++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 72 insertions(+), 3 deletions(-)

diff --git a/src/Client.php b/src/Client.php
index 9fe933b..277a9ac 100755
--- a/src/Client.php
+++ b/src/Client.php
@@ -13,7 +13,7 @@
  *
  * @package UniFi_Controller_API_Client_Class
  * @author  Art of WiFi <info@artofwifi.net>
- * @version Release: 1.1.88
+ * @version Release: 1.1.89
  * @license This class is subject to the MIT license that is bundled with this package in the file LICENSE.md
  * @example This directory in the package repository contains a collection of examples:
  *          https://github.com/Art-of-WiFi/UniFi-API-client/tree/master/examples
@@ -25,7 +25,7 @@ class Client
      *
      * NOTE: do **not** modify the values below, instead use the constructor or the getter and setter functions/methods
      */
-    const CLASS_VERSION = '1.1.88';
+    const CLASS_VERSION = '1.1.89';
     protected string $baseurl              = 'https://127.0.0.1:8443';
     protected string $user                 = '';
     protected string $password             = '';
@@ -227,7 +227,7 @@ public function login()
         /**
          * check the HTTP response code
          */
-        if ($http_code >= 200 ) {
+        if ($http_code >= 200) {
             $this->is_logged_in = true;
 
             return $this->is_logged_in;
@@ -1511,6 +1511,74 @@ public function list_tags()
         return $this->fetch_results('/api/s/' . $this->site . '/rest/tag');
     }
 
+    /**
+     * Create (device) tag (using REST)
+     *
+     * NOTES: this endpoint was introduced with controller versions 5.5.X
+     *
+     * @param string $name required, the tag name to add
+     * @param array|null $devices_macs optional, array of the MAC address(es) of the device(s) to tag with the new tag
+     * @return bool return true on success
+     */
+    public function create_tag(string $name, array $devices_macs = null): bool
+    {
+        $payload = ['name' => $name];
+
+        if (is_array($devices_macs)) {
+            $payload['member_table'] = $devices_macs;
+        }
+
+        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/tag', $payload);
+    }
+
+    /**
+     * Set tagged devices (using REST)
+     *
+     * NOTES: this endpoint was introduced with controller versions 5.5.X
+     *
+     * @param array $devices_macs required, array of the MAC address(es) of the device(s) to tag
+     * @param string $tag_id required, the _id value of the tag to set
+     * @return bool return true on success
+     */
+    public function set_tagged_devices(array $devices_macs, string $tag_id): bool
+    {
+        $this->curl_method = 'PUT';
+
+        $payload = ['member_table' => $devices_macs];
+
+        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/tag/' . $tag_id, $payload);
+    }
+
+    /**
+     * Get (device) tag (using REST)
+     *
+     * NOTES: this endpoint was introduced with controller versions 5.5.X
+     *
+     * @param string $tag_id required, the _id value of the tag to retrieve
+     * @return array|bool containing matching tag objects
+     */
+    public function get_tag(string $tag_id)
+    {
+        $this->curl_method = 'GET';
+
+        return $this->fetch_results('/api/s/' . $this->site . '/rest/tag/' . $tag_id);
+    }
+
+    /**
+     * Delete (device) tag (using REST)
+     *
+     * NOTES: this endpoint was introduced with controller versions 5.5.X
+     *
+     * @param string $tag_id required, the _id value of the tag to set
+     * @return bool return true on success
+     */
+    public function delete_tag(string $tag_id): bool
+    {
+        $this->curl_method = 'DELETE';
+
+        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/tag/' . $tag_id);
+    }
+
     /**
      * Fetch rogue/neighboring access points
      *
@@ -1520,6 +1588,7 @@ public function list_tags()
     public function list_rogueaps(int $within = 24)
     {
         $payload = ['within' => $within];
+
         return $this->fetch_results('/api/s/' . $this->site . '/stat/rogueap', $payload);
     }