API client class v1.1.90

- remove existing x-csrf-token headers before adding a new one, UniFi OS does not like multiple x-csrf-tokens in the same request

src/Client.php

@@ -13,7 +13,7 @@ namespace UniFi_API;
  *
  * @package UniFi_Controller_API_Client_Class
  * @author  Art of WiFi <info@artofwifi.net>
- * @version Release: 1.1.87
+ * @version Release: 1.1.90
  * @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
@@ -21,11 +21,11 @@ namespace UniFi_API;
 class Client
 {
     /**
-     * private and protected properties
+     * protected properties
      *
-     * NOTE: do **not** modify the values here, instead use the constructor or the getter and setter functions/methods
+     * NOTE: do **not** modify the values below, instead use the constructor or the getter and setter functions/methods
      */
-    const CLASS_VERSION = '1.1.87';
+    const CLASS_VERSION = '1.1.90';
     protected string $baseurl              = 'https://127.0.0.1:8443';
     protected string $user                 = '';
     protected string $password             = '';
@@ -69,7 +69,15 @@ class Client
      *                                 This is only needed when you have multiple apps using the API on the same web
      *                                 server.
      */
-    public function __construct(string $user, string $password, string $baseurl = '', string $site = null, string $version = null, bool $ssl_verify = false, string $unificookie_name = 'unificookie')
+    public function __construct(
+        string $user,
+        string $password,
+        string $baseurl = '',
+        string $site = null,
+        string $version = null,
+        bool   $ssl_verify = false,
+        string $unificookie_name = 'unificookie'
+    )
     {
         if (!extension_loaded('curl')) {
             trigger_error('The PHP curl extension is not loaded. Please correct this before proceeding!');
@@ -108,7 +116,7 @@ class Client
     public function __destruct()
     {
         /**
-         * if $_SESSION[$this->unificookie_name] is set, do not log out here except when this is a UniFi OS-based controller
+         * if $_SESSION[$this->unificookie_name] is set, do not log out here
          */
         if (isset($_SESSION[$this->unificookie_name])) {
             return;
@@ -125,7 +133,9 @@ class Client
     /**
      * Login to the UniFi controller
      *
-     * @return bool|int returns true upon success, false or HTTP status upon error
+     * @return bool|int returns true upon success, false or the HTTP response code (typically 400, 401, or 403) upon
+     *                  error
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses
      */
     public function login()
     {
@@ -168,11 +178,7 @@ class Client
         $curl_options = [
             CURLOPT_POST       => true,
             CURLOPT_POSTFIELDS => json_encode(['username' => $this->user, 'password' => $this->password]),
-            CURLOPT_HTTPHEADER => [
+            CURLOPT_HTTPHEADER => $this->curl_headers,
-                'accept: application/json',
-                'content-type: application/json',
-                'Expect:',
-            ],
             CURLOPT_REFERER    => $this->baseurl . '/login',
             CURLOPT_URL        => $this->baseurl . '/api/login',
         ];
@@ -210,7 +216,7 @@ class Client
         /**
          * based on the HTTP response code trigger an error
          */
-        if ($http_code === 400 || $http_code === 401) {
+        if ($http_code >= 400) {
             trigger_error("HTTP response status received: $http_code. Probably a controller login failure");
 
             return $http_code;
@@ -221,8 +227,9 @@ class Client
         /**
          * check the HTTP response code
          */
-        if ($http_code >= 200 && $http_code < 400) {
+        if ($http_code >= 200) {
             $this->is_logged_in = true;
+
             return $this->is_logged_in;
         }
 
@@ -401,9 +408,17 @@ class Client
      * @return array|bool returns an array with a single object containing details of the new user/client-device on
      *                    success, else returns false
      */
-    public function create_user(string $mac, string $user_group_id, string $name = null, string $note = null, bool $is_guest = null, bool $is_wired = null)
+    public function create_user(
+        string $mac,
+        string $user_group_id,
+        string $name = null,
+        string $note = null,
+        bool   $is_guest = null,
+        bool   $is_wired = null
+    )
     {
         $new_user = ['mac' => strtolower($mac), 'usergroup_id' => $user_group_id];
+
         if (!empty($name)) {
             $new_user['name'] = $name;
         }
@@ -1117,6 +1132,19 @@ class Client
         return $this->fetch_results('/api/s/' . $this->site . '/stat/user/' . strtolower(trim($client_mac)));
     }
 
+    /**
+     * Fetch fingerprints for client devices
+     *
+     * @param int $fingerprint_source the id of the client fingerprint_source, starts from 0, this matches the
+     *                                fingerprint_source in the client device objects, the default value is 0
+     * @return array|bool an array of fingerprints, contain dev_ids, dev_type_ids, family_ids, os_name_ids, os_class_ids
+     *                    and vendor_ids, false upon error
+     */
+    public function list_fingerprint_devices(int $fingerprint_source = 0)
+    {
+        return $this->fetch_results('/v2/api/fingerprint_devices/' . $fingerprint_source);
+    }
+
     /**
      * Assign client device to another group
      *
@@ -1483,6 +1511,74 @@ class Client
         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
      *
@@ -1492,6 +1588,7 @@ class Client
     public function list_rogueaps(int $within = 24)
     {
         $payload = ['within' => $within];
+
         return $this->fetch_results('/api/s/' . $this->site . '/stat/rogueap', $payload);
     }
 
@@ -4011,6 +4108,15 @@ class Client
                 return;
             }
 
+            /**
+             * remove any existing x-csrf-token headers first
+             */
+            foreach ($this->curl_headers as $index => $header) {
+                if (strpos(strtolower($header), strtolower('x-csrf-token:')) !== false) {
+                    unset($this->curl_headers[$index]);
+                }
+            }
+
             $this->curl_headers[] = 'x-csrf-token: ' . json_decode(base64_decode($jwt_components[1]))->csrfToken;
         }
     }