API client class v1.1.77

- removed unnecessary CURLOPT_HEADER from the login() method
- added several more possible attributes for client stats
- cast VLAN id to string in create_radius_account()

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.75
+ * @version Release: 1.1.77
  * @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
@@ -26,7 +26,7 @@ class Client
      * NOTE:
      * do not modify the values here, instead use the constructor or the getter and setter functions/methods
      */
-    const CLASS_VERSION = '1.1.75';
+    const CLASS_VERSION = '1.1.77';
     protected $baseurl              = 'https://127.0.0.1:8443';
     protected $user                 = '';
     protected $password             = '';
@@ -41,7 +41,7 @@ class Client
     protected $last_error_message   = null;
     protected $curl_ssl_verify_peer = false;
     protected $curl_ssl_verify_host = false;
-    protected $curl_http_version    = CURL_HTTP_VERSION_1_1;
+    protected $curl_http_version    = CURL_HTTP_VERSION_NONE;
     protected $curl_headers         = [];
     protected $curl_method          = 'GET';
     protected $curl_methods_allowed = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
@@ -140,9 +140,6 @@ class Client
         }
 
         $curl_options = [
-            CURLOPT_HEADER => true,
-            CURLOPT_POST   => true,
-            CURLOPT_NOBODY => true,
             CURLOPT_URL    => $this->baseurl . '/',
         ];
 
