bumped version to 1.1.101

- added a getter method get_cookies_created_at() to return the timestamp when the cookies were created/updated.
  This information can be useful to determine how old the cookies are.
- minor comments clean up

LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016, Art of WiFi
+Copyright (c) 2024, Art of WiFi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,51 +1,82 @@
 ## UniFi Controller API client class
 
-A PHP class that provides access to Ubiquiti's [**UniFi Network Controller**](https://unifi-network.ui.com/) API.
+A PHP class that provides access to Ubiquiti's [**UniFi Network Application**](https://unifi-network.ui.com/) API.
 
-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
+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.
+easy inclusion in your projects. See the [installation instructions](#Installation) below for more details.
+
+## Supported Versions
+
+| Software                             | Versions                                            |
+|--------------------------------------|-----------------------------------------------------|
+| UniFi Network Application/controller | 5.X.X, 6.X.X, 7.X.X, 8.X.X (**8.5.6 is confirmed**) |
+| UniFi OS                             | 3.X, 4.X (**4.1.15 is confirmed**)                  |
+
 
 ## Requirements
 
 - a server with:
-  - PHP 5.5.0 or higher 
+  - PHP **7.4.0** or higher (use version [1.1.83](https://github.com/Art-of-WiFi/UniFi-API-client/releases/tag/v1.1.83) 
+    for PHP 7.3.x and lower)
   - 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
+  - tested on Apache 2.4 with PHP 7.4.27 and cURL 7.60.0 and with PHP 8.3.11 and cURL 7.81.0
 - 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 UniFi Cloud accounts, to access the UniFi Controller API 
-  through this class
+- you **must** use an **account with local access permissions** to access the UniFi Controller API through this class
+- do not use UniFi Cloud accounts and do not enable 2FA for the accounts that you use with this class
+
 
 ## UniFi OS Support
 
-Support for UniFi OS-based controllers has been added as of version 1.1.47:
+Support for UniFi OS-based controllers has been added as of version 1.1.47. These devices/services have been verified
+to work:
 - 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)
+- UniFi Express (UX)
+- UniFi Dream Wall (UDW)
+- UniFi Cloud Gateway Ultra (UCG-Ultra)
+- UniFi CloudKey Enterprise (CK-Enterprise)
+- UniFi Enterprise Fortress Gateway (EFG)
+- Official UniFi Hosting, 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.
+The class automatically detects UniFi OS consoles and adjusts the URLs and several functions/methods accordingly.
 
-> **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.
+UniFi OS-based controllers require you to connect using port **443** instead of **8443** which is used for
+"software-based" controllers. 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.
+
+
+### Remote API access to UniFi OS-based controllers
+When connecting to a UniFi OS-based gateway through the WAN interface, you need to create a specific firewall rule to
+allow this. See this blog post on the Art of WiFi website for more details:
+https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a-udm-pro
+
+The "custom firewall rule" approach described there is the recommended method.
+
+
+## Upgrading from a previous version
+
+When upgrading from a version before **1.1.84**, please:
+- make sure you are using PHP **7.4** or higher
+- test the client with your code for any breaking changes; the class methods now have strict parameter type hints and 
+  response types which can break your code in certain cases where the wrong type is passed or a different response type
+  is expected back
 
-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.
 
+
 ### Composer
 
 The preferred installation method is through [composer](https://getcomposer.org). 
@@ -69,12 +100,16 @@ Or manually add the package to your composer.json file:
 }
 ```
 
-Finally, be sure to include the autoloader in your code:
+Finally, be sure to include the composer autoloader in your code if your framework doesn't already do this for you:
 
 ```php
+/**
+ * load the class using the composer autoloader
+ */
 require_once 'vendor/autoload.php';
 ```
 
+
 ### Git
 
 Execute the following `git` command from the shell in your project directory:
@@ -86,9 +121,13 @@ git clone https://github.com/Art-of-WiFi/UniFi-API-client.git
 When git is done cloning, include the file containing the class like so in your code:
 
 ```php
+/**
+ * load the class directly instead of using the composer autoloader
+ */
 require_once 'path/to/src/Client.php';
 ```
 
+
 ### Download the Release
 
 If you prefer not to use composer or git,
@@ -96,9 +135,13 @@ simply [download the package](https://github.com/Art-of-WiFi/UniFi-API-client/ar
 file, then include the file containing the class in your code like so:
 
 ```php
+/**
+ * load the class directly instead of using the composer autoloader
+ */
 require_once 'path/to/src/Client.php';
 ```
 
+
 ## Example usage
 
 A basic example how to use the class:
@@ -121,6 +164,7 @@ $results          = $unifi_connection->list_alarms(); // returns a PHP array con
 Please refer to the `examples/` directory for some more detailed examples which can be used as a starting point for your
 own PHP code.
 
+
 #### IMPORTANT NOTES:
 
 1. In the above example, `$site_id` is the short site "name" (usually 8 characters long) that is visible in the URL when
@@ -141,15 +185,15 @@ own PHP code.
    [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
 
-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.
+The class currently supports the following functions/methods to access the UniFi Controller API. This list is sorted
+alphabetically. Please refer to the comments in the source code for more details on each of the functions/methods,
+their purpose, and their respective parameters.
 
-- login()
-- logout()
 - adopt_device()
+- advanced_adopt_device()
 - archive_alarm()
 - assign_existing_admin()
 - authorize_guest()
@@ -159,19 +203,18 @@ more details on each of the functions/methods and their respective parameters.
 - check_firmware_update()
 - cmd_stat()
 - count_alarms()
-- create_apgroup() (supported with controller versions 6.0.X and higher)
+- create_apgroup()
 - create_dynamicdns()
 - create_firewallgroup()
 - create_hotspotop()
 - create_network()
 - create_radius_account()
-- create_site()
 - create_user()
 - create_usergroup()
 - create_voucher()
 - create_wlan()
 - custom_api_request()
-- delete_apgroup() (supported with controller versions 6.0.X and higher)
+- delete_apgroup()
 - delete_device()
 - delete_firewallgroup()
 - delete_network()
@@ -180,30 +223,46 @@ more details on each of the functions/methods and their respective parameters.
 - delete_usergroup()
 - delete_wlan()
 - disable_ap()
-- edit_apgroup() (supported with controller versions 6.0.X and higher)
+- disable_wlan()
+- edit_apgroup()
 - edit_client_fixedip()
 - edit_client_name()
 - edit_firewallgroup()
 - edit_usergroup()
 - extend_guest_validity()
-- forget_sta() (supported on controller version 5.9.X and higher)
+- forget_sta()
 - generate_backup()
 - generate_backup_site()
+- get_class_version()
+- get_cookie()
+- 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_site()
 - invite_admin()
 - led_override()
 - list_admins()
-- list_alarms()
 - list_all_admins()
-- list_apgroups() (supported with controller versions 6.0.X and higher)
-- list_aps() (deprecated but still available as alias)
+- list_alarms()
+- list_aps()
 - list_backups()
 - list_clients()
 - list_country_codes()
 - list_current_channels()
 - list_dashboard()
 - list_device_name_mappings()
+- list_device_states()
 - list_devices()
-- list_dpi_stats()
+- list_devices_basic()
 - list_dynamicdns()
 - list_events()
 - list_extension()
@@ -217,38 +276,46 @@ more details on each of the functions/methods and their respective parameters.
 - list_portconf()
 - list_portforward_stats()
 - list_portforwarding()
-- list_radius_accounts() (supported on controller version 5.5.19 and higher)
+- list_radius_accounts()
 - list_radius_profiles()
-- list_rogueaps()
-- list_routing()
 - list_self()
 - list_settings()
 - list_sites()
-- list_tags() (supported on controller version 5.5.19 and higher)
-- list_usergroups()
+- list_tags()
 - list_users()
 - list_wlan_groups()
 - list_wlanconf()
 - locate_ap()
+- login()
+- logout()
 - move_device()
 - power_cycle_switch_port()
 - reboot_cloudkey()
-- reconnect_sta()
 - rename_ap()
-- restart_ap() (deprecated but still available as alias)
-- restart_device()
 - revoke_admin()
 - revoke_voucher()
 - set_ap_radiosettings()
+- set_ap_wlangroup()
+- 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_device_settings_base()
 - set_dynamicdns()
-- set_element_adoption() (supported on controller version 5.13.X and higher)
+- set_element_adoption()
 - set_guestlogin_settings()
 - set_guestlogin_settings_base()
-- set_ips_settings_base() (supported on controller version 5.9.10 and higher)
+- set_ips_settings_base()
+- set_is_unifi_os()
 - set_locate_ap() (deprecated but still available as alias)
 - set_networksettings_base()
 - set_radius_account_base()
+- set_request_method()
+- set_request_timeout()
+- set_site()
 - set_site_connectivity()
 - set_site_country()
 - set_site_guest_access()
@@ -267,28 +334,26 @@ more details on each of the functions/methods and their respective parameters.
 - set_wlansettings()
 - set_wlansettings_base()
 - site_leds()
-- site_ledsoff() (deprecated but still available as alias)
-- site_ledson() (deprecated but still available as alias)
 - spectrum_scan()
 - spectrum_scan_state()
 - start_rolling_upgrade()
-- stat_5minutes_aps() (supported on controller version 5.5.X and higher)
-- stat_5minutes_gateway() (supported on controller version 5.7.X and higher)
-- stat_5minutes_site() (supported on controller version 5.5.X and higher)
-- stat_5minutes_user (supported on controller version 5.7.X and higher)
+- stat_5minutes_aps()
+- stat_5minutes_gateway()
+- stat_5minutes_site()
+- stat_5minutes_user()
 - stat_allusers()
 - stat_auths()
 - stat_client()
 - stat_daily_aps()
-- stat_daily_gateway() (supported on controller version 5.7.X and higher)
+- stat_daily_gateway()
 - stat_daily_site()
-- stat_daily_user() (supported on controller version 5.7.X and higher)
+- stat_daily_user()
 - stat_full_status()
 - stat_hourly_aps()
-- stat_hourly_gateway() (supported on controller version 5.7.X and higher)
+- stat_hourly_gateway()
 - 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_hourly_user()
+- stat_ips_events()
 - stat_monthly_aps()
 - stat_monthly_gateway()
 - stat_monthly_site()
@@ -307,48 +372,27 @@ more details on each of the functions/methods and their respective parameters.
 - upgrade_device()
 - upgrade_device_external()
 
-Other functions, getters/setters:
-
-- get_class_version()
-- 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_site()
-- 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()
 
 ## 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
+[Issues section](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.
 
+
+#### IMPORTANT NOTE:
+When encountering issues with the UniFi API using other libraries, cURL or Postman, please do **not** open an Issue. Such issues will be closed immediately.
+Please use the [Discussions](https://github.com/Art-of-WiFi/UniFi-API-client/discussions) section instead.
+
+
 ## Contribute
 
 If you would like to contribute code (improvements), please open an issue and include
 your code there or else create a pull request.
 
+
 ## Credits
 
 This class is based on the initial work by the following developers:
@@ -358,7 +402,8 @@ This class is based on the initial work by the following developers:
 
 and the API as published by Ubiquiti:
 
-- https://dl.ui.com/unifi/7.0.25/unifi_sh_api
+- https://dl.ui.com/unifi/8.0.26/unifi_sh_api
+
 
 ## Important Disclaimer
 

composer.json

@@ -20,7 +20,7 @@
         }
     ],
     "require": {
-        "php": ">=5.5.0",
+        "php": ">=7.4.0",
         "ext-curl": "*",
         "ext-json": "*"
     },

examples/toggle_auto_update_settings.php

@@ -0,0 +1,69 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example to toggle the site-wide auto upgrade setting on a UniFi controller
+ */
+
+/**
+ * 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
+ *
+ * @var string $controlleruser the user name for access to the UniFi Controller
+ * @var string $controllerpassword the password for access to the UniFi Controller
+ * @var string $controllerurl full url to the UniFi Controller, eg. 'https://
+ * @var string $controllerversion the version of the Controller software, eg. '4.6.6' (must be at least 4.0.0)
+ * @var bool $debug set to true (without quotes) to enable debug output to the browser and the PHP error log
+ */
+require_once('config.php');
+
+/**
+ * site id for the site where settings are to be updated
+ */
+$site_id = 'zzzzz';
+
+/**
+ * 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
+);
+
+$login_results = $unifi_connection->login();
+
+if ($login_results) {
+    /**
+     * we get the current site mgmt settings
+     */
+    $current_site_settings = $unifi_connection->list_settings();
+
+    $mgmt_settings = [];
+    foreach ($current_site_settings as $section) {
+        if ($section->key == 'mgmt') {
+            $mgmt_settings = $section;
+        }
+    }
+
+    /**
+     * toggle the auto upgrade setting and set the auto upgrade hour to 3
+     */
+    $mgmt_settings->auto_upgrade      = !$mgmt_settings->auto_upgrade;
+    $mgmt_settings->auto_upgrade_hour = 3;
+    $mgmt_id                          = $mgmt_settings->_id;
+    $set_result                       = $unifi_connection->set_site_mgmt($mgmt_id, $mgmt_settings);
+
+    echo 'done' . PHP_EOL;
+    exit();
+}
+
+echo 'login failed' . PHP_EOL;