API client class v1.1.82

- allow filtering by multiple MAC addresses in list_devices(), contributed by @sgrodzicki, #189
API client class v1.1.81
2023-12-18 11:42:56 +01:00 · 2023-12-18 11:11:27 +01:00 · 2023-03-28 12:22:42 +02:00 · 2023-03-28 12:21:43 +02:00 · 2023-03-28 12:19:29 +02:00 · 2022-03-28 11:57:57 +02:00
31 changed files with 635 additions and 219 deletions
--- a/README.md
+++ b/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,27 @@ 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.
+
+> **IMPORTANT NOTE**: cookies are no longer supported with UniFi OS-based controllers. If your application code does use cookies,
+  they will be ignored automatically when working with UniFi OS-based controllers.

 Please test all methods you plan on using thoroughly before using the API Client with
 UniFi OS devices in a production environment.
@@ -128,9 +136,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 +187,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 +358,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

--- a/examples/ap_scanning_state.php
+++ b/examples/ap_scanning_state.php
@@ -28,7 +28,14 @@ $ap_mac  = '<enter MAC address of Access Point to check>';
 * initialize the UniFi API connection class and log in to the controller and do our thing
 * spectrum_scan_state()
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
 $set_debug_mode   = $unifi_connection->set_debug($debug);
 $loginresults     = $unifi_connection->login();
 $data             = $unifi_connection->spectrum_scan_state($ap_mac);
--- a/examples/ap_upgrade_firmware.php
+++ b/examples/ap_upgrade_firmware.php
@@ -24,8 +24,15 @@ $device_mac = '<enter MAC address of device to update>';
 * initialize the UniFi API connection class, log in to the controller
 * (this example assumes you have already assigned the correct values in config.php to the variables used)
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, false);
-$login            = $unifi_connection->login();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$login = $unifi_connection->login();

 /**
 * Run the actual upgrade
--- a/examples/auth_guest_basic.php
+++ b/examples/auth_guest_basic.php
@@ -45,9 +45,16 @@ $site_id = '<enter your site id here>';
 /**
 * initialize the UniFi API connection class and log in to the controller
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();

 /**
 * then we authorize the device for the requested duration
--- a/examples/auth_guest_with_note.php
+++ b/examples/auth_guest_with_note.php
@@ -42,9 +42,16 @@ $note = 'Note to attach to newly authorized device';
 /**
 * initialize the UniFi API connection class and log in to the controller
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();

 /**
 * we authorize the device for the requested duration and attach the note to it's object
--- a/examples/block_list.php
+++ b/examples/block_list.php
@@ -42,9 +42,16 @@ if ($site_id == "MUST_DEFINE_THIS") {
 /**
 * initialize the UniFi API connection class and log in to the controller
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login(); // always true regardless of site id
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login(); // always true regardless of site id

 foreach ($macs_to_block as $mac) {
    // block_result is always true even if mac address does not exist :(
--- a/examples/change_super_mgmt.php
+++ b/examples/change_super_mgmt.php
@@ -25,19 +25,26 @@ $debug   = false;
 /**
 * initialize the UniFi API connection class and log in to the controller and do our thing
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, true);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
-$site_settings    = $unifi_connection->list_settings();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);

-$super_mgmt_settings = [];
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();
+$site_settings  = $unifi_connection->list_settings();
+
+$super_mgmt_settings    = [];
 $super_mgmt_settings_id = '';

 if (!empty($site_settings)) {
-    foreach($site_settings as $section) {
+    foreach ($site_settings as $section) {
        echo 'section key: ' . $section->key . PHP_EOL;
        if ($section->key === 'super_mgmt') {
-            $super_mgmt_settings = $section;
+            $super_mgmt_settings    = $section;
            $super_mgmt_settings_id = $section->_id;
        }
    }
--- a/examples/change_wlan_password.php
+++ b/examples/change_wlan_password.php
@@ -35,10 +35,17 @@ $new_password = '<new password goes here>';
 /**
 * initialize the UniFi API connection class and log in to the controller
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
-$results          = $unifi_connection->set_wlansettings($wlan_id, $new_password);
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();
+$results        = $unifi_connection->set_wlansettings($wlan_id, $new_password);

 /**
 * provide feedback in json format
--- a/examples/create_site.php
+++ b/examples/create_site.php
@@ -30,9 +30,16 @@ $description = 'new site';
 /**
 * initialize the UniFi API connection class and log in to the controller and do our thing
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$loginresults     = $unifi_connection->login();
-$results          = $unifi_connection->create_site($description);
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$loginresults = $unifi_connection->login();
+$results      = $unifi_connection->create_site($description);

 /**
 * provide feedback in json format
--- a/examples/create_voucher.php
+++ b/examples/create_voucher.php
@@ -35,9 +35,16 @@ $site_id = '<enter your site id here>';
 /**
 * initialize the UniFi API connection class and log in to the controller
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();

 /**
 * then we create the required number of vouchers with the requested expiration value
--- a/examples/delete_site.php
+++ b/examples/delete_site.php
@@ -31,9 +31,16 @@ $site_to_delete = '<_id value of the site>';
 /**
 * initialize the UniFi API connection class and log in to the controller and do our thing
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$loginresults     = $unifi_connection->login();
-$results          = $unifi_connection->delete_site($site_to_delete);
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$loginresults = $unifi_connection->login();
+$results      = $unifi_connection->delete_site($site_to_delete);

 /**
 * provide feedback in json format
--- a/examples/disable_device.php
+++ b/examples/disable_device.php
@@ -30,9 +30,16 @@ $site_id = '<enter your site id here>';
 /**
 * initialize the UniFi API connection class and log in to the controller
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();

 /**
 * then we disable the device
--- a/examples/disable_switch_port.php
+++ b/examples/disable_switch_port.php
@@ -46,7 +46,14 @@ $port_conf_id = '<enter _id value of desired port configuration>';
 /**
 * initialize the UniFi API connection class and log in to the controller and do our thing
 */
