added ability top determine attributes to fetch with AP and site stats

general minor clean up
bumped version to 1.1.95

LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016, Art of WiFi
+Copyright (c) 2024, Art of WiFi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -2,8 +2,10 @@
 
 A PHP class that provides access to Ubiquiti's [**UniFi Network Application**](https://unifi-network.ui.com/) API.
 
-UniFi Network Application software versions 5.X.X, 6.X.X, 7.X.X, and 8.X.X (version **8.1.104** has been confirmed to work)
+UniFi Network Application software versions 5.X.X, 6.X.X, 7.X.X, and 8.X.X (version **8.5.2** has been confirmed to
-are supported as well as Network Applications on **UniFi OS-based consoles** (UniFi OS **3.2.12** has been confirmed to work).
+work) are supported as well as Network Applications on **UniFi OS-based consoles** (UniFi OS **4.0.20** has been
+confirmed to work).
+
 This class is used by our API Browser tool, which can be found
 [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
 
@@ -15,12 +17,13 @@ easy inclusion in your projects.
 ## Requirements
 
 - a server with:
-  - PHP **7.4.0** or higher (use version [1.1.83](https://github.com/Art-of-WiFi/UniFi-API-client/releases/tag/v1.1.83) for PHP 7.3.x and lower)
+  - PHP **7.4.0** or higher (use version [1.1.83](https://github.com/Art-of-WiFi/UniFi-API-client/releases/tag/v1.1.83) 
+    for PHP 7.3.x and lower)
   - PHP json and PHP cURL modules
-  - tested on Apache 2.4 with PHP 7.4.27 and cURL 7.60.0 and with PHP 8.2.12 and cURL 7.81.0
+  - tested on Apache 2.4 with PHP 7.4.27 and cURL 7.60.0 and with PHP 8.3.11 and cURL 7.81.0
 - direct network connectivity between this server and the host and port (usually TCP port 8443 or port 443 for 
   UniFi OS) where the UniFi Controller is running
-- you **must** use **accounts with local access permissions** to access the UniFi Controller API through this class
+- you **must** use an **account with local access permissions** to access the UniFi Controller API through this class
 - do not use UniFi Cloud accounts and do not enable 2FA for the accounts that you use with this class
 
 
@@ -34,16 +37,20 @@ Support for UniFi OS-based controllers has been added as of version 1.1.47. Thes
 - UniFi Cloud Key Gen2 Plus (UCK G2 Plus), firmware version 2.0.24 or higher
 - UniFi Cloud Console, details [here](https://help.ui.com/hc/en-us/articles/4415364143511)
 - UniFi Express (UX)
+- UniFi Dream Wall (UDW)
+- UniFi Cloud Gateway Ultra (UCG-Ultra)
+- UniFi Enterprise Fortress Gateway (EFG)
 
 The class automatically detects UniFi OS consoles and adjusts the URLs and several functions/methods accordingly.
 
-UniFi OS consoles require you to connect using port **443** instead of **8443** which is used for "software-based"
+UniFi OS-based controllers require you to connect using port **443** instead of **8443** which is used for
-controllers. If your own code implements strict validation of the URL that is passed to the constructor, please adapt
+"software-based" controllers. If your own code implements strict validation of the URL that is passed to the
-your logic to allow URLs without a port suffix or with port 443 when working with a UniFi OS-based controller.
+constructor, please adapt your logic to allow URLs without a port suffix or with port 443 when working with a
+UniFi OS-based controller.
 
 
 ### Remote API access to UniFi OS-based controllers
-When connecting to a UniFi OS gateway through the WAN interface, you need to create a specific firewall rule to
+When connecting to a UniFi OS-based gateway through the WAN interface, you need to create a specific firewall rule to
 allow this. See this blog post on the Art of WiFi website for more details:
 https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a-udm-pro
 

src/Client.php

@@ -3,7 +3,7 @@
 namespace UniFi_API;
 
 /**
- * The UniFi API client class
+ * The UniFi API client class.
  *
  * This UniFi API client class is based on the work done by the following developers:
  *    domwo: https://community.ui.com/questions/little-php-class-for-unifi-api/933d3fb3-b401-4499-993a-f9af079a4a3a
@@ -20,22 +20,22 @@ namespace UniFi_API;
  */
 class Client
 {
-    /** constants */
+    /** Constants. */
-    const CLASS_VERSION        = '1.1.93';
+    const CLASS_VERSION        = '1.1.95';
     const CURL_METHODS_ALLOWED = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
     const DEFAULT_CURL_METHOD  = 'GET';
 
     /**
-     * protected properties
+     * Protected properties.
      *
      * @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 $site                       = '';
-    protected string $version              = '8.0.28';
+    protected string $version                    = '';
     protected bool   $debug                      = false;
     protected bool   $is_logged_in               = false;
     protected bool   $is_unifi_os                = false;
@@ -55,6 +55,16 @@ class Client
         'Content-Type: application/json',
         'Expect:',
     ];
+    protected array  $default_site_stats_attribs = [
+        'bytes',
+        'wan-tx_bytes',
+        'wan-rx_bytes',
+        'wlan_bytes',
+        'num_sta',
+        'lan-num_sta',
+        'wlan-num_sta',
+        'time',
+    ];
 
     /**
      * Construct an instance of the UniFi API client class.
@@ -63,22 +73,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
+     *                         is recommended for production environments to prevent potential MitM attacks, defaults
-     *                         value (false) disables validation of the controller's SSL certificate
+     *                         to false which disables validation of the controller's SSL certificate
-     * @param string $unificookie_name optional, name of the cookie to use, default value is 'unificookie'.
+     * @param string $unificookie_name optional, name of the cookie to use, defaults to 'unificookie'.
-     *                                 This is only necessary when you have multiple apps using the API on the same web
+     *                                 This is only necessary when you have multiple apps using this API client on the
-     *                                 server.
+     *                                 same web server.
      */
     public function __construct(
         string $user,
         string $password,
-        string $baseurl = '',
+        string $baseurl = 'https://127.0.0.1:8443',
-        string $site = null,
+        string $site = 'default',
-        string $version = null,
+        string $version = '8.0.28',
         bool   $ssl_verify = false,
         string $unificookie_name = 'unificookie'
     )
@@ -87,23 +97,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->unificookie_name = trim($unificookie_name);
 
         if ($ssl_verify === true) {
             $this->curl_ssl_verify_peer = true;
@@ -131,11 +133,11 @@ class Client
     }
 
     /**
-     * Login to the UniFi controller
+     * 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()
     {
@@ -221,9 +223,9 @@ class Client
     }
 
     /**
-     * Logout from the UniFi controller
+     * Logout from the UniFi controller.
      *
-     * @return bool returns true upon success
+     * @return bool true upon success
      */
     public function logout(): bool
     {
@@ -269,7 +271,7 @@ class Client
      ****************************************************************/
 
     /**
-     * Authorize a client device
+     * Authorize a client device.
      *
      * @param string $mac client MAC address
      * @param int $minutes minutes (from now) until authorization expires
@@ -278,7 +280,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
     {
@@ -305,10 +307,10 @@ class Client
     }
 
     /**
-     * Unauthorize a client device
+     * 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 +323,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
     {
@@ -331,10 +333,10 @@ class Client
     }
 
     /**
-     * Block a client device
+     * 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
     {
@@ -344,10 +346,10 @@ class Client
     }
 
     /**
-     * Unblock a client device
+     * 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
     {
@@ -357,12 +359,12 @@ class Client
     }
 
     /**
-     * Forget one or more client devices
+     * Forget one or more client devices.
      *
      * @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
     {
@@ -375,7 +377,7 @@ class Client
     }
 
     /**
-     * Create a new user/client-device
+     * Create a new user/client-device.
      *
      * @param string $mac client MAC address
      * @param string $user_group_id _id value for the user group the new user/client-device should belong to which
@@ -424,7 +426,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 +441,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
     {
@@ -449,7 +451,7 @@ class Client
     }
 
     /**
-     * Fetch 5-minute site stats
+     * Fetch 5-minute site stats.
      *
      * @note - defaults to the past 12 hours
      *       - this function/method is only supported on controller versions 5.5.* and later
@@ -457,124 +459,91 @@ class Client
      *         the controller settings
      * @param int|null $start optional, Unix timestamp in milliseconds
      * @param int|null $end optional, Unix timestamp in milliseconds
+     * @param array|null $attribs optional, array of attributes to collect. Default values:
+     *                            'bytes', 'wan-tx_bytes', 'wan-rx_bytes', 'wlan_bytes', 'num_sta', 'lan-num_sta',
+     *                            'wlan-num_sta', 'time'
+     *                            Example values:
+     *                            'airtime_avg', 'latency_avg', 'latency_min', 'latency_max'
      * @return array|bool returns an array of 5-minute stats objects for the current site
      */
-    public function stat_5minutes_site(int $start = null, int $end = null)
+    public function stat_5minutes_site(int $start = null, int $end = null, array $attribs = null)
     {
         $end     = empty($end) ? time() * 1000 : $end;
         $start   = empty($start) ? $end - (12 * 3600 * 1000) : $start;
-
+        $attribs = empty($attribs) ? $this->default_site_stats_attribs : array_merge(['time'], $attribs);
-        $attribs = [
-            'bytes',
-            'wan-tx_bytes',
-            'wan-rx_bytes',
-            'wlan_bytes',
-            'num_sta',
-            'lan-num_sta',
-            'wlan-num_sta',
-            'time',
-        ];
-
         $payload = ['attrs' => $attribs, 'start' => $start, 'end' => $end];
 
         return $this->fetch_results('/api/s/' . $this->site . '/stat/report/5minutes.site', $payload);
     }
 
     /**
-     * Fetch hourly site stats
+     * Fetch hourly site stats.
      *
      * TODO: add support for optional attrib parameter
      *       airtime_avg
      *
      * @note - defaults to the past 7*24 hours
      *       - "bytes" are no longer returned with controller version 4.9.1 and later
+     * @see stat_5minutes_site() for details on attribs
      * @param int|null $start optional, Unix timestamp in milliseconds
      * @param int|null $end optional, Unix timestamp in milliseconds
+     * @param array|null $attribs optional, array of attributes to collect.
      * @return array|bool returns an array of hourly stats objects for the current site
      */
-    public function stat_hourly_site(int $start = null, int $end = null)
+    public function stat_hourly_site(int $start = null, int $end = null, array $attribs = null)
     {
         $end     = empty($end) ? time() * 1000 : $end;
         $start   = empty($start) ? $end - (7 * 24 * 3600 * 1000) : $start;
-
+        $attribs = empty($attribs) ? $this->default_site_stats_attribs : array_merge(['time'], $attribs);
-        $attribs = [
-            'bytes',
-            'wan-tx_bytes',
-            'wan-rx_bytes',
-            'wlan_bytes',
-            'num_sta',
-            'lan-num_sta',
-            'wlan-num_sta',
-            'time',
-        ];
-
         $payload = ['attrs' => $attribs, 'start' => $start, 'end' => $end];
 
         return $this->fetch_results('/api/s/' . $this->site . '/stat/report/hourly.site', $payload);
     }
 
     /**
-     * Fetch daily site stats
+     * Fetch daily site stats.
      *
      * @note - defaults to the past 52*7*24 hours
      *       - "bytes" are no longer returned with controller version 4.9.1 and later
+     * @see stat_5minutes_site() for details on attribs
      * @param int|null $start optional, Unix timestamp in milliseconds
      * @param int|null $end optional, Unix timestamp in milliseconds
+     * @param array|null $attribs optional, array of attributes to collect.
      * @return array|bool returns an array of daily stats objects for the current site
      */
-    public function stat_daily_site(int $start = null, int $end = null)
+    public function stat_daily_site(int $start = null, int $end = null, array $attribs = null)
     {
         $end     = empty($end) ? (time() - (time() % 3600)) * 1000 : $end;
         $start   = empty($start) ? $end - (52 * 7 * 24 * 3600 * 1000) : $start;
-
+        $attribs = empty($attribs) ? $this->default_site_stats_attribs : array_merge(['time'], $attribs);
-        $attribs = [
-            'bytes',
-            'wan-tx_bytes',
-            'wan-rx_bytes',
-            'wlan_bytes',
-            'num_sta',
-            'lan-num_sta',
-            'wlan-num_sta',
-            'time',
-        ];
-
         $payload = ['attrs' => $attribs, 'start' => $start, 'end' => $end];
 
         return $this->fetch_results('/api/s/' . $this->site . '/stat/report/daily.site', $payload);
     }
 
     /**
-     * Fetch monthly site stats
+     * Fetch monthly site stats.
      *
      * @note - defaults to the past 52 weeks (52*7*24 hours)
      *       - "bytes" are no longer returned with controller version 4.9.1 and later
+     * @see stat_5minutes_site() for details on attribs
      * @param int|null $start optional, Unix timestamp in milliseconds
      * @param int|null $end optional, Unix timestamp in milliseconds
+     * @param array|null $attribs optional, array of attributes to collect.
      * @return array|bool returns an array of monthly stats objects for the current site
      */
-    public function stat_monthly_site(int $start = null, int $end = null)
+    public function stat_monthly_site(int $start = null, int $end = null, array $attribs = null)
     {
         $end     = empty($end) ? (time() - (time() % 3600)) * 1000 : $end;
         $start   = empty($start) ? $end - (52 * 7 * 24 * 3600 * 1000) : $start;
-
+        $attribs = empty($attribs) ? $this->default_site_stats_attribs : array_merge(['time'], $attribs);
-        $attribs = [
-            'bytes',
-            'wan-tx_bytes',
-            'wan-rx_bytes',
-            'wlan_bytes',
-            'num_sta',
-            'lan-num_sta',
-            'wlan-num_sta',
-            'time',
-        ];
-
         $payload = ['attrs' => $attribs, 'start' => $start, 'end' => $end];
 
         return $this->fetch_results('/api/s/' . $this->site . '/stat/report/monthly.site', $payload);
     }
 
     /**
-     * Fetch 5-minutes stats for a single access point or all access points
+     * Fetch 5-minutes stats for a single access point or all access points.
      *
      * @note - defaults to the past 12 hours
      *       - this function/method is only supported on controller versions 5.5.* and later
@@ -584,13 +553,37 @@ class Client
      * @param int|null $end optional, Unix timestamp in milliseconds
      * @param string|null $mac optional, AP MAC address to return stats for, when empty,
      *                      stats for all APs are returned
+     * @param array|null $attribs optional, array of attributes to collect, default: (bytes, num_sta, time). Example values:
+     *                       'bytes',
+     *                       'num_sta',
+     *                       'time',
+     *                       'wifi_tx_attempts',
+     *                       'tx_retries',
+     *                       'wifi_tx_dropped',
+     *                       'mac_filter_rejections',
+     *                       'user-wlan-num_sta_connected',
+     *                       'user-wlan-num_sta_disconnected',
+     *                       'na-wifi_tx_attempts',
+     *                       'ng-wifi_tx_attempts',
+     *                       'na-wifi_tx_dropped',
+     *                       'ng-wifi_tx_dropped',
+     *                       'na-tx_retries',
+     *                       'ng-tx_retries',
+     *                       'na-tx_packets',
+     *                       'ng-tx_packets',
+     *                       'na-tx_bytes',
+     *                       'ng-tx_bytes',
+     *                       'na-rx_packets',
+     *                       'ng-rx_packets',
+     *                       'na-rx_bytes',
+     *                       'ng-rx_bytes',
      * @return array|bool returns an array of 5-minute stats objects
      */
-    public function stat_5minutes_aps(int $start = null, int $end = null, string $mac = null)
+    public function stat_5minutes_aps(int $start = null, int $end = null, string $mac = null, array $attribs = null)
     {
         $end     = empty($end) ? time() * 1000 : $end;
         $start   = empty($start) ? $end - (12 * 3600 * 1000) : $start;
-        $attribs = ['bytes', 'num_sta', 'time'];
+        $attribs = empty($attribs) ? ['bytes', 'num_sta', 'time'] : array_merge(['time'], $attribs);
         $payload = ['attrs' => $attribs, 'start' => $start, 'end' => $end];
 
         if (!empty($mac)) {
@@ -601,42 +594,24 @@ class Client
     }
 
     /**
-     * Fetch hourly stats for a single access point or all access points
+     * Fetch hourly stats for a single access point or all access points.
-     *
-     * TODO: optionally add ["top_filter_by" => "tx_retries"] to payload
-     *       add optional parameter for attribs to support:
-     *       wifi_tx_attempts
-     *       tx_retries
-     *       wifi_tx_dropped
-     *       sta_assoc_failures
-     *       sta_wpa_auth_failures
-     *       mac_filter_rejections
-     *       sta_dhcp_failures
-     *       sta_assoc_min
-     *       sta_assoc_max
-     *       sta_connect_time_min
-     *       sta_connect_time_max
-     *       sta_connect_time_total
-     *       user-wlan-num_sta_connected
-     *       user-wlan-num_sta_disconnected
-     *       user-wlan-sta_assoc_samples
-     *       user-wlan-sta_track_samples
-     *       wlan-num_sta
      *
      * @note - defaults to the past 7*24 hours
      *       - make sure that the retention policy for hourly stats is set to the correct value in
      *         the controller settings
+     * @see stat_5minutes_aps() for supported attribs
      * @param int|null $start optional, Unix timestamp in milliseconds
      * @param int|null $end optional, Unix timestamp in milliseconds
      * @param string|null $mac optional, AP MAC address to return stats for, when empty,
      *                       stats for all APs are returned
+     * @param array|null $attribs optional, array of attributes to collect, default: (bytes, num_sta, time).
      * @return array|bool returns an array of hourly stats objects
      */
-    public function stat_hourly_aps(int $start = null, int $end = null, string $mac = null)
+    public function stat_hourly_aps(int $start = null, int $end = null, string $mac = null, array $attribs = null)
     {
         $end     = empty($end) ? (time() * 1000) : $end;
         $start   = empty($start) ? $end - (7 * 24 * 3600 * 1000) : $start;
-        $attribs = ['bytes', 'num_sta', 'time'];
+        $attribs = empty($attribs) ? ['bytes', 'num_sta', 'time'] : array_merge(['time'], $attribs);
         $payload = ['attrs' => $attribs, 'start' => $start, 'end' => $end];
 
         if (!empty($mac)) {
@@ -647,22 +622,24 @@ class Client
     }
 
     /**
-     * Fetch daily stats for a single access point or all access points
+     * Fetch daily stats for a single access point or all access points.
      *
      * @note - defaults to the past 7*24 hours
      *       - make sure that the retention policy for hourly stats is set to the correct value in
      *         the controller settings
+     * @see stat_5minutes_aps() for supported attribs
      * @param int|null $start optional, Unix timestamp in milliseconds
      * @param int|null $end optional, Unix timestamp in milliseconds
      * @param string|null $mac optional, AP MAC address to return stats for, when empty,
      *                         stats for all APs are returned
+     * @param array|null $attribs optional, array of attributes to collect, default: (bytes, num_sta, time).
      * @return array|bool returns an array of daily stats objects
      */
-    public function stat_daily_aps(int $start = null, int $end = null, string $mac = null)
+    public function stat_daily_aps(int $start = null, int $end = null, string $mac = null, array $attribs = null)
     {
         $end     = empty($end) ? time() * 1000 : $end;
         $start   = empty($start) ? $end - (7 * 24 * 3600 * 1000) : $start;
-        $attribs = ['bytes', 'num_sta', 'time'];
+        $attribs = empty($attribs) ? ['bytes', 'num_sta', 'time'] : array_merge(['time'], $attribs);
         $payload = ['attrs' => $attribs, 'start' => $start, 'end' => $end];
 
         if (!empty($mac)) {
@@ -678,17 +655,19 @@ class Client
      * @note - defaults to the past 52 weeks (52*7*24 hours)
      *       - make sure that the retention policy for hourly stats is set to the correct value in
      *         the controller settings
+     * @see stat_5minutes_aps() for supported attribs
      * @param int|null $start optional, Unix timestamp in milliseconds
      * @param int|null $end optional, Unix timestamp in milliseconds
      * @param string|null $mac optional, AP MAC address to return stats for, when empty,
      *                         stats for all APs are returned
+     * @param array|null $attribs optional, array of attributes to collect, default: (bytes, num_sta, time).
      * @return array|bool returns an array of monthly stats objects
      */
-    public function stat_monthly_aps(int $start = null, int $end = null, string $mac = null)
+    public function stat_monthly_aps(int $start = null, int $end = null, string $mac = null, array $attribs = null)
     {
         $end     = empty($end) ? time() * 1000 : $end;
         $start   = empty($start) ? $end - (52 * 7 * 24 * 3600 * 1000) : $start;
-        $attribs = ['bytes', 'num_sta', 'time'];
+        $attribs = empty($attribs) ? ['bytes', 'num_sta', 'time'] : array_merge(['time'], $attribs);
         $payload = ['attrs' => $attribs, 'start' => $start, 'end' => $end];
 
         if (!empty($mac)) {
@@ -699,8 +678,7 @@ class Client
     }
 
     /**
-     * Fetch 5-minutes stats for a single user/client device
+     * Fetch 5-minutes stats for a single user/client device.
-     *
      *
      * @note - defaults to the past 12 hours
      *       - only supported with UniFi controller versions 5.8.X and higher
@@ -728,7 +706,7 @@ class Client
     }
 
     /**
-     * Fetch hourly stats for a single user/client device
+     * Fetch hourly stats for a single user/client device.
      *
      * @note - defaults to the past 7*24 hours
      *       - only supported with UniFi controller versions 5.8.X and higher
@@ -736,13 +714,11 @@ class Client
      *         the controller settings
      *       - make sure that "Clients Historical Data" has been enabled in the UniFi controller settings in the Maintenance
      *         section
+     * @see stat_5minutes_user() for details on attribs
      * @param string $mac MAC address of the user/client device to return stats fo
      * @param int|null $start optional, Unix timestamp in milliseconds
      * @param int|null $end optional, Unix timestamp in milliseconds
-     * @param array|null $attribs array containing attributes (strings) to be returned, valid values are:
+     * @param array|null $attribs array containing attributes (strings) to be returned
-     *                        rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets,
-     *                        tx_packets, satisfaction, wifi_tx_attempts
-     *                        default value is ['rx_bytes', 'tx_bytes']
      * @return array|bool returns an array of hourly stats objects
      */
     public function stat_hourly_user(string $mac, int $start = null, int $end = null, array $attribs = null)
@@ -756,7 +732,7 @@ class Client
     }
 
     /**
-     * Fetch daily stats for a single user/client device
+     * Fetch daily stats for a single user/client device.
      *
      * @note - defaults to the past 7*24 hours
      *       - only supported with UniFi controller versions 5.8.X and higher
@@ -764,13 +740,11 @@ class Client
      *         the controller settings
      *       - make sure that "Clients Historical Data" has been enabled in the UniFi controller settings in the Maintenance
      *         section
+     * @see stat_5minutes_user() for details on attribs
      * @param string $mac MAC address of the user/client device to return stats for
      * @param int|null $start optional, Unix timestamp in milliseconds
      * @param int|null $end optional, Unix timestamp in milliseconds
-     * @param array|null $attribs array containing attributes (strings) to be returned, valid values are:
+     * @param array|null $attribs array containing attributes (strings) to be returned
-     *                        rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets,
-     *                        tx_packets, satisfaction, wifi_tx_attempts
-     *                        default value is ['rx_bytes', 'tx_bytes']
      * @return array|bool returns an array of daily stats objects
      */
     public function stat_daily_user(string $mac, int $start = null, int $end = null, array $attribs = null)
@@ -784,7 +758,7 @@ class Client
     }
 
     /**
-     * Fetch monthly stats for a single user/client device
+     * Fetch monthly stats for a single user/client device.
      *
      * @note - defaults to the past 13 weeks (52*7*24 hours)
      *       - only supported with UniFi controller versions 5.8.X and higher
@@ -792,13 +766,11 @@ class Client
      *         the controller settings
      *       - make sure that "Clients Historical Data" has been enabled in the UniFi controller settings in the Maintenance
      *         section
+     * @see stat_5minutes_user() for details on attribs
      * @param string $mac MAC address of the user/client device to return stats for
      * @param int|null $start optional, Unix timestamp in milliseconds
      * @param int|null $end optional, Unix timestamp in milliseconds
-     * @param array|null $attribs array containing attributes (strings) to be returned, valid values are:
+     * @param array|null $attribs array containing attributes (strings) to be returned
-     *                        rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets,
-     *                        tx_packets, satisfaction, wifi_tx_attempts
-     *                        default value is ['rx_bytes', 'tx_bytes']
      * @return array|bool returns an array of monthly stats objects
      */
     public function stat_monthly_user(string $mac, int $start = null, int $end = null, array $attribs = null)
@@ -812,7 +784,7 @@ class Client
     }
 
     /**
-     * Fetch 5-minute gateway stats
+     * Fetch 5-minute gateway stats.
      *
      * @note - defaults to the past 12 hours
      *       - this function/method is only supported on controller versions 5.5.* and later
@@ -838,16 +810,14 @@ class Client
     }
 
     /**
-     * Fetch hourly gateway stats
+     * Fetch hourly gateway stats.
      *
      * @note - defaults to the past 7*24 hours
      *       - requires a UniFi gateway
+     * @see stat_5minutes_gateway() for details on attribs
      * @param int|null $start optional, Unix timestamp in milliseconds
      * @param int|null $end optional, Unix timestamp in milliseconds
-     * @param array|null $attribs array containing attributes (strings) to be returned, valid values are:
+     * @param array|null $attribs array containing attributes (strings) to be returned
-     *                       mem, cpu, loadavg_5, lan-rx_errors, lan-tx_errors, lan-rx_bytes,
-     *                       lan-tx_bytes, lan-rx_packets, lan-tx_packets, lan-rx_dropped, lan-tx_dropped
-     *                       default is ['time', 'mem', 'cpu', 'loadavg_5']
      * @return array|bool returns an array of hourly stats objects for the gateway belonging to the current site
      */
     public function stat_hourly_gateway(int $start = null, int $end = null, array $attribs = null)
@@ -861,16 +831,14 @@ class Client
     }
 
     /**
-     * Fetch daily gateway stats
+     * Fetch daily gateway stats.
      *
      * @note - defaults to the past 52 weeks (52*7*24 hours)
      *       - requires a UniFi gateway
+     * @see stat_5minutes_gateway() for details on attribs
      * @param int|null $start optional, Unix timestamp in milliseconds
      * @param int|null $end optional, Unix timestamp in milliseconds
-     * @param array|null $attribs array containing attributes (strings) to be returned, valid values are:
+     * @param array|null $attribs array containing attributes (strings) to be returned
-     *                       mem, cpu, loadavg_5, lan-rx_errors, lan-tx_errors, lan-rx_bytes,
-     *                       lan-tx_bytes, lan-rx_packets, lan-tx_packets, lan-rx_dropped, lan-tx_dropped
-     *                       default is ['time', 'mem', 'cpu', 'loadavg_5']
      * @return array|bool returns an array of hourly stats objects for the gateway belonging to the current site
      */
     public function stat_daily_gateway(int $start = null, int $end = null, array $attribs = null)
@@ -884,16 +852,14 @@ class Client
     }
 
     /**
-     * Fetch monthly gateway stats
+     * Fetch monthly gateway stats.
      *
      * @note - defaults to the past 52 weeks (52*7*24 hours)
      *       - requires a UniFi gateway
+     * @see stat_5minutes_gateway() for details on attribs
      * @param int|null $start optional, Unix timestamp in milliseconds
      * @param int|null $end optional, Unix timestamp in milliseconds
-     * @param array|null $attribs array containing attributes (strings) to be returned, valid values are:
+     * @param array|null $attribs array containing attributes (strings) to be returned
-     *                       mem, cpu, loadavg_5, lan-rx_errors, lan-tx_errors, lan-rx_bytes,
-     *                       lan-tx_bytes, lan-rx_packets, lan-tx_packets, lan-rx_dropped, lan-tx_dropped
-     *                       default is ['time', 'mem', 'cpu', 'loadavg_5']
      * @return array|bool returns an array of monthly stats objects for the gateway belonging to the current site
      */
     public function stat_monthly_gateway(int $start = null, int $end = null, array $attribs = null)
@@ -907,7 +873,7 @@ class Client
     }
 
     /**
-     * Fetch speed test results
+     * Fetch speed test results.
      *
      * @note - defaults to the past 24 hours
      *       - requires a UniFi gateway
@@ -925,7 +891,7 @@ class Client
     }
 
     /**
-     * Fetch IPS/IDS events
+     * Fetch IPS/IDS events.
      *
      * @note - defaults to the past 24 hours
      *       - requires a UniFi gateway
@@ -1082,11 +1048,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 +1062,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 +1849,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 +3037,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 +3051,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 +3065,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 +3081,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 +3098,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 +3108,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 +3142,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 +3155,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 +3386,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 +3403,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 +3422,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 +3527,6 @@ class Client
     public function set_site(string $site): string
     {
         $this->check_site($site);
-
         $this->site = trim($site);
 
         return $this->site;
@@ -3901,7 +3930,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
     {