API client class v1.1.94

- minor fix based on Scrutinizer feedback
- re-added `update_admin()` method to the class; for some reason, the merge of #228 was not successful

src/Client.php

@@ -21,7 +21,7 @@ namespace UniFi_API;
 class Client
 {
     /** constants */
-    const CLASS_VERSION        = '1.1.93';
+    const CLASS_VERSION        = '1.1.94';
     const CURL_METHODS_ALLOWED = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
     const DEFAULT_CURL_METHOD  = 'GET';
 
@@ -31,11 +31,11 @@ class Client
      * @note do **not** directly edit the property values below, instead use the constructor or the respective
      *       getter and setter functions/methods
      */
-    protected string $baseurl              = 'https://127.0.0.1:8443';
+    protected string $baseurl              = '';
     protected string $user                 = '';
     protected string $password             = '';
-    protected string $site                 = 'default';
-    protected string $version              = '8.0.28';
+    protected string $site                 = '';
+    protected string $version              = '';
     protected bool   $debug                = false;
     protected bool   $is_logged_in         = false;
     protected bool   $is_unifi_os          = false;
@@ -63,22 +63,22 @@ class Client
      * @param string $password password to use when connecting to the UniFi controller
      * @param string $baseurl optional, base URL of the UniFi controller which *must* include an 'https://' prefix,
      *                        a port suffix (e.g. :8443) is required for non-UniFi OS controllers,
-     *                        do not add trailing slashes, default value is 'https://127.0.0.1:8443'
+     *                        do not add trailing slashes, defaults to 'https://127.0.0.1:8443'
      * @param string|null $site optional, short site name to access, defaults to 'default'
-     * @param string|null $version optional, the version number of the controller
+     * @param string|null $version optional, the version number of the controller, defaults to '8.0.28'
      * @param bool $ssl_verify optional, whether to validate the controller's SSL certificate or not, a value of true
-     *                         is recommended for production environments to prevent potential MitM attacks, default
-     *                         value (false) disables validation of the controller's SSL certificate
-     * @param string $unificookie_name optional, name of the cookie to use, default value is 'unificookie'.
-     *                                 This is only necessary when you have multiple apps using the API on the same web
-     *                                 server.
+     *                         is recommended for production environments to prevent potential MitM attacks, defaults
+     *                         to false which disables validation of the controller's SSL certificate
+     * @param string $unificookie_name optional, name of the cookie to use, defaults to 'unificookie'.
+     *                                 This is only necessary when you have multiple apps using this API client on the
+     *                                 same web server.
      */
     public function __construct(
         string $user,
         string $password,
-        string $baseurl = '',
-        string $site = null,
-        string $version = null,
+        string $baseurl = 'https://127.0.0.1:8443',
+        string $site = 'default',
+        string $version = '8.0.28',
         bool   $ssl_verify = false,
         string $unificookie_name = 'unificookie'
     )
@@ -87,23 +87,15 @@ class Client
             trigger_error('The PHP curl extension is not loaded. Please correct this before proceeding!');
         }
 
-        $this->unificookie_name = trim($unificookie_name);
+        $this->check_base_url($baseurl);
+        $this->check_site($site);
+
+        $this->baseurl          = trim($baseurl);
+        $this->site             = strtolower(trim($site));
         $this->user             = trim($user);
         $this->password         = trim($password);