-$unifi_connection   = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, false);
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
 $set_debug_mode     = $unifi_connection->set_debug($debug);
 $loginresults       = $unifi_connection->login();
 $data               = $unifi_connection->list_devices($device_mac);
--- a/examples/execute_custom_api_request.php
+++ b/examples/execute_custom_api_request.php
@@ -35,10 +35,17 @@ $return         = 'array';
 /**
 * initialize the UniFi API connection class and log in to the controller and do our thing
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
-$results          = $unifi_connection->custom_api_request($url, $request_method, $payload, $return);
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();
+$results        = $unifi_connection->custom_api_request($url, $request_method, $payload, $return);

 /**
 * provide feedback in JSON format or as PHP Object
--- a/examples/extend_guest_auth.php
+++ b/examples/extend_guest_auth.php
@@ -23,9 +23,16 @@ require_once 'config.php';
 $site_id   = "default";
 $site_name = "*enter your site name*";

-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();

 if ($loginresults === 400) {
    print "UniFi controller login failure, please check your credentials in config.php.\n";
@@ -36,7 +43,8 @@ if ($loginresults === 400) {
     * loop thru all known guests
     */
    foreach ($guestlist as $guest) {
-        print "<pre>" . $guest->_id . " (" . $guest->mac . "), valid until " . date(DATE_ATOM, $guest->end) . " (" . $guest->end . ")</pre>";
+        print "<pre>" . $guest->_id . " (" . $guest->mac . "), valid until " .
+              date(DATE_ATOM, $guest->end) . " (" . $guest->end . ")</pre>";

        /**
         * just a sample: only extend validity of guests which have end date after 2017-04-02
--- a/examples/list_alarms.php
+++ b/examples/list_alarms.php
@@ -25,7 +25,14 @@ $site_id = '<enter your site id here>';
 /**
 * initialize the UniFi API connection class and log in to the controller and do our thing
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
 $set_debug_mode   = $unifi_connection->set_debug($debug);
 $loginresults     = $unifi_connection->login();
 $data             = $unifi_connection->list_alarms();
--- a/examples/list_ap_connected_users.php
+++ b/examples/list_ap_connected_users.php
@@ -26,10 +26,17 @@ $site_id = '<enter your site id here>';
 /**
 * initialize the UniFi API connection class and log in to the controller and pull the requested data
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
-$aps_array        = $unifi_connection->list_aps();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();
+$aps_array      = $unifi_connection->list_aps();

 /**
 * output the results in HTML format
--- a/examples/list_connected_users.php
+++ b/examples/list_connected_users.php
@@ -25,10 +25,17 @@ $site_id = '<enter your site id here>';
 /**
 * initialize the UniFi API connection class and log in to the controller and pull the requested data
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
-$clients_array    = $unifi_connection->list_clients();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();
+$clients_array  = $unifi_connection->list_clients();

 /**
 * output the results in JSON format
--- a/examples/list_site_health.php
+++ b/examples/list_site_health.php
@@ -26,14 +26,20 @@ $site_id = '<enter your site id here>';
 /**
 * initialize the UniFi API connection class and log in to the controller and pull the requested data
 */
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);

