API client class v1.1.74

- minor refactoring
- fixed minor typos
- updated README to reflect limited visibility when using read-only administrator accounts, reported by @KetchupBomb and @NickDunas

README.md

@@ -2,8 +2,7 @@
 
 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 
-(version 6.4.54 has been confirmed to work) as well as UniFi OS-based controllers . 
+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.50 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).
 
 The package can be installed manually or by using
@@ -16,11 +15,10 @@ easy inclusion in your projects.
   - PHP version 5.5.0 or higher
   - PHP json and PHP cURL modules
   - tested on Apache 2.4 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.2.24 and cURL 7.58.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 (normally 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 pure UniFi Cloud accounts, to access the UniFi Controller API through 
+  this class
 
 ## UniFi OS Support
 
@@ -86,7 +84,7 @@ require_once 'path/to/src/Client.php';
 ### Download the Release
 
 If you prefer not to use composer or git,
-simply [download the package](https://github.com/Art-of-WiFi/UniFi-API-client/archive/master.zip), uncompress the zip
+simply [download the package](https://github.com/Art-of-WiFi/UniFi-API-client/archive/master.zip), unpack the zip
 file, then include the file containing the class in your code like so:
 
 ```php
@@ -107,7 +105,7 @@ require_once 'vendor/autoload.php';
  * initialize the UniFi API connection class, log in to the controller and request the alarms collection
  * (this example assumes you have already assigned the correct values to the variables used)
  */
-$unifi_connection = new UniFi_API\Client($controller_user, $controller_password $controller_url, $site_id, $controller_version, true);
+$unifi_connection = new UniFi_API\Client($controller_user, $controller_password, $controller_url, $site_id, $controller_version, true);
 $login            = $unifi_connection->login();
 $results          = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects
 ```
@@ -129,11 +127,16 @@ own PHP code.
    this feature in production environments where you have a valid SSL cert installed on the UniFi Controller that is
    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.
+
 ## Functions/methods supported
 
 The class currently supports the following functions/methods to GET/POST/PUT/DELETE data
 through the UniFi Controller API. Please refer to the comments in the source code for
-more details on the functions/methods and their respective parameters.
+more details on each of the functions/methods and their respective parameters.
 
 - login()
 - logout()
@@ -170,6 +173,7 @@ more details on the functions/methods and their respective parameters.
 - disable_ap()
 - edit_apgroup() (supported with controller versions 6.0.X and higher)
 - edit_client_fixedip()
+- edit_client_name()
 - edit_firewallgroup()
 - edit_usergroup()
 - extend_guest_validity()

examples/test_connection.php

@@ -29,24 +29,25 @@ $ch = curl_init();
 if (is_resource($ch) || is_object($ch)) {
     /**
      * If we have a resource or object (for PHP > 8.0), we proceed and set the required cURL options
-     */
-    curl_setopt($ch, CURLOPT_URL, $controllerurl);
-    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
-    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
-    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
-
-    /**
-     * This cURL option can have a value of 0-6
+     *
+     * NOTES:
+     * The cURL option CURLOPT_SSLVERSION can have a value of 0-6
      * see this URL for more details:
      * http://php.net/manual/en/function.curl-setopt.php
      * 0 is the default value and is used by the PHP API client class
      */
-    curl_setopt($ch, CURLOPT_SSLVERSION, 0);
+    $curl_options = [
+        CURLOPT_PROTOCOLS      => CURLPROTO_HTTPS,
+        CURLOPT_URL            => $controllerurl,
+        CURLOPT_CUSTOMREQUEST  => 'GET',
+        CURLOPT_SSL_VERIFYPEER => false,
+        CURLOPT_SSL_VERIFYHOST => false,
+        CURLOPT_VERBOSE        => true,
+        CURLOPT_SSLVERSION     => 0,
+        CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
+    ];
 
-    /**
-     * Be more verbose
-     */
-    curl_setopt($ch, CURLOPT_VERBOSE, true);
+    curl_setopt_array($ch, $curl_options);
 
     /**
      * $results contains the output as returned by the cURL request,

src/Client.php

@@ -24,16 +24,16 @@ class Client
      * private and protected properties
      *
      * NOTE:
-     * do not modify the values here, instead user the constructor or the getter and setter functions/methods
+     * do not modify the values here, instead use the constructor or the getter and setter functions/methods
      */
-    const CLASS_VERSION             = '1.1.72';
+    const CLASS_VERSION = '1.1.74';
     protected $baseurl              = 'https://127.0.0.1:8443';
     protected $user                 = '';
     protected $password             = '';
     protected $site                 = 'default';
     protected $version              = '6.2.26';
     protected $debug                = false;
-    protected $is_loggedin          = false;
+    protected $is_logged_in         = false;
     protected $is_unifi_os          = false;
     protected $exec_retries         = 0;
     protected $cookies              = '';
@@ -60,7 +60,7 @@ class Client
      * @param string $version    optional, the version number of the controller
      * @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 certificate
+     *                           value (false) disables validation of the controller's SSL certificate
      */
     public function __construct($user, $password, $baseurl = '', $site = '', $version = '', $ssl_verify = false)
     {
@@ -85,7 +85,7 @@ class Client
             $this->version = trim($version);
         }
 
-        if ((boolean)$ssl_verify === true) {
+        if ((bool) $ssl_verify === true) {
             $this->curl_ssl_verify_peer = true;
             $this->curl_ssl_verify_host = 2;
         }
@@ -109,7 +109,7 @@ class Client
         /**
          * logout, if needed
          */
-        if ($this->is_loggedin) {
+        if ($this->is_logged_in) {
             $this->logout();
         }
     }
@@ -124,12 +124,11 @@ class Client
         /**
          * skip the login process if already logged in
          */
-        if ($this->is_loggedin === true) {
-            return true;
+        if ($this->update_unificookie()) {
+            $this->is_logged_in = true;
         }
 
-        if ($this->update_unificookie()) {
-            $this->is_loggedin = true;
+        if ($this->is_logged_in === true) {
             return true;
         }
 
@@ -218,8 +217,8 @@ class Client
          * check the HTTP response code
          */
         if ($http_code >= 200 && $http_code < 400) {
-            $this->is_loggedin = true;
-            return $this->is_loggedin;
+            $this->is_logged_in = true;
+            return $this->is_logged_in;
         }
 
         return false;
@@ -277,8 +276,8 @@ class Client
 
         curl_close($ch);
 
-        $this->is_loggedin = false;
-        $this->cookies     = '';
+        $this->is_logged_in = false;
+        $this->cookies      = '';
         return true;
     }
 
@@ -1057,23 +1056,23 @@ class Client
     /**
      * Assign client device to another group
      *
-     * @param string $user_id  id of the user device to be modified
-     * @param string $group_id id of the user group to assign user to
+     * @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
      */
-    public function set_usergroup($user_id, $group_id)
+    public function set_usergroup($client_id, $group_id)
     {
         $payload = ['usergroup_id' => $group_id];
-        return $this->fetch_results_boolean('/api/s/' . $this->site . '/upd/user/' . trim($user_id), $payload);
+        return $this->fetch_results_boolean('/api/s/' . $this->site . '/upd/user/' . trim($client_id), $payload);
     }
 
     /**
-     * Update client fixedip (using REST)
+     * Update client device fixed IP address (using REST)
      *
-     * @param string $client_id   _id value for the client
-     * @param bool   $use_fixedip determines whether use_fixedip is true or false
+     * @param string $client_id   _id value for the client device
+     * @param bool   $use_fixedip determines whether to enable the fixed IP address or not
      * @param string $network_id  optional, _id value for the network where the ip belongs to
-     * @param string $fixed_ip    optional, IP address, value of client's fixed_ip field
+     * @param string $fixed_ip    optional, IP address, value of client device's fixed_ip field
      * @return array|false returns an array containing a single object with attributes of the updated client on success
      */
     public function edit_client_fixedip($client_id, $use_fixedip, $network_id = null, $fixed_ip = null)
@@ -1101,6 +1100,28 @@ class Client
         return $this->fetch_results('/api/s/' . $this->site . '/rest/user/' . trim($client_id), $payload);
     }
 
+    /**
+     * Update client device name (using REST)
+     *
+     * @param string $client_id  _id value for the client device
+     * @param string $name       name of the client
+     * @return array|false returns an array containing a single object with attributes of the updated client on success
+     */
+    public function edit_client_name($client_id, $name)
+    {
+        if (empty($name)) {
+            return false;
+        }
+
+        $this->curl_method = 'PUT';
+        $payload           = [
+            '_id'  => $client_id,
+            'name' => $name,
+        ];
+
+        return $this->fetch_results('/api/s/' . $this->site . '/rest/user/' . trim($client_id), $payload);
+    }
+
     /**
      * Fetch user groups
      *
@@ -1400,7 +1421,7 @@ class Client
      * NOTES:
      * this is an experimental function, please do not use unless you know exactly what you're doing
      *
-     * @return bool|array|string URL from where the backup file can be downloaded once generated, false upon failure
+     * @return array|bool URL from where the backup file can be downloaded once generated, false upon failure
      */
     public function generate_backup()
     {
@@ -1504,7 +1525,7 @@ class Client
      * @param string       $locale_id _id value of the locale section
      * @param object|array $payload   stdClass object or associative array containing the configuration to apply to the
      *                                site, must be a (partial) object/array structured in the same manner as is
-     *                                returned by list_settings() for section with the the "locale" key. Valid
+     *                                returned by list_settings() for section with the "locale" key. Valid
      *                                timezones can be obtained in Javascript as explained here:
      *                                https://stackoverflow.com/questions/38399465/how-to-get-list-of-all-timezones-in-javascript
      *                                or in PHP using timezone_identifiers_list(). Do not include the _id property, it
@@ -1688,13 +1709,13 @@ class Client
      *
      * @param string $admin_id       _id value of the admin user to assign, can be obtained using the
      *                               list_all_admins() method/function
-     * @param bool   $readonly       optional, whether or not the new admin has readonly
+     * @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 or not the new admin has permissions to
+     * @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 or not the new admin has permissions to
+     * @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
@@ -1740,7 +1761,7 @@ class Client
     }
 
     /**
-     * Fetch wlan_groups
+     * Fetch WLAN groups
      *
      * @return array containing known wlan_groups
      */
@@ -1803,7 +1824,7 @@ class Client
     /**
      * Fetch self
      *
-     * @return array containing information about the logged in user
+     * @return array containing information about the logged-in user
      */
     public function list_self()
     {
@@ -1973,7 +1994,7 @@ class Client
 
         $payload = ['type' => $type];
 
-        if (is_array($cat_filter) && $type == 'by_app') {
+        if (is_array($cat_filter) && $type === 'by_app') {
             $payload['cats'] = $cat_filter;
         }
 
@@ -2528,7 +2549,7 @@ class Client
     }
 
     /**
-     * Create a wlan
+     * Create a WLAN
      *
      * @param string  $name             SSID
      * @param string  $x_passphrase     new pre-shared key, minimal length is 8 characters, maximum length is 63,
@@ -2541,8 +2562,9 @@ class Client
      * @param string  $security         optional, security type (open, wep, wpapsk, wpaeap)
      * @param string  $wpa_mode         optional, wpa mode (wpa, wpa2, ..)
      * @param string  $wpa_enc          optional, encryption (auto, ccmp)
-     * @param boolean $vlan_enabled     optional, enable/disable vlan for this wlan
-     * @param int     $vlan             optional, vlan id
+     * @param boolean $vlan_enabled     optional, enable/disable VLAN for this wlan (is ignored as of 1.1.73)
+     * @param string  $vlan_id          optional, "_id" value  of the VLAN to assign to this WLAN, can be found using
+     *                                  list_networkconf()
      * @param boolean $uapsd_enabled    optional, enable/disable Unscheduled Automatic Power Save Delivery
      * @param boolean $schedule_enabled optional, enable/disable wlan schedule
      * @param array   $schedule         optional, schedule rules
@@ -2561,35 +2583,34 @@ class Client
         $security = 'open',
         $wpa_mode = 'wpa2',
         $wpa_enc = 'ccmp',
-        $vlan_enabled = false,
-        $vlan = null,
+        $vlan_enabled = null,
+        $vlan_id = null,
         $uapsd_enabled = false,
         $schedule_enabled = false,
         $schedule = [],
         $ap_group_ids = null
     ) {
         $payload = [
-            'name'             => $name,
-            'usergroup_id'     => $usergroup_id,
-            'wlangroup_id'     => $wlangroup_id,
+            'name'             => trim($name),
+            'usergroup_id'     => trim($usergroup_id),
+            'wlangroup_id'     => trim($wlangroup_id),
             'enabled'          => $enabled,
             'hide_ssid'        => $hide_ssid,
             'is_guest'         => $is_guest,
-            'security'         => $security,
-            'wpa_mode'         => $wpa_mode,
-            'wpa_enc'          => $wpa_enc,
-            'vlan_enabled'     => $vlan_enabled,
+            'security'         => trim($security),
+            'wpa_mode'         => trim($wpa_mode),
+            'wpa_enc'          => trim($wpa_enc),
             'uapsd_enabled'    => $uapsd_enabled,
             'schedule_enabled' => $schedule_enabled,
             'schedule'         => $schedule,
         ];
 
-        if (!empty($vlan) && $vlan_enabled) {
-            $payload['vlan'] = $vlan;
+        if (!empty($vlan_id)) {
+            $payload['networkconf_id'] = $vlan_id;
         }
 
         if (!empty($x_passphrase) && $security !== 'open') {
-            $payload['x_passphrase'] = $x_passphrase;
+            $payload['x_passphrase'] = trim($x_passphrase);
         }
 
         if (!empty($ap_group_ids) && is_array($ap_group_ids)) {
@@ -2604,9 +2625,8 @@ class Client
      *
      * @param string       $wlan_id the "_id" value for the WLAN which can be found with the list_wlanconf() function
      * @param object|array $payload stdClass object or associative array containing the configuration to apply to the
-     *                              wlan, must be a
-     *                              (partial) object/array structured in the same manner as is returned by
-     *                              list_wlanconf() for the wlan.
+     *                              wlan, must be a (partial) object/array structured in the same manner as is returned
+     *                              by list_wlanconf() for the wlan.
      * @return bool true on success
      */
     public function set_wlansettings_base($wlan_id, $payload)
@@ -2690,7 +2710,7 @@ class Client
 
         $macs    = array_map('strtolower', $macs);
         $payload = [
-            'mac_filter_enabled' => (bool)$mac_filter_enabled,
+            'mac_filter_enabled' => (bool) $mac_filter_enabled,
             'mac_filter_policy'  => $mac_filter_policy,
             'mac_filter_list'    => $macs,
         ];
@@ -3003,15 +3023,15 @@ class Client
         ];
 
         if (!is_null($tunnel_type)) {
-            $payload['tunnel_type'] = (int)$tunnel_type;
+            $payload['tunnel_type'] = (int) $tunnel_type;
         }
 
         if (!is_null($tunnel_medium_type)) {
-            $payload['tunnel_medium_type'] = (int)$tunnel_medium_type;
+            $payload['tunnel_medium_type'] = (int) $tunnel_medium_type;
         }
 
         if (!is_null($vlan)) {
-            $payload['vlan'] = (int)$vlan;
+            $payload['vlan'] = (int) $vlan;
         }
 
         return $this->fetch_results('/api/s/' . $this->site . '/rest/account', $payload);
@@ -3155,7 +3175,7 @@ class Client
      * Fetch access points and other devices under management of the controller (USW and/or USG devices)
      *
      * NOTE:
-     * changed function/method name to fit it's purpose
+     * changed function/method name to fit its purpose
      *
      * @param string $device_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 <device_mac> parameter)
@@ -3590,7 +3610,7 @@ class Client
         /**
          * guard clause to check if logged in when needed
          */
-        if ($login_required && !$this->is_loggedin) {
+        if ($login_required && !$this->is_logged_in) {
             return false;
         }
 
@@ -3817,17 +3837,17 @@ class Client
                 $cookie_crumbs = explode(';', $cookie);
                 foreach ($cookie_crumbs as $cookie_crumb) {
                     if (strpos($cookie_crumb, 'unifises') !== false) {
-                        $this->cookies     = $cookie_crumb;
-                        $this->is_loggedin = true;
-                        $this->is_unifi_os = false;
+                        $this->cookies      = $cookie_crumb;
+                        $this->is_logged_in = true;
+                        $this->is_unifi_os  = false;
 
                         break;
                     }
 
                     if (strpos($cookie_crumb, 'TOKEN') !== false) {
-                        $this->cookies     = $cookie_crumb;
-                        $this->is_loggedin = true;
-                        $this->is_unifi_os = true;
+                        $this->cookies      = $cookie_crumb;
+                        $this->is_logged_in = true;
+                        $this->is_unifi_os  = true;
 
                         break;
                     }
@@ -3843,7 +3863,7 @@ class Client
      *
      * @param string       $path    path for the request
      * @param object|array $payload optional, payload to pass with the request
-     * @return bool|array|string response returned by the controller API, false upon error
+     * @return bool|string response returned by the controller API, false upon error
      */
     protected function exec_curl($path, $payload = null)
     {
@@ -3927,7 +3947,7 @@ class Client
         }
 
         /**
-         * fetch the HTTP response code
+         * get the HTTP response code
          */
         $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 
@@ -3935,12 +3955,12 @@ class Client
          * an HTTP response code 401 (Unauthorized) indicates the Cookie/Token has expired in which case
          * re-login is required
          */
-        if ($http_code == 401) {
+        if ($http_code === 401) {
             if ($this->debug) {
                 error_log(__FUNCTION__ . ': needed to reconnect to UniFi controller');
             }
 
-            if ($this->exec_retries == 0) {
+            if ($this->exec_retries === 0) {
                 /**
                  * explicitly clear the expired Cookie/Token, update other properties and log out before logging in again
                  */
@@ -3948,8 +3968,8 @@ class Client
                     $_SESSION['unificookie'] = '';
                 }
 
-                $this->is_loggedin = false;
-                $this->cookies     = '';
+                $this->is_logged_in = false;
+                $this->cookies      = '';
                 $this->exec_retries++;
                 curl_close($ch);
 
@@ -3961,7 +3981,7 @@ class Client
                 /**
                  * when re-login was successful, simply execute the same cURL request again
                  */
-                if ($this->is_loggedin) {
+                if ($this->is_logged_in) {
                     if ($this->debug) {
                         error_log(__FUNCTION__ . ': re-logged in, calling exec_curl again');
                     }
@@ -4006,7 +4026,7 @@ class Client
     /**
      * Create and return a new cURL handle
      *
-     * @return object|bool|resource cURL handle (object or resource) upon success, false upon failure
+     * @return object|resource|bool cURL handle (object or resource) upon success, false upon failure
      */
     protected function get_curl_handle()
     {