Merge branch 'master' of github.com:Art-of-WiFi/UniFi-API-client

merge for device-basic

README.md

@@ -2,8 +2,9 @@
 
 A PHP class that provides access to Ubiquiti's [**UniFi Network Controller**](https://unifi-network.ui.com/) API.
 
-UniFi Network Controller software versions 4.X.X, 5.X.X and 6.X.X are supported  as well as UniFi OS-based controllers (version 6.5.55 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).
+UniFi Network Controller software versions 4.X.X, 5.X.X, 6.X.X, and 7.X.X (version 7.2.93 has been confirmed to work)
+are supported as well as UniFi OS-based controllers. This class is used by our API browser tool which can be found
+[here](https://github.com/Art-of-WiFi/UniFi-API-browser).
 
 The package can be installed manually or by using
 composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for
@@ -15,20 +16,24 @@ easy inclusion in your projects.
   - PHP 5.5.0 or higher 
   - PHP json and PHP cURL modules
   - tested on Apache 2.4 with PHP 5.6.1 and cURL 7.42.1 and with PHP 7.4.9 and cURL 7.68.0
-- direct network connectivity between this server and the host and port (normally TCP port 8443 or port 443 for 
+- 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**, not pure UniFi Cloud accounts, to access the UniFi Controller API through 
-  this class
+- you must use **accounts with local access**, not UniFi Cloud accounts, to access the UniFi Controller API 
+  through this class
 
 ## UniFi OS Support
 
-Support for UniFi OS-based controllers (UniFi Dream Router, UniFi Dream Machine, UniFi Dream Machine Pro 
-or Cloud Key Gen2/Cloud Key Gen2 Plus with firmware version 2.0.24 or higher) has 
-been added as of version 1.1.47. The class automatically detects UniFi OS devices and
-adjusts URLs and several functions/methods accordingly. If your own code implements strict
-validation of the URL that is passed to the constructor, please adapt your logic to 
-allow URLs without a port suffix or with port 443 when dealing with a UniFi OS-based
-controller.
+Support for UniFi OS-based controllers has been added as of version 1.1.47:
+- UniFi Dream Router (UDR)
+- UniFi Dream Machine (UDM)
+- UniFi Dream Machine Pro (UDM PRO)
+- UniFi Cloud Key Gen2 (UCK G2), firmware version 2.0.24 or higher
+- 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)
+
+The class automatically detects UniFi OS-based controllers and adjusts URLs and several functions/methods accordingly.
+If your own code implements strict validation of the URL that is passed to the constructor, please adapt your
+logic to allow URLs without a port suffix or with port 443 when working with a UniFi OS-based controller.
 
 Please test all methods you plan on using thoroughly before using the API Client with
 UniFi OS devices in a production environment.
@@ -128,9 +133,10 @@ own PHP code.
    associated with the FQDN in the `controller_url` parameter. This option was added with API client version 1.1.16.
 
 3. Using an administrator account (`$controller_user` in the above example) with **read-only** permissions can limit 
-   visibility on certain collection/object properties. See this [issue](https://github.com/Art-of-WiFi/UniFi-API-client/issues/129)
-   and this [issue](https://github.com/Art-of-WiFi/UniFi-API-browser/issues/94) for an example where the WPA2 password
-   isn't accessible for **read-only** administrator accounts.
+   visibility on certain collection/object properties. See this
+   [issue](https://github.com/Art-of-WiFi/UniFi-API-client/issues/129) and this 
+   [issue](https://github.com/Art-of-WiFi/UniFi-API-browser/issues/94) for an example where the WPA2 password isn't
+   visible for **read-only** administrator accounts.
 
 ## Functions/methods supported
 
@@ -178,6 +184,8 @@ more details on each of the functions/methods and their respective parameters.
 - edit_usergroup()
 - extend_guest_validity()
 - forget_sta() (supported on controller version 5.9.X and higher)
+- generate_backup()
+- generate_backup_site()
 - invite_admin()
 - led_override()
 - list_admins()
@@ -347,7 +355,7 @@ This class is based on the initial work by the following developers:
 
 and the API as published by Ubiquiti:
 
-- https://dl.ui.com/unifi/6.5.55/unifi_sh_api
+- https://dl.ui.com/unifi/7.0.25/unifi_sh_api
 
 ## Important Disclaimer
 

examples/update_switch_poe-mode.php

@@ -8,6 +8,9 @@
  * usage:          If the file is called via a web URL, it should be called like: update_switch_poe-mode.php?poe_mode=off
  *                 If the file is called via the command line, it should be called like: php update_switch_poe-mode.php off
  *                 The values can be "off" or "auto"
+ *
+ * IMPORTANT INFORMATION:
+ * This example no longer works with controller versions 7.1.X and higher. You now need to work with port profiles to enable POE on a switch port.
  */
 
 /**
@@ -91,4 +94,4 @@ if (!$update_device) {
     echo json_encode($error, JSON_PRETTY_PRINT);
 }
 
-echo json_encode($update_device, JSON_PRETTY_PRINT);
+echo json_encode($update_device, JSON_PRETTY_PRINT);

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.80
  * @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.80';
     protected $baseurl              = 'https://127.0.0.1:8443';
     protected $user                 = '';
     protected $password             = '';
@@ -38,10 +38,10 @@ class Client
     protected $exec_retries         = 0;
     protected $cookies              = '';
     protected $last_results_raw     = null;
-    protected $last_error_message   = null;
+    protected $last_error_message   = '';
     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',
@@ -427,11 +424,10 @@ class Client
      * Add/modify/remove a client-device note
      *
      * @param string $user_id id of the client-device to be modified
-     * @param string $note    optional, note to be applied to the client-device, when empty or not set,
-     *                        the existing note for the client-device is removed and "noted" attribute set to false
+     * @param string $note    optional, note to be applied to the client-device
      * @return bool returns true upon success
      */
-    public function set_sta_note($user_id, $note = null)
+    public function set_sta_note($user_id, $note = '')
     {
         $payload = ['note' => $note];
         return $this->fetch_results_boolean('/api/s/' . $this->site . '/upd/user/' . trim($user_id), $payload);
@@ -445,7 +441,7 @@ class Client
      *                        the existing name for the client device is removed
      * @return bool returns true upon success
      */
-    public function set_sta_name($user_id, $name = null)
+    public function set_sta_name($user_id, $name = '')
     {
         $payload = ['name' => $name];
         return $this->fetch_results_boolean('/api/s/' . $this->site . '/upd/user/' . trim($user_id), $payload);
@@ -485,6 +481,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 +599,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 +700,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 +714,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 +743,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 +772,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 +801,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 +1056,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
-     *               single client device object
+     * @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, false upon error
      */
     public function list_clients($client_mac = null)
     {
@@ -1372,11 +1396,22 @@ class Client
         return $this->fetch_results('/api/s/' . $this->site . '/list/user');
     }
 
+    /**
+     * List of site devices with a basic subset of fields (e.g., mac, state, adopted, disabled, type, model, name)
+     *
+     * @return array|false an array containing known UniFi device objects), false upon error
+     */
+    public function list_devices_basic()
+    {
+        return $this->fetch_results('/api/s/' . $this->site . '/stat/device-basic');
+    }
+
     /**
      * 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)
     {
@@ -1422,10 +1457,9 @@ class Client
     }
 
     /**
-     * Generate backup
+     * Generate a backup
      *
-     * NOTES:
-     * this is an experimental function, please do not use unless you know exactly what you're doing
+     * NOTES: this is an experimental function, please do not use unless you know exactly what you're doing
      *
      * @return array|bool URL from where the backup file can be downloaded once generated, false upon failure
      */
@@ -1446,6 +1480,20 @@ class Client
         return $this->fetch_results('/api/s/' . $this->site . '/cmd/backup', $payload);
     }
 
+    /**
+     * Generate a backup/export of the current site
+     *
+     * NOTES: this is an experimental function, please do not use unless you know exactly what you're doing
+     *
+     * @return array|bool URL from where the backup/export file can be downloaded once generated, false upon failure
+     */
+    public function generate_backup_site()
+    {
+        $payload = ['cmd' => 'export-site'];
+
+        return $this->fetch_results('/api/s/' . $this->site . '/cmd/backup', $payload);
+    }
+
     /**
      * Fetch sites
      *
@@ -1680,7 +1728,8 @@ class Client
         $device_adopt = false,
         $device_restart = false
     ) {
-        $email_valid = filter_var(trim($email), FILTER_VALIDATE_EMAIL);
+        $email       = trim($email);
+        $email_valid = filter_var($email, FILTER_VALIDATE_EMAIL);
         if (!$email_valid) {
             trigger_error('The email address provided is invalid!');
             return false;
@@ -1688,7 +1737,7 @@ class Client
 
         $payload = [
             'name'        => trim($name),
-            'email'       => trim($email),
+            'email'       => $email,
             'for_sso'     => $enable_sso,
             'cmd'         => 'invite-admin',
             'role'        => 'admin',
@@ -1869,10 +1918,10 @@ class Client
      * @param string $note       optional, note to attach to the hotspot operator
      * @return bool true upon success
      */
-    public function create_hotspotop($name, $x_password, $note = null)
+    public function create_hotspotop($name, $x_password, $note = '')
     {
         $payload = ['name' => $name, 'x_password' => $x_password];
-        if (is_string($note)) {
+        if (!empty($note)) {
             $payload['note'] = trim($note);
         }
 
@@ -1908,7 +1957,7 @@ class Client
         $minutes,
         $count = 1,
         $quota = 0,
-        $note = null,
+        $note = '',
         $up = null,
         $down = null,
         $megabytes = null
@@ -1920,7 +1969,7 @@ class Client
             'quota'  => intval($quota),
         ];
 
-        if (is_string($note)) {
+        if (!empty($note)) {
             $payload['note'] = trim($note);
         }
 
@@ -2549,7 +2598,7 @@ class Client
      * @return array containing wireless networks and their settings, or an array containing a single wireless network
      *               when using the <wlan_id> parameter
      */
-    public function list_wlanconf($wlan_id = null)
+    public function list_wlanconf($wlan_id = '')
     {
         return $this->fetch_results('/api/s/' . $this->site . '/rest/wlanconf/' . trim($wlan_id));
     }
@@ -2650,12 +2699,12 @@ class Client
      * @param string $name         optional, SSID
      * @return bool true on success
      */
-    public function set_wlansettings($wlan_id, $x_passphrase, $name = null)
+    public function set_wlansettings($wlan_id, $x_passphrase, $name = '')
     {
         $payload                 = [];
         $payload['x_passphrase'] = trim($x_passphrase);
 
-        if (is_string($name)) {
+        if (!empty($name)) {
             $payload['name'] = trim($name);
         }
 
@@ -2778,7 +2827,7 @@ class Client
      *                         by default all alarms are archived
      * @return bool true on success
      */
-    public function archive_alarm($alarm_id = null)
+    public function archive_alarm($alarm_id = '')
     {
         $payload = ['cmd' => 'archive-all-alarms'];
         if (!empty($alarm_id)) {
@@ -3017,9 +3066,9 @@ class Client
      */
     public function create_radius_account($name, $x_password, $tunnel_type = null, $tunnel_medium_type = null, $vlan = null)
     {
-        $tunnel_types        = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
-        $tunnel_medium_types = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
-        if ((!is_null($tunnel_type) && !in_array($tunnel_type, $tunnel_types)) || (!is_null($tunnel_medium_type) && !in_array($tunnel_medium_type, $tunnel_medium_types)) || ($tunnel_type ^ $tunnel_medium_type)) {
+        $tunnel_type_values        = [null, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
+        $tunnel_medium_type_values = [null, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
+        if (!in_array($tunnel_type, $tunnel_type_values) || !in_array($tunnel_medium_type, $tunnel_medium_type_values) || ($tunnel_type xor $tunnel_medium_type)) {
             return false;
         }
 
@@ -3037,7 +3086,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 +3387,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|object|null the raw results as returned by the controller API
      */
     public function get_last_results_raw($return_json = false)
     {
@@ -3356,16 +3405,12 @@ class Client
     /**
      * Get last error message
      *
-     * @return object|bool the error message of the last method called in PHP stdClass Object format, returns false if
-     *                     unavailable
+     * @return string the error message of the last method called in PHP stdClass Object format, an empty string when
+     *                none available
      */
     public function get_last_error_message()
     {
-        if (!is_null($this->last_error_message)) {
-            return $this->last_error_message;
-        }
-
-        return false;
+        return $this->last_error_message;
     }
 
     /**
@@ -3571,12 +3616,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
-     * - the default value used in this class is CURL_HTTP_VERSION_1_1
-     * - https://curl.se/libcurl/c/CURLOPT_HTTP_VERSION.html
+     * - as of cURL version 7.62.0 the default value is CURL_HTTP_VERSION_2TLS which may cause issues,
+     *   this method allows to set the value to CURL_HTTP_VERSION_1_1 when needed
      *
-     * @param int $http_version new value for $curl_http_version, can be CURL_HTTP_VERSION_1_1 int(2)
-     *                          or CURL_HTTP_VERSION_2TLS int(4)
+     * @param int $http_version new value for $curl_http_version, CURL_HTTP_VERSION_1_1 int(2) or
+     *                          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 +3633,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()
     {
@@ -3628,7 +3674,7 @@ class Client
 
             if (isset($response->meta->rc)) {
                 if ($response->meta->rc === 'ok') {
-                    $this->last_error_message = null;
+                    $this->last_error_message = '';
                     if (is_array($response->data) && !$boolean) {
                         return $response->data;
                     }