-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
-$result           = $unifi_connection->list_health();
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();
+$result         = $unifi_connection->list_health();

 /**
 * output the results in correct json formatting
 */
 header('Content-Type: application/json');
-echo (json_encode($result, JSON_PRETTY_PRINT));
+echo(json_encode($result, JSON_PRETTY_PRINT));
--- a/examples/list_sites.php
+++ b/examples/list_sites.php
@@ -26,10 +26,17 @@ $site_id = 'default';
 /**
 * initialize the UniFi API connection class and log in to the controller and do our thing
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
-$data             = $unifi_connection->list_sites();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();
+$data           = $unifi_connection->list_sites();

 /**
 * we can render the full results in json format
--- a/examples/list_social_auth_details.php
+++ b/examples/list_social_auth_details.php
@@ -26,10 +26,17 @@ $site_id = '<enter your site id here>';
 /**
 * initialize the UniFi API connection class and log in to the controller and do our thing
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
-$data             = $unifi_connection->stat_payment();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();
+$data           = $unifi_connection->stat_payment();

 /**
 * cycle through the results and print social auth details if set,
--- a/examples/list_user_stats.php
+++ b/examples/list_user_stats.php
@@ -38,12 +38,19 @@ $attribs = ['rx_bytes', 'tx_bytes'];
 /**
 * initialize the UniFi API connection class and log in to the controller and do our thing
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, true);
-$set_debug_mode   = $unifi_connection->set_debug(false);
-$loginresults     = $unifi_connection->login();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug(false);
+$loginresults   = $unifi_connection->login();
 //$data             = $unifi_connection->stat_5minutes_user($mac, null, null, $attribs);
 //$data             = $unifi_connection->stat_hourly_user($mac, null, null, $attribs);
-$data             = $unifi_connection->stat_daily_user($mac, null, null, $attribs);
+$data = $unifi_connection->stat_daily_user($mac, null, null, $attribs);

 /**
 * provide feedback in json format
--- a/examples/modify_smartpower_pdu_outlet.php
+++ b/examples/modify_smartpower_pdu_outlet.php
@@ -49,39 +49,52 @@ $new_cycle_enabled = false;
 /**
 * initialize the UniFi API connection class and log in to the controller and do our thing
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
-if ($loginresults) {
-    $pdu_details = $unifi_connection->list_devices($pdu_mac);
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);

-    /**
-     * change the model below from USPPDUP to UP1 when using a USP-Plug (thanks to @thesohoguy for contributing this)
-     */
-    if (!empty($pdu_details) && property_exists($pdu_details[0], 'model') && $pdu_details[0]->model === 'USPPDUP' && property_exists($pdu_details[0], 'outlet_overrides')) {
-        $device_id        = $pdu_details[0]->_id;
-        $outlet_overrides = $pdu_details[0]->outlet_overrides;
-
-        foreach ($outlet_overrides as $key => $value) {
-            if ($value->index === $outlet_idx) {
-                $outlet_overrides[$key]->relay_state   = $new_relay_state;
-                $outlet_overrides[$key]->cycle_enabled = $new_cycle_enabled;
-            }
-        }
-
-        $pdu_update = $unifi_connection->set_device_settings_base($device_id, ['outlet_overrides' => $outlet_overrides]);
-
-        /**
-         * provide feedback in json format
-         */
-        echo 'results:' . PHP_EOL . PHP_EOL;
-        echo json_encode($pdu_update, JSON_PRETTY_PRINT);
-        echo PHP_EOL;
-    } else {
-        echo 'not a PDU device?';
-        echo PHP_EOL;
-    }
-} else {
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();
+if (!$loginresults) {
    echo 'we encountered a login error!';
    echo PHP_EOL;
-}
+    exit();
+}
+
+$pdu_details = $unifi_connection->list_devices($pdu_mac);
+
+/**
+ * change the model below from USPPDUP to UP1 when using a USP-Plug (thanks to @thesohoguy for contributing this)
+ */
+if (
+    !empty($pdu_details) &&
+    property_exists($pdu_details[0], 'model') &&
+    $pdu_details[0]->model === 'USPPDUP' &&
+    property_exists($pdu_details[0], 'outlet_overrides')
+) {
+    $device_id        = $pdu_details[0]->_id;
+    $outlet_overrides = $pdu_details[0]->outlet_overrides;
+
+    foreach ($outlet_overrides as $key => $value) {
+        if ($value->index === $outlet_idx) {
+            $outlet_overrides[$key]->relay_state   = $new_relay_state;
+            $outlet_overrides[$key]->cycle_enabled = $new_cycle_enabled;
+        }
+    }
+
+    $pdu_update = $unifi_connection->set_device_settings_base($device_id,
+        ['outlet_overrides' => $outlet_overrides]);
+
+    /**
+     * provide feedback in json format
+     */
+    echo 'results:' . PHP_EOL . PHP_EOL;
+    echo json_encode($pdu_update, JSON_PRETTY_PRINT);
+} else {
+    echo 'not a PDU device?';
+}
+echo PHP_EOL;
--- a/examples/reconnect_client.php
+++ b/examples/reconnect_client.php
@@ -30,9 +30,16 @@ $site_id = '<enter your site id here>';
 /**
 * initialize the UniFi API connection class and log in to the controller
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();

 /**
 * then we force the device to reconnect
--- a/examples/set_vlan_to_port.php
+++ b/examples/set_vlan_to_port.php
@@ -0,0 +1,153 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Samuel Schnelly
+ * description:    example basic PHP script to change VLAN on port
+ */
+
+/**
+ * using the composer autoloader
+ */
+require_once 'vendor/autoload.php';
+
+/**
+ * include the config file (place your credentials etc. there if not already present)
+ * see the config.template.php file for an example
+ */
+require_once 'config.php';
+
+/**
+ * the site to use
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller and do our thing
+ */
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();
+
+/**
+ * change VLAN on port
+ */
+$port = 1;
+$vlan = 200;
+
+/**
+ * MAC Address of the UniFi device
+ */
+$mac = '<enter your device mac address here>';
+
+set_port_vlan($mac, $port, $vlan, $unifi_connection);
+
+/**
+ * Set specific VLAN on device port
+ *
+ * @param string $device_mac MAC Address of UNIFI device
+ * @param int $port_idx Port number of UNIFI device, note: started by 1
+ * @param int $vlan_id VLAN ID to set
+ * @param UniFi_API\Client $unifi_connection
+ *
+ * @return bool true if result is success, false upon failure
+ */
+function set_port_vlan($device_mac, $port_idx, $vlan_id, $unifi_connection)
+{
+    $device = $unifi_connection->list_devices($device_mac);
+
+    // if no device found
+    if (count($device) == 0) {
+        trigger_error('set_port_vlan() device not found');
+        return false;
+    }
+
+    $port_table = $device[0]->port_table;
+    $def_port   = null;
+
+    // check if port exists
+    $exist = false;
+    foreach ($port_table as $key => $port) {
+        if ($port->port_idx == $port_idx) {
+            $exist    = true;
+            $def_port = $port;
+            break;
+        }
+    }
+
+    if (!$exist) {
+        trigger_error('set_port_vlan() port_idx not found on device');
+        return false;
+    }
+
+    // check if vlan exists
+    $native_networkconf_id = null;
+
+    foreach ($unifi_connection->list_networkconf() as $key => $network) {
+        if ($network->purpose == 'vlan-only' && $network->vlan == $vlan_id) {
+            $native_networkconf_id = $network->_id;
+        }
+    }
+
+    if ($native_networkconf_id === null) {
+        trigger_error('set_port_vlan() vlan not exist');
+        return false;
+    }
+
+    $exist = false;
+    foreach ($device[0]->port_overrides as $key => $port) {
+        if ($port->port_idx == $port_idx) {
+            $exist                                                  = true;
+            $device[0]->port_overrides[$key]->native_networkconf_id = $native_networkconf_id;
+            break;
+        }
+    }
+
+    if (!$exist) {
+        $device[0]->port_overrides[] = [
+            'port_idx'                              => isset($port_idx) ? $port_idx : 1,
+            'setting_preference'                    => isset($setting_preference) ? $setting_preference : 'auto',
+            'name'                                  => isset($def_port->name) ? $def_port->name : 'Port 1',
+            'op_mode'                               => isset($def_port->op_mode) ? $def_port->op_mode : 'switch',
+            'port_security_enabled'                 => isset($def_port->port_security_enabled) ? $def_port->port_security_enabled : false,
+            'port_security_mac_address'             => isset($def_port->port_security_mac_address) ? $def_port->port_security_mac_address : [],
+            'native_networkconf_id'                 => isset($native_networkconf_id) ? $native_networkconf_id : '',
+            'excluded_networkconf_ids'              => isset($def_port->excluded_networkconf_ids) ? $def_port->excluded_networkconf_ids : [],
+            'show_traffic_restriction_as_allowlist' => isset($def_port->show_traffic_restriction_as_allowlist) ? $def_port->show_traffic_restriction_as_allowlist : false,
+            'forward'                               => isset($def_port->forward) ? $def_port->forward : 'customize',
+            'lldpmed_enabled'                       => isset($def_port->lldpmed_enabled) ? $def_port->lldpmed_enabled : true,
+            'voice_networkconf_id'                  => isset($def_port->voice_networkconf_id) ? $def_port->voice_networkconf_id : '',
+            'stormctrl_bcast_enabled'               => isset($def_port->stormctrl_bcast_enabled) ? $def_port->stormctrl_bcast_enabled : false,
+            'stormctrl_bcast_rate'                  => isset($def_port->stormctrl_bcast_rate) ? $def_port->stormctrl_bcast_rate : 100,
+            'stormctrl_mcast_enabled'               => isset($def_port->stormctrl_mcast_enabled) ? $def_port->stormctrl_mcast_enabled : false,
+            'stormctrl_mcast_rate'                  => isset($def_port->stormctrl_mcast_rate) ? $def_port->stormctrl_mcast_rate : 100,
+            'stormctrl_ucast_enabled'               => isset($def_port->stormctrl_ucast_enabled) ? $def_port->stormctrl_ucast_enabled : false,
+            'stormctrl_ucast_rate'                  => isset($def_port->stormctrl_ucast_rate) ? $def_port->stormctrl_ucast_rate : 100,
+            'egress_rate_limit_kbps_enabled'        => isset($def_port->egress_rate_limit_kbps_enabled) ? $def_port->egress_rate_limit_kbps_enabled : false,
+            'autoneg'                               => isset($def_port->autoneg) ? $def_port->autoneg : true,
+            'isolation'                             => isset($def_port->isolation) ? $def_port->isolation : false,
+            'stp_port_mode'                         => isset($def_port->stp_port_mode) ? $def_port->stp_port_mode : true,
+            'port_keepalive_enabled'                => isset($def_port->port_keepalive_enabled) ? $def_port->port_keepalive_enabled : false
+        ];
+
+    }
+
+    $payload = [
+        'port_overrides' => $device[0]->port_overrides
+    ];
+
+    $result = $unifi_connection->set_device_settings_base($device[0]->device_id, $payload);
+
+    if ($result) {
+        return true;
+    }
+
+    return false;
+}
--- a/examples/toggle_led.php
+++ b/examples/toggle_led.php
@@ -31,9 +31,16 @@ $mac = '<enter MAC address of your AP here>';
 /**
 * initialize the UniFi API connection class and log in to the controller to do our thing
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion); // initialize the class instance
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();

 /**
 * using the new method/function
--- a/examples/unblock_list.php
+++ b/examples/unblock_list.php
@@ -43,9 +43,16 @@ if ($site_id == "MUST_DEFINE_THIS") {
 /**
 * initialize the UniFi API connection class and log in to the controller
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login(); // always true regardless of site id
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login(); // always true regardless of site id

 foreach ($macs_to_unblock as &$mac) {
    // block_result is always true even if mac address does not exist :(
--- a/examples/update_ac-iw_ports.php
+++ b/examples/update_ac-iw_ports.php
@@ -47,11 +47,11 @@ $port_conf_id_port_2 = '<_id of port configuration to apply to port #2>';
 $new_ports_config = [
    'port_overrides' => [
        [
-            'port_idx' => 1,
+            'port_idx'    => 1,
            'portconf_id' => $port_conf_id_port_1
        ],
        [
-            'port_idx' => 2,
+            'port_idx'    => 2,
            'portconf_id' => $port_conf_id_port_2
        ]
    ]
@@ -60,12 +60,19 @@ $new_ports_config = [
 /**
 * initialize the UniFi API connection class and log in to the controller and do our thing
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, false);
-$set_debug_mode   = $unifi_connection->set_debug(false);
-$loginresults     = $unifi_connection->login();
-$data             = $unifi_connection->list_devices($device_mac);
-$device_id        = $data[0]->device_id;
-$update_device    = $unifi_connection->set_device_settings_base($device_id, $new_ports_config);
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug(false);
+$loginresults   = $unifi_connection->login();
+$data           = $unifi_connection->list_devices($device_mac);
+$device_id      = $data[0]->device_id;
+$update_device  = $unifi_connection->set_device_settings_base($device_id, $new_ports_config);

 if (!$update_device) {
    $error = $unifi_connection->get_last_results_raw();
--- a/examples/update_device_wlan_settings_5.5.X.php
+++ b/examples/update_device_wlan_settings_5.5.X.php
@@ -51,22 +51,29 @@ $na_channel = 44;
 /**
 * initialize the UniFi API connection class and log in to the controller and do our thing
 */
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, false);
-$set_debug_mode   = $unifi_connection->set_debug(false);
-$loginresults     = $unifi_connection->login();
-$data             = $unifi_connection->list_devices($ap_mac);
-$radio_table      = $data[0]->radio_table;
-$device_id        = $data[0]->device_id;
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug(false);
+$loginresults   = $unifi_connection->login();
+$data           = $unifi_connection->list_devices($ap_mac);
+$radio_table    = $data[0]->radio_table;
+$device_id      = $data[0]->device_id;

 foreach ($radio_table as $radio) {
    if ($radio->radio === 'ng') {
        $radio->tx_power_mode = $ng_tx_power_mode;
-        $radio->channel = $ng_channel;
+        $radio->channel       = $ng_channel;
    }

    if ($radio->radio === 'na') {
        $radio->tx_power_mode = $na_tx_power_mode;
-        $radio->channel = $na_channel;
+        $radio->channel       = $na_channel;
    }
 }

