API client class v1.1.75

- updated docblocks to be less USG-specific
- removed content-length header from the logout method, reported by @Olivier6767
- added notes to reflect successful tests with UDR running latest Pre-Release version of the UniFi controller (version 6.5.52)
- added checks in specific cases when using trim() to prevent PHP 8 from throwing an error when the variable is null, submitted by @djchen

README.md

@@ -1,44 +1,51 @@
 ## UniFi Controller API client class
 
-A PHP class that provides access to Ubiquiti's [**UniFi Network Controller**](https://unifi-network.ui.com/) API,
-versions 4.X.X, 5.X.X and 6.X.X of the UniFi Network Controller software are supported (version 6.3.51 has been
-confirmed to work) as well as UniFi OS-based controllers (version 5.12.59 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).
+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).
 
 The package can be installed manually or by using
-composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
+composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for
+easy inclusion in your projects.
 
 ## Requirements
 
-- a server with PHP, version 5.5.0 or higher, and the PHP cURL module installed (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) where the UniFi
-  Controller is running
-- you must use **local accounts**, not UniFi Cloud accounts, to access the UniFi Controller API through this class
+- a server with:
+  - 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 
+  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
 
 ## UniFi OS Support
 
-Support for UniFi OS-based controllers (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 applies strict validation of the URL that is
-passed to the constructor, please adapt your logic to allow URLs without a port suffix when dealing with a UniFi
-OS-based controller.
+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.
 
-Please test all methods you plan on using thoroughly before using the API Client with UniFi OS devices in a production
-environment.
+Please test all methods you plan on using thoroughly before using the API Client with
+UniFi OS devices in a production environment.
 
 ## Installation
 
-Use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client
-class.
+Use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the 
+API client class.
 
 ### Composer
 
-The preferred installation method is through [composer](https://getcomposer.org). Follow
-these [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer
-installed.
+The preferred installation method is through [composer](https://getcomposer.org). 
+Follow these [installation instructions](https://getcomposer.org/doc/00-intro.md) if you don't have composer
+installed already.
 
-Once composer is installed, simply execute this command from the shell in your project directory:
+Once composer is installed, simply execute this command from the shell in your project
+directory:
 
 ```sh
 composer require art-of-wifi/unifi-api-client
@@ -77,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
@@ -115,16 +122,21 @@ own PHP code.
 
    `jl3z2shm` is the short site "name" and the value to assign to $site_id.
 
-2. The last optional parameter that is passed to the constructor in the above example (`true`), enables validation of
+2. The 6th optional parameter that is passed to the constructor in the above example (`true`), enables validation of
    the controller's SSL certificate which is otherwise **disabled** by default. It is **highly recommended** to enable
    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.
+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 each of the functions/methods and their respective parameters.
 
 - login()
 - logout()
@@ -134,10 +146,10 @@ parameters.
 - authorize_guest()
 - block_sta()
 - cancel_rolling_upgrade()
-- cmd_stat()
-- count_alarms()
 - check_controller_update()
 - check_firmware_update()
+- cmd_stat()
+- count_alarms()
 - create_apgroup() (supported with controller versions 6.0.X and higher)
 - create_dynamicdns()
 - create_firewallgroup()
@@ -161,6 +173,7 @@ 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()
@@ -177,8 +190,8 @@ parameters.
 - list_country_codes()
 - list_current_channels()
 - list_dashboard()
-- list_devices()
 - list_device_name_mappings()
+- list_devices()
 - list_dpi_stats()
 - list_dynamicdns()
 - list_events()
@@ -259,24 +272,24 @@ parameters.
 - stat_daily_gateway() (supported on controller version 5.7.X and higher)
 - stat_daily_site()
 - stat_daily_user() (supported on controller version 5.7.X and higher)
+- stat_full_status()
 - stat_hourly_aps()
 - stat_hourly_gateway() (supported on controller version 5.7.X and higher)
 - stat_hourly_site()
 - stat_hourly_user() (supported on controller version 5.7.X and higher)
 - stat_ips_events() (supported on controller version 5.9.10 and higher)
+- stat_monthly_aps()
+- stat_monthly_gateway()
+- stat_monthly_site()
+- stat_monthly_user()
 - stat_payment()
 - stat_sessions()
 - stat_sites()
 - stat_speedtest_results()
 - stat_sta_sessions_latest()
 - stat_status()
-- stat_full_status()
 - stat_sysinfo()
 - stat_voucher()
-- stat_monthly_aps()
-- stat_monthly_gateway()
-- stat_monthly_site()
-- stat_monthly_user()
 - unauthorize_guest()
 - unblock_sta()
 - unset_locate_ap() (deprecated but still available as alias)
@@ -286,38 +299,44 @@ parameters.
 Other functions, getters/setters:
 
 - get_class_version()
-- get_connection_timeout()
 - get_cookie() (renamed from getcookie(), deprecated but still available, use get_cookies() instead)
 - get_cookies()
+- get_curl_connection_timeout()
+- get_curl_http_version()
+- get_curl_method()
+- get_curl_request_timeout()
+- get_curl_request_timeout()
+- get_curl_ssl_verify_host()
+- get_curl_ssl_verify_peer()
 - get_debug()
 - get_is_unifi_os()
 - get_last_error_message()
 - get_last_results_raw()
-- get_request_method()
 - get_site()
-- get_ssl_verify_host()
-- get_ssl_verify_peer()
 - set_connection_timeout()
 - set_cookies()
+- set_curl_http_version()
+- set_curl_request_timeout()
+- set_curl_ssl_verify_host()
+- set_curl_ssl_verify_peer()
 - set_debug()
 - set_is_unifi_os()
 - set_request_method()
+- set_request_timeout()
 - set_site()
-- set_ssl_verify_host()
-- set_ssl_verify_peer()
 
 ## Need help or have suggestions?
 
-There is still work to be done to add functionality and further improve the usability of this class, so all
-suggestions/comments are welcome. Please use the
-GitHub [issue list](https://github.com/Art-of-WiFi/UniFi-API-client/issues) or the Ubiquiti Community
-forums (https://community.ubnt.com/t5/UniFi-Wireless/PHP-class-to-access-the-UniFi-controller-API-updates-and/td-p/1512870)
+There is still work to be done to add functionality and further improve the usability of
+this class, so all suggestions/comments are welcome. Please use the GitHub
+[issue list](https://github.com/Art-of-WiFi/UniFi-API-client/issues) or the Ubiquiti
+Community forums (https://community.ubnt.com/t5/UniFi-Wireless/PHP-class-to-access-the-UniFi-controller-API-updates-and/td-p/1512870)
 to share your suggestions and questions.
 
 ## Contribute
 
-If you would like to contribute code (improvements), please open an issue and include your code there or else create a
-pull request.
+If you would like to contribute code (improvements), please open an issue and include
+your code there or else create a pull request.
 
 ## Credits
 
@@ -328,9 +347,9 @@ 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.2.26/unifi_sh_api
+- https://dl.ui.com/unifi/6.5.55/unifi_sh_api
 
 ## Important Disclaimer
 
-Many of the functions in this API client class are not officially supported by Ubiquiti and as such, may not be
-supported in future versions of the UniFi Controller API.
+Many of the functions in this API client class are not officially supported by Ubiquiti
+and as such, may not be supported in future versions of the UniFi Controller API.

composer.json

@@ -16,7 +16,7 @@
         {
             "name": "Art of WiFi",
             "email": "info@artofowifi.net",
-            "homepage": "http://artofwifi.net"
+            "homepage": "https://artofwifi.net"
         }
     ],
     "require": {

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,