-
-        if (!empty($baseurl)) {
-            $this->check_base_url($baseurl);
-            $this->baseurl = trim($baseurl);
-        }
-
-        if (!empty($site)) {
-            $this->check_site($site);
-            $this->site = trim($site);
-        }
-
-        if (!empty($version)) {
-            $this->version = trim($version);
-        }
+        $this->version          = trim($version);
+        $this->unificookie_name = trim($unificookie_name);
 
         if ($ssl_verify === true) {
             $this->curl_ssl_verify_peer = true;
@@ -133,9 +125,9 @@ class Client
     /**
      * Login to the UniFi controller
      *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses
      * @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()
     {
@@ -223,7 +215,7 @@ class Client
     /**
      * Logout from the UniFi controller
      *
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function logout(): bool
     {
@@ -278,7 +270,7 @@ class Client
      * @param int|null $megabytes optional, data transfer limit in MB
      * @param string|null $ap_mac optional, AP MAC address to which client is connected, should result in faster
      *                            authorization for the client device
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function authorize_guest(string $mac, int $minutes, int $up = null, int $down = null, int $megabytes = null, string $ap_mac = null): bool
     {
@@ -308,7 +300,7 @@ class Client
      * Unauthorize a client device
      *
      * @param string $mac client MAC address
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function unauthorize_guest(string $mac): bool
     {
@@ -321,7 +313,7 @@ class Client
      * Reconnect a client device
      *
      * @param string $mac client MAC address
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function reconnect_sta(string $mac): bool
     {
@@ -334,7 +326,7 @@ class Client
      * Block a client device
      *
      * @param string $mac client MAC address
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function block_sta(string $mac): bool
     {
@@ -347,7 +339,7 @@ class Client
      * Unblock a client device
      *
      * @param string $mac client MAC address
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function unblock_sta(string $mac): bool
     {
@@ -362,7 +354,7 @@ class Client
      * @note only supported with controller versions 5.9.X and higher, can be
      *       slow (up to 5 minutes) on larger controllers
      * @param array|string $mac array of client MAC addresses (strings) or a single MAC address string
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function forget_sta($mac): bool
     {
@@ -424,7 +416,7 @@ class Client
      *
      * @param string $user_id id of the client-device to be modified
      * @param string $note optional, note to be applied to the client-device
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function set_sta_note(string $user_id, string $note = ''): bool
     {
@@ -439,7 +431,7 @@ class Client
      * @param string $user_id id of the client-device to be modified
      * @param string $name optional, name to be applied to the client device, when empty or not set,
      *                        the existing name for the client device is removed
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function set_sta_name(string $user_id, string $name = ''): bool
     {
@@ -1082,11 +1074,11 @@ class Client
     }
 
     /**
-     * Assign client device to another group
+     * Assign a client device to another group
      *
      * @param string $client_id _id value of the client device to be modified
      * @param string $group_id _id value of the user group to assign client device to
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function set_usergroup(string $client_id, string $group_id): bool
     {
@@ -1096,7 +1088,7 @@ class Client
     }
 
     /**
-     * Update client device fixed IP address (using REST)
+     * Update a client device's fixed IP address (using REST)
      *
      * @param string $client_id _id value for the client device
      * @param bool $use_fixedip determines whether to enable the fixed IP address or not
@@ -1883,6 +1875,68 @@ class Client
         return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/sitemgr', $payload);
     }
 
+    /**
+     * Update an admin of the current site
+     *
+     * @param string $admin_id _id value of the admin user to update, can be obtained using the
+     *                         list_all_admins() method/function
+     * @param string $name update the name of the admin user
+     * @param string $email update the email address of the admin user
+     * @param string $password optionally update the password of the admin user
+     * @param bool $readonly optional, whether the new admin has readonly
+     *                       permissions, default value is false which gives the new admin
+     *                       Administrator permissions
+     * @param bool $device_adopt optional, whether the new admin has permissions to
+     *                           adopt devices, default value is false. With versions < 5.9.X this only applies
+     *                           when readonly is true.
+     * @param bool $device_restart optional, whether the new admin has permissions to
+     *                             restart devices, default value is false. With versions < 5.9.X this only applies
+     *                             when readonly is true.
+     * @return bool true on success
+     */
+    public function update_admin(
+        string $admin_id,
+        string $name,
+        string $email,
+        string $password = '',
+        bool   $readonly = false,
+        bool   $device_adopt = false,
+        bool   $device_restart = false
+    ): bool
+    {
+        $email       = trim($email);
+        $email_valid = filter_var($email, FILTER_VALIDATE_EMAIL);
+
+        if (!$email_valid) {
+            trigger_error('The email address provided is invalid!');
+            return false;
+        }
+
+        $payload = [
+            'admin'       => trim($admin_id),
+            'name'        => trim($name),
+            'email'       => $email,
+            'cmd'         => 'update-admin',
+            'role'        => 'admin',
+            'x_password'  => $password,
+            'permissions' => [],
+        ];
+
+        if ($readonly) {
+            $payload['role'] = 'readonly';
+        }
+
+        if ($device_adopt) {
+            $payload['permissions'][] = 'API_DEVICE_ADOPT';
+        }
+
+        if ($device_restart) {
+            $payload['permissions'][] = 'API_DEVICE_RESTART';
+        }
+
+        return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/sitemgr', $payload);
+    }
+
     /**
      * Revoke an admin from the current site
      *
@@ -3009,7 +3063,7 @@ class Client
      * Check firmware update
      *
      * @note triggers a Device Firmware Update in Classic Settings > System settings > Maintenance
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function check_firmware_update(): bool
     {
@@ -3023,7 +3077,7 @@ class Client
      *
      * @note updates the device to the latest STABLE firmware known to the controller
      * @param string $mac MAC address of the device to upgrade
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function upgrade_device(string $mac): bool
     {
@@ -3037,7 +3091,7 @@ class Client
      *
      * @note updates all devices of the selected type to the latest STABLE firmware known to the controller
      * @param string $type the type of devices to upgrade, must be one of "uap", "usw", "ugw". "uap" is the default.
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function upgrade_all_devices(string $type = 'uap'): bool
     {
@@ -3053,7 +3107,7 @@ class Client
      *       - please take great care to select a valid firmware file for the device!
      * @param string $firmware_url URL for the firmware file to upgrade the device to
      * @param string|array $macs MAC address of the device to upgrade or an array of MAC addresses
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function upgrade_device_external(string $firmware_url, $macs): bool
     {
@@ -3070,7 +3124,7 @@ class Client
      *
      * @note updates all UniFi devices to the latest firmware known to the controller in a
      *       staggered/rolling fashion
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function start_rolling_upgrade(): bool
     {
@@ -3080,7 +3134,7 @@ class Client
     /**
      * Cancel rolling upgrade.
      *
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function cancel_rolling_upgrade(): bool
     {
@@ -3114,7 +3168,7 @@ class Client
      *       - the port must be actually providing power
      * @param string $mac main MAC address of the switch
      * @param int $port_idx port number/index of the port to be affected
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function power_cycle_switch_port(string $mac, int $port_idx): bool
     {
@@ -3127,7 +3181,7 @@ class Client
      * Trigger an RF scan by an AP
      *
      * @param string $mac MAC address of the AP
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function spectrum_scan(string $mac): bool
     {
@@ -3358,7 +3412,7 @@ class Client
      * @param string $method optional, HTTP request type, can be GET (default), POST, PUT, PATCH, or DELETE
      * @param object|array|null $payload optional, stdClass object or associative array containing the payload to pass
      * @param string $return optional, string; determines how to return results, when "boolean" the method must
-     *                       return a boolean result (true/false) or "array" when the method must return an array
+     *                       return a boolean result or "array" when the method must return an array (default)
      * @return bool|array returns results as requested, returns false on incorrect parameters
      */
     public function custom_api_request(string $path, string $method = 'GET', $payload = null, string $return = 'array')
@@ -3375,7 +3429,9 @@ class Client
 
         if ($return === 'array') {
             return $this->fetch_results($path, $payload);
-        } elseif ($return === 'boolean') {
+        }
+
+        if ($return === 'boolean') {
             return $this->fetch_results_boolean($path, $payload);
         }
 
@@ -3392,9 +3448,9 @@ class Client
      *
      * @note changed function/method name to fit its purpose
      * @param string|null $mac optional, the MAC address of a single device for which the call must be made
-     * @return array containing known device objects (or a single device when using the <mac> parameter)
+     * @return array|bool containing known device objects (or a single device when using the <mac> parameter)
      */
-    public function list_aps(string $mac = null): array
+    public function list_aps(string $mac = null)
     {
         trigger_error(
             'Function list_aps() has been deprecated, use list_devices() instead.',
@@ -3497,7 +3553,6 @@ class Client
     public function set_site(string $site): string
     {
         $this->check_site($site);
-
         $this->site = trim($site);
 
         return $this->site;
@@ -3901,7 +3956,7 @@ class Client
     /**
      * Capture the latest JSON error when $this->debug is true
      *
-     * @return bool returns true upon success, false upon failure
+     * @return bool true upon success, false upon failure
      */
     protected function catch_json_last_error(): bool
     {