--- a/examples/update_switch_poe-mode.php
+++ b/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.
 */

 /**
@@ -39,20 +42,21 @@ $lanports = [6];
 /**
 * This is the function that reads out the current port configuration and changes the value for the poe_mode for the ports defined in $lanports
 */
-function update_ports($running_config, $ports, $poe_mode){
+function update_ports($running_config, $ports, $poe_mode)
+{
    /**
     * Update already non-default ports
     */
    $running_config_count = count($running_config);
-    for($i = 0; $i < $running_config_count; $i++){
-        if(in_array($running_config[$i]->port_idx, $ports)){
+    for ($i = 0; $i < $running_config_count; $i++) {
+        if (in_array($running_config[$i]->port_idx, $ports)) {
            $running_config[$i]->poe_mode = $poe_mode;
            unset($ports[array_search($running_config[$i]->port_idx, $ports)]);
        }
    }

    $add_conf = [];
-    foreach($ports as $port){
+    foreach ($ports as $port) {
        $add_conf[] = [
            'port_idx' => $port,
            'poe_mode' => $poe_mode
@@ -62,12 +66,19 @@ function update_ports($running_config, $ports, $poe_mode){
    return array_merge($running_config, $add_conf);
 }

-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, false);
-$set_debug_mode   = $unifi_connection->set_debug(false);
-$loginresults     = $unifi_connection->login();
-$data             = $unifi_connection->list_devices($device_mac);
-$device_id        = $data[0]->device_id;
-$current_conf     = $data[0]->port_overrides;
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug(false);
+$loginresults   = $unifi_connection->login();
+$data           = $unifi_connection->list_devices($device_mac);
+$device_id      = $data[0]->device_id;
+$current_conf   = $data[0]->port_overrides;

 /**
 * This reads in the values provided via URL or in the command line, if nothing is set than it will poe_mode will be set to "auto"
@@ -91,4 +102,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);
--- a/src/Client.php
+++ b/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.82
 * @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
@@ -23,25 +23,24 @@ class Client
    /**
     * private and protected properties
     *
-     * NOTE:
-     * do not modify the values here, instead use the constructor or the getter and setter functions/methods
+     * 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.82';
    protected $baseurl              = 'https://127.0.0.1:8443';
    protected $user                 = '';
    protected $password             = '';
    protected $site                 = 'default';
-    protected $version              = '6.2.26';
+    protected $version              = '7.3.76';
    protected $debug                = false;
    protected $is_logged_in         = false;
    protected $is_unifi_os          = false;
    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'];
@@ -100,9 +99,9 @@ class Client
    public function __destruct()
    {
        /**
-         * if $_SESSION['unificookie'] is set, do not log out here
+         * if $_SESSION['unificookie'] is set, do not log out here except when this is a UniFi OS-based controller
         */
-        if (isset($_SESSION['unificookie'])) {
+        if (isset($_SESSION['unificookie']) && !$this->is_unifi_os) {
            return;
        }

@@ -140,9 +139,6 @@ class Client
        }

        $curl_options = [
-            CURLOPT_HEADER => true,
-            CURLOPT_POST   => true,
-            CURLOPT_NOBODY => true,
            CURLOPT_URL    => $this->baseurl . '/',
        ];

@@ -162,7 +158,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 +423,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 +440,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 +480,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 +598,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 +699,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 +713,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 +742,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 +771,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 +800,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 +1055,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,19 +1395,29 @@ class Client
        return $this->fetch_results('/api/s/' . $this->site . '/list/user');
    }

+    /**
+     * List of UniFi devices with a basic subset of properties (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)
+     * @param array|string $device_macs optional, array containing the MAC addresses (lowercase strings) of the devices
+     *                                  to filter by, may also be a (lowercase) string containing a single MAC address
+     * @return array|false an array containing known UniFi device objects (optionally filtered by the <device_macs>
+     *                     parameter), false upon error
     */
-    public function list_devices($device_mac = null)
+    public function list_devices($device_macs = [])
    {
-        if (is_string($device_mac)) {
-            $device_mac = strtolower(trim($device_mac));
-        }
+        $payload = ['macs' => (array) $device_macs];

-        return $this->fetch_results('/api/s/' . $this->site . '/stat/device/' . $device_mac);
+        return $this->fetch_results('/api/s/' . $this->site . '/stat/device', $payload);
    }

    /**
@@ -1422,10 +1455,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 +1478,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 +1726,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 +1735,7 @@ class Client

        $payload = [
            'name'        => trim($name),
-            'email'       => trim($email),
+            'email'       => $email,
            'for_sso'     => $enable_sso,
            'cmd'         => 'invite-admin',
            'role'        => 'admin',
@@ -1869,10 +1916,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 +1955,7 @@ class Client
        $minutes,
        $count = 1,
        $quota = 0,
-        $note = null,
+        $note = '',
        $up = null,
        $down = null,
        $megabytes = null
@@ -1920,7 +1967,7 @@ class Client
            'quota'  => intval($quota),
        ];

-        if (is_string($note)) {
+        if (!empty($note)) {
            $payload['note'] = trim($note);
        }

@@ -2549,7 +2596,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));
    }
@@ -2576,6 +2623,7 @@ class Client
     * @param array   $schedule         optional, schedule rules
     * @param array   $ap_group_ids     optional, array of ap group ids, required for UniFi controller versions 6.0.X
     *                                  and higher
+     * @param array $payload            optional, array of additional parameters (wlan_bands, wpa3_support, etc.)
     * @return bool true on success
     */
    public function create_wlan(
@@ -2594,9 +2642,10 @@ class Client
        $uapsd_enabled = false,
        $schedule_enabled = false,
        $schedule = [],
-        $ap_group_ids = null
+        $ap_group_ids = null,
+        $payload = []
    ) {
-        $payload = [
+        $payload = array_merge($payload,[
            'name'             => trim($name),
            'usergroup_id'     => trim($usergroup_id),
            'wlangroup_id'     => trim($wlangroup_id),
@@ -2609,7 +2658,7 @@ class Client
            'uapsd_enabled'    => $uapsd_enabled,
            'schedule_enabled' => $schedule_enabled,
            'schedule'         => $schedule,
-        ];
+        ]);

        if (!empty($vlan_id)) {
            $payload['networkconf_id'] = $vlan_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;
                    }
Author	SHA1	Message	Date
malle-pietje	e89daaf1a3	API client class v1.1.82 - allow filtering by multiple MAC addresses in list_devices(), contributed by @sgrodzicki, #189	2023-12-18 11:42:56 +01:00
malle-pietje	d66c3ddd75	API client class v1.1.81 - hotfix to address cookie issues in UniFi OS 3.2.7, reported by @tflatebo - fixed minor typos - minor code reformatting of the examples - starting with this release, cookies are no longer supported when connecting to a UniFi OS-based controller - added set_vlan_to_port.php example, contributed by @SamuelSchnelly, #203 - allow additional parameters in `create_wlan()`'s payload, contributed by @sgrodzicki, #191	2023-12-18 11:11:27 +01:00
malle-pietje	9e092f8b85	Merge branch 'master' of github.com:Art-of-WiFi/UniFi-API-client merge for device-basic	2023-03-28 12:22:42 +02:00
Sebastian Grodzicki	e4dc2e273c	Add `stat/device-basic` endpoint (#188 ) Merge to include device-basic endpoint	2023-03-28 12:21:43 +02:00
malle-pietje	67d318ca91	- bumped version to class v1.1.80 - added generate_backup_site() method, contributed by @labo-jad	2023-03-28 12:19:29 +02:00
malle-pietje	cbe89d913c	API client class v1.1.79 - updated README to reflect support for 7.X - `get_last_error_message()` now always returns a string which is empty if no message is available - applied PR #151 in slightly different way for consistency with other similar code sections, contributed by @banakito - changed default argument values in several methods/functions from null to an empty string	2022-03-28 11:57:57 +02:00
malle-pietje	4fe1780e1d	API client class v1.1.78 - fixed `create_radius_account()` method to make Tunnel Type and Medium optional parameters, reported by @CodeByJacob	2022-03-11 13:24:31 +01:00
malle-pietje	61bd2eda0d	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()	2022-03-11 12:08:40 +01:00
malle-pietje	746fb0933c	API client class v1.1.76 - minor changes based on feedback by Scrutinizer - removed use of CURLOPT_NOBODY in login() method - switched to using cURL's default HTTP version	2021-12-29 15:01:12 +01:00