@@ -162,7 +159,7 @@ class Client
          * prepare the actual login
          */
         $curl_options = [
-            CURLOPT_NOBODY     => false,
+            CURLOPT_POST       => true,
             CURLOPT_POSTFIELDS => json_encode(['username' => $this->user, 'password' => $this->password]),
             CURLOPT_HTTPHEADER => [
                 'content-type: application/json',
@@ -485,6 +482,9 @@ class Client
     /**
      * Fetch hourly site stats
      *
+     * TODO: add support for optional attrib parameter
+     *       airtime_avg
+     *
      * NOTES:
      * - defaults to the past 7*24 hours
      * - "bytes" are no longer returned with controller version 4.9.1 and later
@@ -600,6 +600,26 @@ class Client
     /**
      * 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
+     *
      * NOTES:
      * - defaults to the past 7*24 hours
      * - make sure that the retention policy for hourly stats is set to the correct value in
@@ -681,6 +701,7 @@ class Client
     /**
      * Fetch 5 minutes stats for a single user/client device
      *
+     *
      * NOTES:
      * - defaults to the past 12 hours
      * - only supported with UniFi controller versions 5.8.X and higher
@@ -694,7 +715,8 @@ class Client
      * @param int    $end     optional, Unix timestamp in milliseconds
      * @param array  $attribs array containing attributes (strings) to be returned, valid values are:
      *                        rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets,
-     *                        tx_packets default is ['rx_bytes', 'tx_bytes']
+     *                        tx_packets, satisfaction, wifi_tx_attempts
+     *                        default value is ['rx_bytes', 'tx_bytes']
      * @return array returns an array of 5-minute stats objects
      */
     public function stat_5minutes_user($mac, $start = null, $end = null, $attribs = null)
@@ -722,7 +744,8 @@ class Client
      * @param int    $end     optional, Unix timestamp in milliseconds
      * @param array  $attribs array containing attributes (strings) to be returned, valid values are:
      *                        rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets,
-     *                        tx_packets default is ['rx_bytes', 'tx_bytes']
+     *                        tx_packets, satisfaction, wifi_tx_attempts
+     *                        default value is ['rx_bytes', 'tx_bytes']
      * @return array returns an array of hourly stats objects
      */
     public function stat_hourly_user($mac, $start = null, $end = null, array $attribs = null)
@@ -750,7 +773,8 @@ class Client
      * @param int    $end     optional, Unix timestamp in milliseconds
      * @param array  $attribs array containing attributes (strings) to be returned, valid values are:
      *                        rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets,
-     *                        tx_packets default is ['rx_bytes', 'tx_bytes']
+     *                        tx_packets, satisfaction, wifi_tx_attempts
+     *                        default value is ['rx_bytes', 'tx_bytes']
      * @return array returns an array of daily stats objects
      */
     public function stat_daily_user($mac, $start = null, $end = null, $attribs = null)
@@ -778,7 +802,8 @@ class Client
      * @param int    $end     optional, Unix timestamp in milliseconds
      * @param array  $attribs array containing attributes (strings) to be returned, valid values are:
      *                        rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets,
-     *                        tx_packets default is ['rx_bytes', 'tx_bytes']
+     *                        tx_packets, satisfaction, wifi_tx_attempts
+     *                        default value is ['rx_bytes', 'tx_bytes']
      * @return array returns an array of monthly stats objects
      */
     public function stat_monthly_user($mac, $start = null, $end = null, $attribs = null)
@@ -1032,8 +1057,8 @@ class Client
      *
      * @param string $client_mac optional, the MAC address of a single online client device for which the call must be
      *                           made
-     * @return array returns an array of online client device objects, or in case of a single device request, returns a
+     * @return array|false returns an array of online client device objects, or in case of a single device request, returns a
-     *               single client device object
+     *                    single client device object, false upon error
      */
     public function list_clients($client_mac = null)
     {
@@ -1376,7 +1401,8 @@ class Client
      * Fetch UniFi devices
      *
      * @param string $device_mac optional, the MAC address of a single UniFi device for which the call must be made
-     * @return array containing known UniFi device objects (or a single device when using the <device_mac> parameter)
+     * @return array|false an array containing known UniFi device objects (or a single device when using the <device_mac>
+     *                     parameter), false upon error
      */
     public function list_devices($device_mac = null)
     {
@@ -3037,7 +3063,7 @@ class Client
         }
 
         if (!is_null($vlan)) {
-            $payload['vlan'] = (int) $vlan;
+            $payload['vlan'] = (string) $vlan;
         }
 
         return $this->fetch_results('/api/s/' . $this->site . '/rest/account', $payload);
@@ -3338,7 +3364,7 @@ class Client
      *
      * @param boolean $return_json true returns the results in "pretty printed" json format,
      *                             false returns PHP stdClass Object format (default)
-     * @return object|string the raw results as returned by the controller API
+     * @return false|string|null the raw results as returned by the controller API
      */
     public function get_last_results_raw($return_json = false)
     {
@@ -3571,12 +3597,12 @@ class Client
      * Set value for the private property $curl_http_version
      *
      * NOTES:
-     * - as of cURL version 7.62.0 the default value is CURL_HTTP_VERSION_2TLS which may cause issues
+     * - as of cURL version 7.62.0 the default value is CURL_HTTP_VERSION_2TLS which may cause issues,
-     * - the default value used in this class is CURL_HTTP_VERSION_1_1
+     *   this method allows to set the value to CURL_HTTP_VERSION_1_1 when needed
-     * - https://curl.se/libcurl/c/CURLOPT_HTTP_VERSION.html
      *
-     * @param int $http_version new value for $curl_http_version, can be CURL_HTTP_VERSION_1_1 int(2)
+     * @param int $http_version new value for $curl_http_version, CURL_HTTP_VERSION_1_1 int(2) or
-     *                          or CURL_HTTP_VERSION_2TLS int(4)
+     *                          CURL_HTTP_VERSION_2TLS int(4) are recommended
+     * @see https://curl.se/libcurl/c/CURLOPT_HTTP_VERSION.html
      */
     public function set_curl_http_version($http_version)
     {
@@ -3588,6 +3614,7 @@ class Client
      *
      * @return int current value of $request_timeout, can be CURL_HTTP_VERSION_1_1 int(2) or
      *             CURL_HTTP_VERSION_2TLS int(4)
+     * @see https://curl.se/libcurl/c/CURLOPT_HTTP_VERSION.html
      */
     public function get_curl_http_version()
     {