Add reboot_os_console method (#286)

- merged PR #284, contributed by @Jacobtims

.gitignore

@@ -1,2 +1,22 @@
 # Ignore personal config file
-examples/config.php
+/examples/config.php
+
+# ignore accidentally generated vendor directory and composer.lock file, just in case...
+/vendor/
+/composer.lock
+
+# ignore phpdoc files
+/build
+.phpdoc-md
+
+# ignore XML files
+*.xml
+
+# ignore PHPStorm files
+.idea/*
+
+# ignore the TODO list
+TODO.md
+
+# ignore Claude Code files
+CLAUDE*.md

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,147 +1,284 @@
 ## UniFi Controller API client class
 
-A PHP class which provides access to Ubiquiti's **UniFi Controller API**, versions 4.x.x and 5.x.x of the UniFi Controller software are supported (version 5.6.18 has been confirmed to work). It's a standalone version of the class which is used in our API browser tool [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
+[![License](https://img.shields.io/github/license/Art-of-WiFi/UniFi-API-client)](https://github.com/Art-of-WiFi/UniFi-API-client/blob/main/LICENSE)
+[![Packagist Version](https://img.shields.io/packagist/v/art-of-wifi/unifi-api-client)](https://packagist.org/packages/art-of-wifi/unifi-api-client)
+[![Downloads](https://img.shields.io/packagist/dt/art-of-wifi/unifi-api-client)](https://packagist.org/packages/art-of-wifi/unifi-api-client)
+[![PHP Version](https://img.shields.io/packagist/php-v/art-of-wifi/unifi-api-client)](https://packagist.org/packages/art-of-wifi/unifi-api-client)
 
-This class can be installed using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
+A PHP class that provides access to Ubiquiti's [**UniFi Network Application**](https://unifi-network.ui.com/) API.
 
-### Donations
+This class is used by our API Browser tool, which can be found
+[here](https://github.com/Art-of-WiFi/UniFi-API-browser).
 
-If you find this PHP API client class useful and wish to support it's further development, please use the PayPal donate button below. All donations go to the project maintainer.
+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. See the [installation instructions](#Installation) below for more details.
 
-[![Donate](https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=M7TVNVX3Z44VN)
 
-## Methods and functions supported
+## Why use this API client?
 
-The class currently supports the following functions/methods to get/post/put/delete data through the UniFi Controller API:
+- Easy to use: clear docs, comprehensive method coverage, and helpful examples.
-- login()
+- Broad coverage: exposes many UniFi endpoints not (yet) available in the official APIs.
-- logout()
+- Composer-friendly: installable via [Composer](https://getcomposer.org) and works with modern PHP projects.
-- adopt_device()
+- Lightweight and dependency-free: no external libraries required; uses cURL.
-- archive_alarm()
+- Secure: communicates over TLS and supports optional SSL certificate validation.
-- authorize_guest()
+- Flexible and extensible: includes `custom_api_request()` for calling any API endpoint.
-- block_sta()
+- Robust error handling: throws named Exceptions for precise try/catch handling.
-- count_alarms()
+- Actively maintained: regular updates and compatibility with recent UniFi versions.
-- create_hotspotop()
-- create_network()
-- create_radius_account()
-- create_site()
-- create_usergroup()
-- create_voucher()
-- create_wlan()
-- delete_network()
-- delete_radius_account()
-- delete_site()
-- delete_usergroup()
-- delete_wlan()
-- disable_ap()
-- edit_usergroup()
-- extend_guest_validity()
-- led_override()
-- list_admins()
-- list_alarms()
-- list_aps() (deprecated but still available as alias)
-- list_clients()
-- list_current_channels()
-- list_dashboard()
-- list_devices()
-- list_dpi_stats()
-- list_dynamicdns()
-- list_events()
-- list_extension()
-- list_guests()
-- list_health()
-- list_hotspotop()
-- list_known_rogueaps()
-- list_networkconf()
-- list_portconf()
-- list_portforward_stats()
-- list_portforwarding()
-- list_radius_accounts() (supported on controller version 5.5.19 and higher)
-- list_radius_profiles()
-- list_rogueaps()
-- list_self()
-- list_settings()
-- list_sites()
-- list_tags() (supported on controller version 5.5.19 and higher)
-- list_usergroups()
-- list_users()
-- list_wlan_groups()
-- list_wlanconf()
-- locate_ap()
-- power_cycle_switch_port()
-- reconnect_sta()
-- rename_ap()
-- restart_ap()
-- revoke_voucher()
-- set_ap_radiosettings()
-- set_device_settings_base()
-- set_guestlogin_settings()
-- set_locate_ap() (deprecated but still available as alias)
-- set_networksettings_base()
-- set_radius_account_base()
-- set_sta_name()
-- set_sta_note()
-- set_usergroup()
-- set_wlan_mac_filter()
-- 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()
-- stat_allusers()
-- stat_auths()
-- stat_client()
-- stat_5minutes_aps() (supported on controller version 5.5.* and higher)
-- stat_hourly_aps()
-- stat_daily_aps()
-- stat_5minutes_site() (supported on controller version 5.5.* and higher)
-- stat_hourly_site()
-- stat_daily_site()
-- stat_payment()
-- stat_sessions()
-- stat_sites()
-- stat_sta_sessions_latest()
-- stat_status()
-- stat_sysinfo()
-- stat_voucher()
-- unauthorize_guest()
-- unblock_sta()
-- unset_locate_ap() (deprecated but still available as alias)
-- upgrade_device()
-- upgrade_device_external()
 
-Internal functions, getters/setters:
-- set_debug()
-- set_site()
-- set_site()
-- get_site()
-- get_cookie() (renamed from getcookie())
-- get_last_results_raw()
-- get_last_error_message()
 
-Please refer to the source code for more details on the functions/methods and their parameters.
+## Supported Versions
+
+| Software                             | Versions                                                  |
+|--------------------------------------|-----------------------------------------------------------|
+| UniFi Network Application/controller | 5.x, 6.x, 7.x, 8.x, 9.x, 10.x (**10.0.154 is confirmed**) |
+| UniFi OS                             | 3.x, 4.x, 5.x (**5.0.5 is confirmed**)                    |
+
 
 ## Requirements
 
-- a web server with PHP and cURL modules installed (tested on apache2 with PHP Version 5.6.1 and cURL 7.42.1)
+- a server or desktop with:
-- network connectivity between this web server and the server and port (normally TCP port 8443) where the UniFi Controller is running
+  - 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 cURL (`php-curl`) module enabled
+  - direct network connectivity between this server/desktop and the host and port where the UniFi Network Application is
+    running (usually TCP port 8443, port 11443 for UniFi OS Server, or port 443 for UniFi OS consoles)
+- you **must** use an admin **account with local access permissions** to access the API through this class as explained
+  here:  
+  https://artofwifi.net/blog/use-local-admin-account-unifi-api-captive-portal
+- do **not** use UniFi Cloud accounts and do not enable MFA/2FA for the accounts that you use with this class
 
-## Installation ##
 
-You can use **Composer**, **Git** or simply **Download the Release** to install the API client class.
+## UniFi OS Support
 
-### Composer
+Starting from version **1.1.47**, this API client also supports UniFi OS-based controllers. These
+applications/devices/services have been verified to work:
+- UniFi OS Server, announcement [here](https://blog.ui.com/article/introducing-unifi-os-server)
+- 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 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)
+- HostiFi UniFi Cloud Hosting, details [here](https://hostifi.com/unifi)
 
-The preferred method is via [composer](https://getcomposer.org). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.
+The class automatically detects UniFi OS consoles/servers and adjusts URLs and several functions/methods accordingly.
 
-Once composer is installed, simply execute this command from the shell in your project directory:
+UniFi OS-based consoles require you to connect using port **443** while **8443** which is used for
+the self-hosted/software-based controllers. When connecting to **UniFi OS Server**, you are required to use port
+**11443**.
+
+
+### Remote API access to UniFi OS-based gateways
+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 detailed instructions when using the **"Classic"**
+firewall:  
+https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a-udm-pro
+
+See this blog post when using the **Zone-Based firewall** (ZBF):  
+https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a-udm-pro-using-zbf
+
+
+## Upgrading from previous versions
+
+When upgrading from a version before **2.0.0**, please:
+- change your code to use the new Exceptions that are thrown by the class
+- test the client with your code for any breaking changes
+- make sure you are using [Composer](#composer) to install the class because the code is no longer held within a single
+  file
+- see the note [here](#looking-for-version-1xx) regarding the single file version (1.x.x) of the API client
+
+
+## Installation
+
+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, execute this command from the shell in your project directory:
 
 ```sh
 composer require art-of-wifi/unifi-api-client
 ```
 
- Or you can manually add the package to your composer.json file:
+Or manually add the package to your `composer.json` file:
+
+```javascript
+{
+    "require": {
+        "art-of-wifi/unifi-api-client": "^2.0"
+    }
+}
+```
+
+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';
+```
+
+## Example usage
+
+A quick and basic example of how to use the class:
+
+```php
+/**
+ * load the class using the composer autoloader
+ */
+require_once 'vendor/autoload.php';
+
+/**
+ * initialize the UniFi API connection class, log in to the controller and request the alarms collection
+ * (this example assumes you have already assigned the correct values to the variables used)
+ */
+$unifi_connection = new UniFi_API\Client($controller_user, $controller_password, $controller_url, $site_id, $controller_version, true);
+$login            = $unifi_connection->login();
+$results          = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects
+```
+
+
+#### 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
+   managing the site in the UniFi Network Controller. For example, with this URL:
+
+   `https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard`
+
+   `jl3z2shm` is the short site "name" and the value to assign to $site_id.
+
+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
+   visible for **read-only** administrator accounts.
+
+### Code Examples:
+
+More code examples are available in the [`examples/`](examples/) directory.
+
+## Exception handling
+
+The class now throws **Exceptions** for various error conditions instead of using PHP's `trigger_error()` function. This
+allows for more granular error handling in your application code.
+
+You can also choose to catch the `UniFi_API\Exceptions\UnifiApiException` Exception to catch all Exceptions that
+might be thrown by the API Client class.
+
+Here is an example of how to catch each of the Exceptions individually:
+```php
+<?php
+/**
+ * PHP API usage example with Exception handling
+ */
+use UniFi_API\Exceptions\CurlExtensionNotLoadedException;
+use UniFi_API\Exceptions\CurlGeneralErrorException;
+use UniFi_API\Exceptions\CurlTimeoutException;
+use UniFi_API\Exceptions\InvalidBaseUrlException;
+use UniFi_API\Exceptions\InvalidSiteNameException;
+use UniFi_API\Exceptions\JsonDecodeException;
+use UniFi_API\Exceptions\LoginFailedException;
+use UniFi_API\Exceptions\LoginRequiredException;
+
+/**
+ * load the class using the composer autoloader
+ */
+require_once 'vendor/autoload.php';
+
+/**
+ * include the config file (place your credentials etc. there if not already present)
+ */
+require_once 'config.php';
+
+/**
+ * initialize the UniFi API connection class, log in to the controller and request the alarms collection
+ * (this example assumes you have already assigned the correct values to the variables in config.php)
+ */
+try {
+    $unifi_connection = new UniFi_API\Client($controller_user, $controller_password, $controller_url, $site_id, $controller_version, true);
+    $login            = $unifi_connection->login();
+    $results          = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects
+} catch (CurlExtensionNotLoadedException $e) {
+    echo 'CurlExtensionNotLoadedException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidBaseUrlException $e) {
+    echo 'InvalidBaseUrlException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidSiteNameException $e) {
+    echo 'InvalidSiteNameException: ' . $e->getMessage(). PHP_EOL;
+} catch (JsonDecodeException $e) {
+    echo 'JsonDecodeException: ' . $e->getMessage(). PHP_EOL;
+} catch (LoginRequiredException $e) {
+    echo 'LoginRequiredException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlGeneralErrorException $e) {
+    echo 'CurlGeneralErrorException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlTimeoutException $e) {
+    echo 'CurlTimeoutException: ' . $e->getMessage(). PHP_EOL;
+} catch (LoginFailedException $e) {
+    echo 'LoginFailedException: ' . $e->getMessage(). PHP_EOL;
+} catch (Exception $e) {
+    /** catch any other Exceptions that might be thrown */
+    echo 'General Exception: ' . $e->getMessage(). PHP_EOL;
+}
+```
+
+Although the PHP DocBlocks for most public methods/functions contain `@throws Exception`, it is recommended to catch
+specific Exceptions that can be thrown by the API Client class to provide more detailed error messages to your
+application code.
+
+In most cases, the class will let Exceptions bubble up to the calling code, but in some cases it will catch them and
+throw a new Exception with a more specific message.
+
+The `list_alarms.php` example in the `examples/` directory is a good starting point to see how you can implement
+Exception handling.
+
+
+## Functions/methods supported
+
+The class currently supports a large and growing number of functions/methods to access the UniFi Controller API. 
+Please refer to the comments/PHP DocBlocks in the source code for more details on each of the functions/methods,
+their purpose, and their respective parameters.
+
+If you are using an advanced IDE such as PHPStorm or VS Code, you can use its code completion and other
+features to explore the available functions/methods thanks to the extensive PHP DocBlocks throughout the code.
+
+For a quick overview of the available functions/methods, you can also check the API Reference here:  
+[API Reference](API_REFERENCE.md)
+
+
+## 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
+[Issues section](https://github.com/Art-of-WiFi/UniFi-API-client/issues) or the Ubiquiti
+Community forums (https://community.ui.com/questions/PHP-client-class-to-access-the-UniFi-controller-API-updates-and-discussion-part-2/a793904e-6023-4a7f-bcae-340db2a03fc1)
+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.
+
+
+## Looking for version 1.x.x?
+
+With versions 1.x.x of the API client, the entire client was contained within a single file which can be useful in
+specific cases.
+This has changed with version 2.0.0 where the code is now split across multiple files and inclusion in your project is
+managed using composer.
+
+If you are looking for the version 1.x.x code, you can tell composer to install that version by using the following
+syntax in your `composer.json` file:
 
 ```javascript
 {
@@ -151,83 +288,43 @@ composer require art-of-wifi/unifi-api-client
 }
 ```
 
-Finally, be sure to include the autoloader in your code:
+Alternatively, you can download the latest 1.x.x code from the [releases page](https://github.com/Art-of-WiFi/UniFi-API-client/releases).
 
-```php
+Whenever necessary, we will make sure to update the **version_1** branch with the latest 1.x.x code.
-require_once('vendor/autoload.php');
-```
 
-### Git
-
-Execute the following `git` command from the shell in your project directory:
-
-```sh
-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
-require_once('path/to/src/Client.php');
-```
-
-### Download the Release
-
-If you prefer not to use composer or git, you can simply [download the package](https://github.com/Art-of-WiFi/UniFi-API-client/archive/master.zip), uncompress the zip file, then include the file containing the class in your code like so:
-
-```php
-require_once('path/to/src/Client.php');
-```
-
-## Example usage
-
-A basic example how to use the class:
-
-```php
-/**
- * load the class using the composer autoloader
- */
-require_once('vendor/autoload.php');
-
-/**
- * initialize the Unifi API connection class, log in to the controller and request the alarms collection
- * (this example assumes you have already assigned the correct values to the variables used)
- */
-$unifi_connection = new UniFi_API\Client($controller_user, $controller_password, $controller_url, $site_id, $controller_version, true);
-$login            = $unifi_connection->login();
-$results          = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects
-```
-
-Please refer to the `examples/` directory for some more detailed examples which you can use as a starting point for your own PHP code.
-
-### IMPORTANT NOTES:
-
-In the example above, the last parameter (`true`) that is passed to the constructor, 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, and which is associated with the FQDN of the server as used in the `controller_url` parameter. This option was added with API client version 1.1.16.
-
----
-
-In the example above, `$site_id` is the 8 character short site "name" which is visible in the URL when managing the site in the UniFi Controller:
-
-`https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard`
-
-In this case, `jl3z2shm` is the value required for $site_id.
-
-## Need help or have suggestions?
-
-There is still work to be done to add functionality and improve the usability of this class, so all suggestions/comments are welcome. Please use the github [issue](https://github.com/Art-of-WiFi/UniFi-API-client/issues) list 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 ideas/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.
 
 ## Credits
 
-This class is largely based on the work done by the following developers:
+This class is based on the initial work by the following developers:
-- domwo: http://community.ubnt.com/t5/UniFi-Wireless/little-php-class-for-unifi-api/m-p/603051
+
+- domwo: https://community.ui.com/questions/little-php-class-for-unifi-api/933d3fb3-b401-4499-993a-f9af079a4a3a
 - fbagnol: https://github.com/fbagnol/class.unifi.php
-- and the API as published by Ubiquiti: https://dl.ubnt.com/unifi/5.6.18-8261dc5066/unifi_sh_api
+
+and the API as published by Ubiquiti:
+
+- https://dl.ui.com/unifi/8.6.9/unifi_sh_api
+
+## Contributors
+
+A big thanks to all the contributors who have helped with this project!
+
+[![Contributors](https://img.shields.io/github/contributors/Art-of-WiFi/UniFi-API-client)](https://github.com/Art-of-WiFi/UniFi-API-client/graphs/contributors)
+
+If you would like to contribute to this project, please open an issue and include
+your suggestions or code there or else create a pull request.
+
+
+## About Art of WiFi
+
+Art of WiFi develops software and tools that enhance the capabilities of UniFi networks. From captive portals and
+reporting solutions to device search utilities, our goal is to make UniFi deployments more powerful and easier to
+manage.
+
+If you're looking for a specific solution or just want to see what else we offer, feel free to explore our web site:
+- https://www.artofwifi.net
+
 
 ## Important Disclaimer
 
-Many of the functions in this API client class are not officially supported by UBNT 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

@@ -1,27 +1,29 @@
 {
-    "name": 		"art-of-wifi/unifi-api-client",
+    "name": "art-of-wifi/unifi-api-client",
-    "type": 		"library",
+    "type": "library",
-    "description": 	"API client class for use with Ubiquiti's UniFi controller",
+    "description": "API client class for use with Ubiquiti's UniFi controller",
     "keywords": [
-		"ubnt",
+        "ubnt",
-		"ubiquiti",
+        "ubiquiti",
-		"unifi",
+        "unifi",
-		"controller",
+        "controller",
-		"api",
+        "api",
-		"client"
+        "client",
-	],
+        "unifi os"
-    "homepage": 	"https://github.com/Art-of-WiFi/UniFi-API-client",
+    ],
-    "license": 		"MIT",
+    "homepage": "https://github.com/Art-of-WiFi/UniFi-API-client",
+    "license": "MIT",
     "authors": [
         {
-            "name": 	"Art of WiFi",
+            "name": "Art of WiFi",
-            "email": 	"info@artofowifi.net",
+            "email": "info@artofowifi.net",
-            "homepage": "http://artofwifi.net"
+            "homepage": "https://artofwifi.net"
         }
     ],
     "require": {
-        "php": ">=5.4.0",
+        "php": ">=7.4.0",
-		"ext-curl": "*"
+        "ext-curl": "*",
+        "ext-json": "*"
     },
     "autoload": {
         "psr-4": {

examples/README.md

@@ -1,14 +1,32 @@
 ## API client class usage examples
-This directory contains some PHP code examples which demonstrate usage of the PHP API client class and can be used as a good starting point for your own custom code.
+
+This directory contains some PHP code examples which demonstrate usage of the PHP API client class and can be used as a
+good starting point for your own custom code.
 
 ### Usage
 
-Copy the appropriate example file to your working directory together with a copy of the config.template.php file which should be renamed to config.php.
+Copy the appropriate example file to your working directory together with a copy of the config.template.php file which
-Then update the contents of your new config.php with your controller details and credentials and modify the example file as required to fit your needs.
+should be renamed to config.php. Then update the contents of your new config.php with your controller details and
+credentials and modify the example file as required to fit your needs.
+
+Also make sure to update the path for the composer autoloader file (`vendor/autoload.php`) or the file containing the
+Class itself (`src/Client.php`) in your `require_once()` statement as required.
+
+#### Executing scripts from the CLI
+
+Most of the included example scripts can be run from the CLI or shell as follows after the necessary credentials and
+parameters have been added or updated:
+
+```sh
+$ php list_site_health.php
+```
+
+NOTE: this does require the `php-cli` module to be installed
 
 ### Contribute
 
-If you would like to share your own example file(s), please open an issue and include your code there or else create a pull request.
+If you would like to share your own example file(s), please open an issue and include your code there or else create a
+pull request.
 
 ## Important Disclaimer
 

examples/ap_scanning_state.php

@@ -3,22 +3,23 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to fetch an Access Point's scanning state/results
+ * description:    example basic PHP script to fetch an Access Point's scanning state/results
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * site id and MAC address of AP to query
+ * https://github.com/Art-of-WiFi/UniFi-API-client#important-notes
  */
 $site_id = '<enter your site id here>';
 $ap_mac  = '<enter MAC address of Access Point to check>';
@@ -27,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);

examples/ap_upgrade_firmware.php

@@ -0,0 +1,45 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: @4oo4
+ * description:    example script to upgrade device firmware (can be scheduled with systemd/cron)
+ *                 to the most current version
+ */
+require_once 'vendor/autoload.php';
+require_once 'config.php';
+
+/**
+ * site id of the AP to update
+ * https://github.com/Art-of-WiFi/UniFi-API-client#important-notes
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * device MAC address formatted with colons, e.g. 'de:ad:be:ef:01:23'
+ */
+$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
+);
+
+$login = $unifi_connection->login();
+
+/**
+ * Run the actual upgrade
+ */
+$results = $unifi_connection->upgrade_device($device_mac);
+
+/**
+ * provide feedback in json format from $response given by upgrade_device();
+ */
+echo json_encode($results, JSON_PRETTY_PRINT);

examples/auth_guest_basic.php

@@ -3,25 +3,35 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to perform a basic auth of a guest device
+ * description:    example PHP script to perform a basic auth of a guest device
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * the MAC address of the device to authorize
  */
 $mac = '<enter MAC address of guest device to auth>';
 
+/**
+ * the MAC address of the Access Point the guest is currently connected to, enter null (without quotes)
+ * if not known or unavailable
+ *
+ * NOTE:
+ * although the AP MAC address is not a required parameter for the authorize_guest() function,
+ * adding this parameter will speed up the initial authorization process
+ */
+$ap_mac = '<enter MAC address of Access Point>';
+
 /**
  * the duration to authorize the device for in minutes
  */
@@ -35,14 +45,21 @@ $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);
+$unifi_connection = new UniFi_API\Client(
-$set_debug_mode   = $unifi_connection->set_debug($debug);
+    $controlleruser,
-$loginresults     = $unifi_connection->login();
+    $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
  */
-$auth_result = $unifi_connection->authorize_guest($mac, $duration);
+$auth_result = $unifi_connection->authorize_guest($mac, $duration, null, null, null, $ap_mac);
 
 /**
  * provide feedback in json format

examples/auth_guest_with_note.php

@@ -3,19 +3,21 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to auth a guest device and attach a note to it
+ * description:    example basic PHP script to auth a guest device and attach a note to it,
+ *                 this requires the device to be connected to the WLAN/LAN at moment of
+ *                 authorization
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * the MAC address of the device to authorize
@@ -40,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);
+$unifi_connection = new UniFi_API\Client(
-$set_debug_mode   = $unifi_connection->set_debug($debug);
+    $controlleruser,
-$loginresults     = $unifi_connection->login();
+    $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

examples/block_list.php

@@ -0,0 +1,90 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: @malcolmcif, based on another Art of WiFi example
+ * description:    basic PHP script to block a list of mac addresses passed in via command line,
+ *                 output is to console in non json format
+ *
+ * usage:
+ *  php block_list.php <list of comma seperated mac addresses>
+ *
+ * example:
+ *  php block_list.php 09:09:09:09:09:09,10:10:10:10:10:10
+ */
+
+/**
+ * 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';
+$debug = false;
+
+/**
+ * the MAC address(es) of the device(s) to block
+ */
+$macs_to_block = explode(',', $argv[1]);
+
+/**
+ * The site to authorize the device with
+ */
+$site_id = 'MUST_DEFINE_THIS';
+if ($site_id == "MUST_DEFINE_THIS") {
+    print 'ERROR: set the site id in your script';
+    return;
+}
+
+/**
+ * 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
+
+foreach ($macs_to_block as $mac) {
+    // block_result is always true even if mac address does not exist :(
+    $block_result = $unifi_connection->block_sta($mac);
+
+    /**
+     * NOTE:
+     * during testing I had some strange behavior where clients were not reconnecting to the network correctly,
+     * they appeared unblocked and received a valid IP address but could not actually get any data.
+     * the clients did not come to life until I disabled the SSID and then re enabled it.
+     * I guessed maybe these commands were occurring too quickly for the controller so I have slowed them down;
+     * since introducing the sleep I have not seen the above behavior so it might be fixed
+     */
+    sleep(1);
+
+    $getid_result = $unifi_connection->stat_client($mac);
+
+    if (property_exists($getid_result[0], "oui")) {
+        // this field(manufacturer) seems to exist on valid mac addresses
+        if (property_exists($getid_result[0], "name")) {
+            // this is the alias field if it has been defined
+            $name = $getid_result[0]->name;
+        } else {
+            $name = $getid_result[0]->hostname;
+        }
+        print 'blocked ' . $name . PHP_EOL;
+    } else {
+        print 'ERROR: could not block ' . $mac . PHP_EOL;
+        print '       check mac address is valid and part of your network' . PHP_EOL;
+    }
+}
+
+/**
+ * No json formatted data
+ */
+//echo json_encode($block_result, JSON_PRETTY_PRINT);

examples/change_super_mgmt.php

@@ -0,0 +1,72 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description:    example basic PHP script to modify the super_mgmt settings for UniFi controller and output results
+ *                 in json format
+ */
+
+/**
+ * using the composer autoloader
+ */
+require_once 'vendor/autoload.php';
+
+/**
+ * UniFi controller credentials and the site to use, in this case since we are modifying global settings you can select
+ * any site here that is available on the UniFi controller
+ *
+ * NOTE: in this case you need to enter Super Administrator account credentials in config.php
+ */
+require_once 'config.php';
+$site_id = 'default';
+$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
+);
+
+$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) {
+        echo 'section key: ' . $section->key . PHP_EOL;
+        if ($section->key === 'super_mgmt') {
+            $super_mgmt_settings    = $section;
+            $super_mgmt_settings_id = $section->_id;
+        }
+    }
+}
+
+/**
+ * modify the super_mgmt settings, in this example we only modify the Live Chat settings
+ * uncomment the required new value below:
+ */
+//$super_mgmt_settings->live_chat = 'disabled';
+//$super_mgmt_settings->live_chat = 'enabled';
+$super_mgmt_settings->live_chat = 'super-only';
+
+/**
+ * we echo the parameters which we will be passing to the UniFi controller API
+ */
+echo $super_mgmt_settings_id . PHP_EOL;
+echo json_encode($super_mgmt_settings, JSON_PRETTY_PRINT) . PHP_EOL . PHP_EOL;
+
+$update_results = $unifi_connection->set_super_mgmt_settings_base($super_mgmt_settings_id, $super_mgmt_settings);
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($update_results, JSON_PRETTY_PRINT);

examples/change_wlan_password.php

@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to change the WPA2 password/PSK of a WLAN, returns true on success
+ * description:    example basic PHP script to change the WPA2 password/PSK of a WLAN, returns true on success
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * The site to which the WLAN you want to modify belongs
@@ -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);
+$unifi_connection = new UniFi_API\Client(
-$set_debug_mode   = $unifi_connection->set_debug($debug);
+    $controlleruser,
-$loginresults     = $unifi_connection->login();
+    $controllerpassword,
-$results          = $unifi_connection->set_wlansettings($wlan_id, $new_password);
+    $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

examples/config.template.php

@@ -1,10 +1,8 @@
 <?php
 /**
- * Copyright (c) 2017, Art of WiFi
+ * Copyright (c) 2021, Art of WiFi
- *
- * This file is subject to the MIT license that is bundled
- * with this package in the file LICENSE.md
  *
+ * This file is subject to the MIT license that is bundled with this package in the file LICENSE.md
  */
 
 /**
@@ -15,8 +13,9 @@
  */
 $controlleruser     = ''; // the user name for access to the UniFi Controller
 $controllerpassword = ''; // the password for access to the UniFi Controller
-$controllerurl      = ''; // full url to the UniFi Controller, eg. 'https://22.22.11.11:8443'
+$controllerurl      = ''; // full url to the UniFi Controller, eg. 'https://22.22.11.11:8443', for UniFi OS-based
-$controllerversion  = ''; // the version of the Controller software, eg. '4.6.6' (must be at least 4.0.0)
+                          // controllers a port suffix isn't required, no trailing slashes should be added
+$controllerversion  = ''; // the version of the Controller software, e.g. '4.6.6' (must be at least 4.0.0)
 
 /**
  * set to true (without quotes) to enable debug output to the browser and the PHP error log

examples/create_site.php

@@ -0,0 +1,47 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description:    example basic PHP script to create a new site, returns true upon success
+ */
+
+/**
+ * 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 to log in to the controller
+ */
+$site_id = '<short site name of a site the credentials used have access to>';
+
+/**
+ * description of the new site
+ */
+$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);
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($results, JSON_PRETTY_PRINT);

examples/create_voucher.php

@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to create a set of vouchers, returns an array containing the newly created vouchers
+ * description:    example basic PHP script to create a set of vouchers, returns an array containing the newly created vouchers
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * minutes the voucher is valid after activation (expiration time)
@@ -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);
+$unifi_connection = new UniFi_API\Client(
-$set_debug_mode   = $unifi_connection->set_debug($debug);
+    $controlleruser,
-$loginresults     = $unifi_connection->login();
+    $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

examples/delete_site.php

@@ -0,0 +1,48 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description:    example basic PHP script to delete a site, returns true upon success
+ */
+
+/**
+ * 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 to log in to the controller
+ */
+$site_id = '<short site name of a site the credentials used have access to>';
+
+
+/**
+ * the site to delete, must not be the same site as referenced by $site_id
+ */
+$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);
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($results, JSON_PRETTY_PRINT);

examples/disable_device.php

@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to disable/enable a device, returns true upon success
+ * description:    example basic PHP script to disable/enable a device, returns true upon success
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * the 24 character id of the device to disable/enable
@@ -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);
+$unifi_connection = new UniFi_API\Client(
-$set_debug_mode   = $unifi_connection->set_debug($debug);
+    $controlleruser,
-$loginresults     = $unifi_connection->login();
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();
 
 /**
  * then we disable the device
@@ -45,6 +52,6 @@ $disable_result = $unifi_connection->disable_ap($device_id, true);
 //$disable_result = $unifi_connection->disable_ap($device_id, false);
 
 /**
- * provide feedback (the newly created voucher code, without the dash) in json format
+ * provide feedback in json format
  */
 echo json_encode($disable_result, JSON_PRETTY_PRINT);

examples/disable_switch_port.php

@@ -0,0 +1,85 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description:    example PHP script to disable/enable the port of a UniFi switch
+ * note:           Requires controller version 5.5.X or higher. This example assumes an override alreay exists for the desired port.
+ *                 To create a new port override simply append one (similar in structure to $updated_override) as needed to the
+ *                 $existing_overrides array
+ */
+
+/**
+ * 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 to log in to the controller
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * the MAC address of the UniFi switch to re-configure
+ */
+$device_mac = '<enter MAC address>';
+
+/**
+ * index of port to modify/add
+ */
+$port_idx = 24;
+
+/**
+ * port configuration id to apply when enabling/disabling the port
+ *
+ * NOTE:
+ * port configurations are available through list_portconf()
+ */
+$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
+);
+
+$set_debug_mode     = $unifi_connection->set_debug($debug);
+$loginresults       = $unifi_connection->login();
+$data               = $unifi_connection->list_devices($device_mac);
+$device_id          = $data[0]->device_id;
+$existing_overrides = $data[0]->port_overrides;
+
+foreach ($existing_overrides as $key => $value) {
+    if (!empty($value->port_idx) && $value->port_idx === $port_idx) {
+        $updated_override = [
+            'portconf_id' => $port_conf_id,
+            'port_idx'    => $port_idx,
+            'poe_mode'    => $value->poe_mode,
+            'name'        => 'Your-port-name',
+        ];
+
+        $existing_overrides[$key] = $updated_override;
+    }
+}
+
+$payload = [
+    'port_overrides' => $existing_overrides
+];
+
+$update_device = $unifi_connection->set_device_settings_base($device_id, $payload);
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($update_device, JSON_PRETTY_PRINT);

examples/execute_custom_api_request.php

@@ -0,0 +1,54 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description:    example basic PHP script to execute a custom API request using the
+ *                 custom_api_request() function/method
+ */
+
+/**
+ * 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 authorize the device with
+ * https://github.com/Art-of-WiFi/UniFi-API-client#important-notes
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * parameters
+ */
+$url            = '/api/s/' . $site_id . '/stat/fwupdate/latest-version';
+$request_method = 'GET';
+$payload        = null;
+$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);
+
+/**
+ * provide feedback in JSON format or as PHP Object
+ */
+echo json_encode($results, JSON_PRETTY_PRINT);
+//print_r($results);

examples/extend_guest_auth.php

@@ -3,48 +3,77 @@
  * PHP API usage example
  *
  * contributed by: mtotone
- * description: example of how to extend validity of guest authorizations
+ * description:    example of how to extend validity of guest authorizations
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
-// must be adapted to your site!
+/**
+ * must be adapted to your site!
+ */
 $site_id   = "default";
 $site_name = "*enter your site name*";
 
-$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$unifi_connection = new UniFi_API\Client(
-$set_debug_mode   = $unifi_connection->set_debug($debug);
+    $controlleruser,
-$loginresults     = $unifi_connection->login();
+    $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";
+    print "UniFi controller login failure, please check your credentials in config.php.\n";
 } else {
-	$guestlist = $unifi_connection->list_guests();
+    $guestlist = $unifi_connection->list_guests();
-	// print "<pre>"; print_r ($guestlist); print "</pre>";
-	// loop thru all known guests
-	foreach ($guestlist as $guest) {
-		// print "<pre>"; print_r ($guest); print "</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
+    /**
-		if ($guest->end > 1491166482) {
+     * loop thru all known guests
-			// extend clients five times = five days
+     */
-			if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
+    foreach ($guestlist as $guest) {
-			if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
+        print "<pre>" . $guest->_id . " (" . $guest->mac . "), valid until " .
-			if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
+              date(DATE_ATOM, $guest->end) . " (" . $guest->end . ")</pre>";
-			if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
-			if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
-		}
-	}
 
-	$logout_results = $unifi_connection->logout();
+        /**
+         * just a sample: only extend validity of guests which have end date after 2017-04-02
+         */
+        if ($guest->end > 1491166482) {
+            /**
+             * extend clients five times = five days
+             */
+            if (!$unifi_connection->extend_guest_validity($guest->_id)) {
+                print "Extend failed for guest with id " . $guest->_id . "\n";
+            }
+
+            if (!$unifi_connection->extend_guest_validity($guest->_id)) {
+                print "Extend failed for guest with id " . $guest->_id . "\n";
+            }
+
+            if (!$unifi_connection->extend_guest_validity($guest->_id)) {
+                print "Extend failed for guest with id " . $guest->_id . "\n";
+            }
+
+            if (!$unifi_connection->extend_guest_validity($guest->_id)) {
+                print "Extend failed for guest with id " . $guest->_id . "\n";
+            }
+
+            if (!$unifi_connection->extend_guest_validity($guest->_id)) {
+                print "Extend failed for guest with id " . $guest->_id . "\n";
+            }
+        }
+    }
+
+    $logout_results = $unifi_connection->logout();
 }

examples/list_alarms.php

@@ -3,19 +3,34 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to pull current alarms from the UniFi controller and output in json format
+ * description: An example basic PHP script to pull current alarms from the UniFi controller and output in JSON format,
+ *              also demonstrates how to catch exceptions.
  */
+use UniFi_API\Exceptions\CurlExtensionNotLoadedException;
+use UniFi_API\Exceptions\CurlGeneralErrorException;
+use UniFi_API\Exceptions\CurlTimeoutException;
+use UniFi_API\Exceptions\InvalidBaseUrlException;
+use UniFi_API\Exceptions\InvalidSiteNameException;
+use UniFi_API\Exceptions\JsonDecodeException;
+use UniFi_API\Exceptions\LoginFailedException;
+use UniFi_API\Exceptions\LoginRequiredException;
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+require_once 'vendor/autoload.php';
 
 /**
- * include the config file (place your credentials etc. there if not already present)
+ * Include the config file (place your credentials etc. there if not already present), see the config.template.php
- * see the config.template.php file for an example
+ * file for an example.
+ *
+ * @var array $controlleruser
+ * @var array $controllerpassword
+ * @var array $controllerurl
+ * @var array $controllerversion
+ * @var array $debug
  */
-require_once('config.php');
+require_once 'config.php';
 
 /**
  * the site to use
@@ -25,12 +40,40 @@ $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);
+try {
-$set_debug_mode   = $unifi_connection->set_debug($debug);
+    $unifi_connection = new UniFi_API\Client(
-$loginresults     = $unifi_connection->login();
+        $controlleruser,
-$data             = $unifi_connection->list_alarms();
+        $controllerpassword,
+        $controllerurl,
+        $site_id,
+        $controllerversion
+    );
 
-/**
+    $set_debug_mode = $unifi_connection->set_debug($debug);
- * provide feedback in json format
+    $login_results  = $unifi_connection->login();
- */
+    $data           = $unifi_connection->list_alarms();
-echo json_encode($data, JSON_PRETTY_PRINT);
+
+    /**
+     * echo the results in JSON format
+     */
+    echo json_encode($data, JSON_PRETTY_PRINT);
+} catch (CurlExtensionNotLoadedException $e) {
+    echo 'CurlExtensionNotLoadedException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidBaseUrlException $e) {
+    echo 'InvalidBaseUrlException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidSiteNameException $e) {
+    echo 'InvalidSiteNameException: ' . $e->getMessage(). PHP_EOL;
+} catch (JsonDecodeException $e) {
+    echo 'JsonDecodeException: ' . $e->getMessage(). PHP_EOL;
+} catch (LoginRequiredException $e) {
+    echo 'LoginRequiredException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlGeneralErrorException $e) {
+    echo 'CurlGeneralErrorException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlTimeoutException $e) {
+    echo 'CurlTimeoutException: ' . $e->getMessage(). PHP_EOL;
+} catch (LoginFailedException $e) {
+    echo 'LoginFailedException: ' . $e->getMessage(). PHP_EOL;
+} catch (Exception $e) {
+    /** catch any other Exceptions that might be thrown */
+    echo 'General Exception: ' . $e->getMessage(). PHP_EOL;
+}

examples/list_ap_connected_users.php

@@ -3,20 +3,20 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example to pull connected user numbers for Access Points from the Unifi controller and output the results
+ * description:    example to pull connected user numbers for Access Points from the UniFi controller and output the results
- *              in raw HTML format
+ *                 in raw HTML format
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * the short name of the site which you wish to query
@@ -26,17 +26,24 @@ $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(
-$set_debug_mode   = $unifi_connection->set_debug($debug);
+    $controlleruser,
-$loginresults     = $unifi_connection->login();
+    $controllerpassword,
-$aps_array        = $unifi_connection->list_aps();
+    $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
  */
 header('Content-Type: text/html; charset=utf-8');
 foreach ($aps_array as $ap) {
-	if ($ap->type === 'uap') {
+    if ($ap->type === 'uap') {
-		echo '<b>AP name:</b>' . $ap->name . ' <b>model:</b>' . $ap->model . ' <b># connected clients:</b>' . $ap->num_sta . '<br>';
+        echo '<b>AP name:</b>' . $ap->name . ' <b>model:</b>' . $ap->model . ' <b># connected clients:</b>' . $ap->num_sta . '<br>';
-	}
+    }
 }

examples/list_connected_users.php

@@ -0,0 +1,44 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: @gahujipo
+ * description:    example to pull connected users and their details from the UniFi controller and output the results
+ *                 in JSON format
+ */
+/**
+ * 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 short name of the site which you wish to query
+ */
+$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();
+
+/**
+ * output the results in JSON format
+ */
+header('Content-Type: application/json; charset=utf-8');
+echo json_encode($clients_array);

examples/list_site_health.php

@@ -3,20 +3,20 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example to pull site health metrics from the Unifi controller and output the results
+ * description:    example to pull site health metrics from the UniFi controller and output the results
- *              in json format
+ *                 in json format
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * the short name of the site you wish to query
@@ -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);
-$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();
-$loginresults     = $unifi_connection->login();
+$result         = $unifi_connection->list_health();
-$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));

examples/list_sites.php

@@ -0,0 +1,53 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description:    example basic PHP script to list all site on the controller that are
+ *                 available to the admin account defined in config.php
+ */
+
+/**
+ * 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';
+
+/**
+ * we use the default site in the initial connection
+ */
+$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();
+
+/**
+ * we can render the full results in json format
+ */
+//echo json_encode($data, JSON_PRETTY_PRINT);
+
+/**
+ * or we print each site name and site id
+ */
+foreach ($data as $site) {
+    echo 'Site name: ' . $site->desc . ', site id: ' . $site->name . PHP_EOL;
+}
+
+echo PHP_EOL;

examples/list_social_auth_details.php

@@ -3,20 +3,20 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to pull Facebook social auth details from the UniFi controller and output
+ * description:    example basic PHP script to pull Facebook social auth details from the UniFi controller and output
- *              them in basic HTML format
+ *                 them in basic HTML format
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * the site to use
@@ -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);
+$unifi_connection = new UniFi_API\Client(
-$set_debug_mode   = $unifi_connection->set_debug($debug);
+    $controlleruser,
-$loginresults     = $unifi_connection->login();
+    $controllerpassword,
-$data             = $unifi_connection->stat_payment();
+    $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,

examples/list_user_stats.php

@@ -0,0 +1,58 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description:    example basic PHP script to pull stats for s epcific user/client device from the UniFi controller and output in json format
+ */
+
+/**
+ * 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>';
+
+/**
+ * MAC address of client to fetch stats for
+ */
+$mac = '<MAC address>';
+
+/**
+ * array of attributes to collect
+ * valid attributes:
+ * rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets, tx_packets
+ */
+//$attribs = ['rx_bytes', 'tx_bytes', 'signal', 'rx_rate', 'tx_rate', 'rx_retries', 'tx_retries', 'rx_packets', 'tx_packets'];
+$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
+);
+
+$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);
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($data, JSON_PRETTY_PRINT);

examples/modify_smartpower_pdu_outlet.php

@@ -0,0 +1,100 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description:    example basic PHP script to toggle power of an outlet on the UniFi SmartPower PDU Pro,
+ *                 last tested with UniFi controller version 6.1.19
+ */
+require '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 = 'default';
+
+/**
+ * MAC of UniFi SmartPower PDU Pro to work with
+ */
+$pdu_mac = '<MAC ADDRESS of PDU>';
+
+/**
+ * index value of the outlet to modify
+ */
+$outlet_idx = 20;
+
+/**
+ * new values for relay_state (enable/disable Power) and cycle_enabled (disable/enable Modem Power Cycle) for the above outlet,
+ * values must be boolean (true/false)
+ *
+ * NOTES:
+ * - here you can choose to also change the name of the outlet
+ * - outlet overrides are structured like this:
+ *    {
+ *        "index": 1,
+ *        "name": "USB Outlet 1",
+ *        "cycle_enabled": false,
+ *        "relay_state": true
+ *    }
+ */
+$new_relay_state   = true;
+$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) {
+    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;

examples/ppsks_examples/create_ppsk.php

@@ -0,0 +1,131 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to create a new PPSK for a WLAN on the UniFi controller
+ */
+use UniFi_API\Exceptions\CurlExtensionNotLoadedException;
+use UniFi_API\Exceptions\CurlGeneralErrorException;
+use UniFi_API\Exceptions\CurlTimeoutException;
+use UniFi_API\Exceptions\InvalidBaseUrlException;
+use UniFi_API\Exceptions\InvalidSiteNameException;
+use UniFi_API\Exceptions\JsonDecodeException;
+use UniFi_API\Exceptions\LoginFailedException;
+use UniFi_API\Exceptions\LoginRequiredException;
+
+require 'vendor/autoload.php';
+
+/**
+ * Record start time.
+ */
+$start_time = microtime(true);
+
+/**
+ * Include the config file (place your credentials etc. there if not already present),
+ * see the config.template.php file for an example.
+ *
+ * @var array $controller_user
+ * @var array $controller_password
+ * @var array $controller_url
+ * @var array $controller_version
+ * @var array $debug
+ */
+require_once 'config.php';
+
+/**
+ * The id of the site to use.
+ */
+$site_id = 'default';
+
+/**
+ * The new PPSK details.
+ */
+$new_ppsk_password   = 'mysecretppsk'; // the password for the new PPSK, this password must be unique for the SSID, between 8-63 characters
+$new_ppsk_network_id = 'zzzzzzzzzzzzzzzzzzzzz'; // id for the required VLAN, taken from the output of list_networkconf()
+$new_ppsk_wlan_id    = 'xxxxxxxxxxxxxxxxxxxxx'; // id for the required WLAN, taken from the output of list_wlanconf()
+
+try {
+    /**
+     * initialize the UniFi API connection class and log in to the controller and do our thing
+     */
+    $unifi_connection = new UniFi_API\Client(
+        $controller_user,
+        $controller_password,
+        $controller_url,
+        $site_id,
+        $controller_version
+    );
+
+    $request_start_time = microtime(true);
+
+    $set_debug_mode = $unifi_connection->set_debug($debug);
+    $login_results  = $unifi_connection->login();
+    $wlan_conf      = $unifi_connection->list_wlanconf();
+
+    /**
+     * Get the details for the WLAN the PPSK will be created for.
+     */
+    $wlan_details = [];
+
+    foreach ($wlan_conf as $wlan) {
+        if ($wlan->_id === $new_ppsk_wlan_id) {
+            $wlan_details = $wlan;
+
+            break;
+        }
+    }
+
+    if (empty($wlan_details)) {
+        echo 'WLAN not found, exiting... Please check the $new_ppsk_wlan_id value 🤨' . PHP_EOL;
+
+        exit;
+    }
+
+    /**
+     * Create the new PPSK, then append it to the existing PPSKs array.
+     */
+    $new_ppsk = [
+        'password'       => $new_ppsk_password,
+        'networkconf_id' => $new_ppsk_network_id,
+    ];
+
+    $wlan_details->private_preshared_keys[] = $new_ppsk;
+
+    $unifi_connection->set_wlansettings_base($new_ppsk_wlan_id, $wlan_details);
+
+    $request_end_time = microtime(true);
+
+    /**
+     * Record end time.
+     */
+    $end_time = microtime(true);
+
+    /**
+     * Calculate and display the execution time.
+     */
+    $execution_time = $end_time - $start_time;
+
+    echo 'The PPSK has been created successfully!👍' . PHP_EOL;
+
+    echo 'Full execution time: ' . $execution_time . ' seconds' . PHP_EOL;
+    echo 'Time to fetch, process and push data back: ' . ($request_end_time - $request_start_time) . ' seconds' . PHP_EOL;
+} catch (CurlExtensionNotLoadedException $e) {
+    echo 'CurlExtensionNotLoadedException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidBaseUrlException $e) {
+    echo 'InvalidBaseUrlException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidSiteNameException $e) {
+    echo 'InvalidSiteNameException: ' . $e->getMessage(). PHP_EOL;
+} catch (JsonDecodeException $e) {
+    echo 'JsonDecodeException: ' . $e->getMessage(). PHP_EOL;
+} catch (LoginRequiredException $e) {
+    echo 'LoginRequiredException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlGeneralErrorException $e) {
+    echo 'CurlGeneralErrorException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlTimeoutException $e) {
+    echo 'CurlTimeoutException: ' . $e->getMessage(). PHP_EOL;
+} catch (LoginFailedException $e) {
+    echo 'LoginFailedException: ' . $e->getMessage(). PHP_EOL;
+} catch (Exception $e) {
+    echo 'General Exception: ' . $e->getMessage(). PHP_EOL;
+}

examples/ppsks_examples/list_ppsks.php

@@ -0,0 +1,108 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to list all PPSKs for all WLANs in a specific UniFi site
+ */
+
+use UniFi_API\Exceptions\CurlExtensionNotLoadedException;
+use UniFi_API\Exceptions\CurlGeneralErrorException;
+use UniFi_API\Exceptions\CurlTimeoutException;
+use UniFi_API\Exceptions\InvalidBaseUrlException;
+use UniFi_API\Exceptions\InvalidSiteNameException;
+use UniFi_API\Exceptions\JsonDecodeException;
+use UniFi_API\Exceptions\LoginFailedException;
+use UniFi_API\Exceptions\LoginRequiredException;
+
+require 'vendor/autoload.php';
+
+/**
+ * Record start time.
+ */
+$start_time = microtime(true);
+
+/**
+ * Include the config file (place your credentials etc. there if not already present),
+ * see the config.template.php file for an example.
+ *
+ * @var array $controller_user
+ * @var array $controller_password
+ * @var array $controller_url
+ * @var array $controller_version
+ * @var array $debug
+ */
+require_once 'config.php';
+
+/**
+ * The id of the site to use.
+ */
+$site_id = 'default';
+
+try {
+    /**
+     * initialize the UniFi API connection class and log in to the controller and do our thing
+     */
+    $unifi_connection = new UniFi_API\Client(
+        $controller_user,
+        $controller_password,
+        $controller_url,
+        $site_id,
+        $controller_version
+    );
+
+    $request_start_time = microtime(true);
+
+    $set_debug_mode = $unifi_connection->set_debug($debug);
+    $login_results  = $unifi_connection->login();
+    $wlan_conf      = $unifi_connection->list_wlanconf();
+
+    /**
+     * Get the details for the WLAN the PPSK will be created for.
+     */
+    $wlan_details = [];
+
+    foreach ($wlan_conf as $wlan) {
+        /**
+         * Skip this SSID if private_pre_shared_keys is not set or empty.
+         */
+        if (empty($wlan->private_preshared_keys)) {
+            continue;
+        }
+
+        echo json_encode($wlan->private_preshared_keys, JSON_PRETTY_PRINT) . PHP_EOL;
+    }
+
+    $request_end_time = microtime(true);
+
+    /**
+     * Record end time.
+     */
+    $end_time = microtime(true);
+
+    /**
+     * Calculate and display the execution time.
+     */
+    $execution_time = $end_time - $start_time;
+
+    echo 'Full execution time: ' . $execution_time . ' seconds' . PHP_EOL;
+    echo 'Time to fetch, process and push data back: ' . ($request_end_time - $request_start_time) . ' seconds' . PHP_EOL;
+} catch (CurlExtensionNotLoadedException $e) {
+    echo 'CurlExtensionNotLoadedException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidBaseUrlException $e) {
+    echo 'InvalidBaseUrlException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidSiteNameException $e) {
+    echo 'InvalidSiteNameException: ' . $e->getMessage(). PHP_EOL;
+} catch (JsonDecodeException $e) {
+    echo 'JsonDecodeException: ' . $e->getMessage(). PHP_EOL;
+} catch (LoginRequiredException $e) {
+    echo 'LoginRequiredException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlGeneralErrorException $e) {
+    echo 'CurlGeneralErrorException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlTimeoutException $e) {
+    echo 'CurlTimeoutException: ' . $e->getMessage(). PHP_EOL;
+} catch (LoginFailedException $e) {
+    echo 'LoginFailedException: ' . $e->getMessage(). PHP_EOL;
+} catch (Exception $e) {
+    echo 'General Exception: ' . $e->getMessage(). PHP_EOL;
+}

examples/ppsks_examples/remove_ppsk.php

@@ -0,0 +1,141 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to remove a PPSK from a specific UniFi site
+ */
+use UniFi_API\Exceptions\CurlExtensionNotLoadedException;
+use UniFi_API\Exceptions\CurlGeneralErrorException;
+use UniFi_API\Exceptions\CurlTimeoutException;
+use UniFi_API\Exceptions\InvalidBaseUrlException;
+use UniFi_API\Exceptions\InvalidSiteNameException;
+use UniFi_API\Exceptions\JsonDecodeException;
+use UniFi_API\Exceptions\LoginFailedException;
+use UniFi_API\Exceptions\LoginRequiredException;
+
+require 'vendor/autoload.php';
+
+/**
+ * Record start time.
+ */
+$start_time = microtime(true);
+
+$total_removals = 0;
+
+/**
+ * Include the config file (place your credentials etc. there if not already present),
+ * see the config.template.php file for an example.
+ *
+ * @var array $controller_user
+ * @var array $controller_password
+ * @var array $controller_url
+ * @var array $controller_version
+ * @var array $debug
+ */
+require_once 'config.php';
+
+/**
+ * The id of the site to use.
+ */
+$site_id = 'default';
+
+/**
+ * The password value of the PPSK to remove.
+ */
+$ppsk_to_remove = 'mysecretppsk';
+
+try {
+    /**
+     * Initialize the UniFi API connection class and log in to the controller and do our thing.
+     */
+    $unifi_connection = new UniFi_API\Client(
+        $controller_user,
+        $controller_password,
+        $controller_url,
+        $site_id,
+        $controller_version
+    );
+
+    $request_start_time = microtime(true);
+
+    $set_debug_mode = $unifi_connection->set_debug($debug);
+    $login_results  = $unifi_connection->login();
+    $wlan_conf      = $unifi_connection->list_wlanconf();
+
+    foreach ($wlan_conf as $wlan) {
+        /**
+         * Skip this SSID if the private_pre_shared_keys array is not set or empty.
+         */
+        if (empty($wlan->private_preshared_keys)) {
+            continue;
+        }
+
+        $removals = 0;
+
+        foreach ($wlan->private_preshared_keys as $ppsk) {
+            if ($ppsk->password === $ppsk_to_remove) {
+                echo 'Removing PPSK with password: "' . $ppsk_to_remove . '"' . PHP_EOL;
+
+                /**
+                 * Remove the PPSK from the private_preshared_keys array.
+                 */
+                $wlan->private_preshared_keys = array_values(array_filter($wlan->private_preshared_keys, function ($value) use ($ppsk_to_remove) {
+                    return $value->password !== $ppsk_to_remove;
+                }));
+
+                $removals++;
+            }
+        }
+
+        /**
+         * Push the updated WLAN configuration back to the controller if we removed one or more PPSKs.
+         */
+        if ($removals > 0) {
+            echo 'Pushing updated WLAN configuration back to the controller...' . PHP_EOL;
+            $unifi_connection->set_wlansettings_base($wlan->_id, $wlan);
+            $total_removals += $removals;
+        }
+    }
+
+    $request_end_time = microtime(true);
+
+    /**
+     * Record end time.
+     */
+    $end_time = microtime(true);
+
+    /**
+     * Calculate the execution time.
+     */
+    $execution_time = $end_time - $start_time;
+
+    if ($total_removals === 0) {
+        echo 'No PPSKs were removed, exiting...' . PHP_EOL;
+
+        exit;
+    }
+
+    echo 'Total PPSKs removed: ' . $total_removals . PHP_EOL;
+
+    echo 'Full execution time: ' . $execution_time . ' seconds' . PHP_EOL;
+    echo 'Time to fetch, process and push data back: ' . ($request_end_time - $request_start_time) . ' seconds' . PHP_EOL;
+} catch (CurlExtensionNotLoadedException $e) {
+    echo 'CurlExtensionNotLoadedException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidBaseUrlException $e) {
+    echo 'InvalidBaseUrlException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidSiteNameException $e) {
+    echo 'InvalidSiteNameException: ' . $e->getMessage(). PHP_EOL;
+} catch (JsonDecodeException $e) {
+    echo 'JsonDecodeException: ' . $e->getMessage(). PHP_EOL;
+} catch (LoginRequiredException $e) {
+    echo 'LoginRequiredException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlGeneralErrorException $e) {
+    echo 'CurlGeneralErrorException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlTimeoutException $e) {
+    echo 'CurlTimeoutException: ' . $e->getMessage(). PHP_EOL;
+} catch (LoginFailedException $e) {
+    echo 'LoginFailedException: ' . $e->getMessage(). PHP_EOL;
+} catch (Exception $e) {
+    echo 'General Exception: ' . $e->getMessage(). PHP_EOL;
+}

examples/reconnect_client.php

@@ -0,0 +1,52 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description:    example basic PHP script to force a client device to reconnect
+ */
+
+/**
+ * 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 MAC address to reconnect
+ */
+$mac_to_reconnect = '<MAC address>';
+
+/**
+ * site where the above MAC address is connected
+ */
+$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();
+
+/**
+ * then we force the device to reconnect
+ */
+$reconnect_result = $unifi_connection->reconnect_sta($mac_to_reconnect);
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($reconnect_result, JSON_PRETTY_PRINT);

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;
+}

examples/site_provisioning_example/README.md

@@ -0,0 +1,10 @@
+## Site provisioning script
+
+Contributed by @smos
+
+This directory contains an example provisioning script to create a large number of sites with comparable network configurations. It sets the LAN config to site specific configuration. Copy the settings.template.php and config.template.php to their respective files for testing.
+This is meant as a basic provisioning only system. Currently used against controller 5.6.30.
+
+## Important Disclaimer
+
+Use all examples at your own risk!

examples/site_provisioning_example/config.template.php

@@ -0,0 +1,24 @@
+<?php
+/**
+ * Copyright (c) 2017, Art of WiFi
+ *
+ * This file is subject to the MIT license that is bundled
+ * with this package in the file LICENSE.md
+ *
+ */
+
+/**
+ * Controller configuration
+ * ===============================
+ * Copy this file to your working directory, rename it to config.php and update the section below with your UniFi
+ * controller details and credentials
+ */
+$controlleruser     = ''; // the user name for access to the UniFi Controller
+$controllerpassword = ''; // the password for access to the UniFi Controller
+$controllerurl      = ''; // full url to the UniFi Controller, eg. 'https://22.22.11.11:8443'
+$controllerversion  = ''; // the version of the Controller software, eg. '4.6.6' (must be at least 4.0.0)
+
+/**
+ * set to true (without quotes) to enable debug output to the browser and the PHP error log
+ */
+$debug = false;

examples/site_provisioning_example/provision.php

@@ -0,0 +1,396 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: @smos
+ * description: example provisioning script to create a large number of sites with comparable network configurations
+ */
+
+/* include important files */
+require_once('UniFi-API-client/src/Client.php');
+
+/* Set the default timezone */
+date_default_timezone_set('Europe/Amsterdam');
+
+// Example array with site information, includes numeric reference
+$fil_array = array();
+$fil_array[600]['aktief'] = 1; // Active
+$fil_array[600]['kassa_aantal'] = 1; // Cash registers
+$fil_array[600]['divisie_code'] = "D"; // Brand
+$fil_array[600]['corr_woonplaats'] = "Amsterdam"; // City
+
+
+echo "<pre>";
+// Import the controller auth config
+include("config.php");
+
+/**
+ * set to true (without quotes) to enable debug output to the browser and the PHP error log
+ */
+$debug = true;
+
+$site_id = "default";
+
+/**
+ * initialize the UniFi API connection class, log in to the controller and request the alarms collection
+ * (this example assumes you have already assigned the correct values to the variables used)
+ */
+$unifi_connection = new UniFi_API\Client($controller_user, $controller_password, $controller_url, $site_id, $controller_version, false);
+$login            = $unifi_connection->login();
+
+if($login > 400) {
+    echo "Failed to log into controller";
+    die;
+}
+// $sites = $unifi_connection->list_sites(); // returns a PHP array containing sites
+
+$open_shops = array();
+// Mogrify shop info into useable arrays
+foreach($fil_array as $filnr => $shop) {
+    if(floatval($shop['aktief']) == 0)
+        continue;
+    if($shop['divisie_code'] != "D")
+        continue;
+
+    if((floatval($shop['kassa_aantal']) > 0))
+        $open_shops[$filnr] = ucfirst(strtolower($shop['corr_woonplaats']));
+}
+
+// If debug, create Fake open shops array, otherwise unset test shops
+if($debug === true) {
+    $open_shops = array();
+    $open_shops[943] = "Test 1";
+    $open_shops[965] = "Test 2";
+} else {
+    unset($open_shops[943]);
+    unset($open_shops[965]);
+    unset($close_shops[943]);
+    unset($close_shops[965]);
+}
+
+// Check if we can find all our shop sites, otherwise add to todo list for creation, close list for deletion
+$todo_shops = $open_shops;
+$active_shops = array();
+$close_shops = array();
+foreach($unifi_connection->list_sites() as $site){
+    $desc = $site->desc;
+    // Does it look like a shop?
+    if(preg_match("/([0-9][0-9][0-9]+)/", $desc, $matches)) {
+        // echo "Found site {$desc}\n";
+        unset($todo_shops[floatval($matches[1])]);
+        $active_shops[floatval($matches[1])] = $site->name;
+
+        if(!$open_shops[floatval($matches[1])]) {
+            // echo "Shop {$matches[1]} does not have hardware\n";
+            $close_shops[floatval($matches[1])] = $site->name;
+        }
+    }
+}
+
+// Any sites we need to create before we can continue?
+foreach($todo_shops as $filnr => $city){
+    $filnr = sprintf("%04d", $filnr);
+    $desc = "{$filnr} {$city}";
+    echo "Create site for {$filnr}\n";
+    $createsite = $unifi_connection->create_site($desc);
+    if($createsite === false) {
+        echo "Failed to create site for {$filnr}, id {$siteid}\n";
+        break;
+    }
+}
+// Refresh site list
+if(count($todo_shops > 0)) {
+    foreach($unifi_connection->list_sites() as $site){
+        $desc = $site->desc;
+        // Does it look like a shop?
+        if(preg_match("/([0-9][0-9][0-9]+)/", $desc, $matches)) {
+            // echo "Found site {$desc}\n";
+            unset($todo_shops[floatval($matches[1])]);
+            $active_shops[floatval($matches[1])] = $site->name;
+        }
+    }
+}
+
+// If debug, create Fake site entries array, otherwise unset test shops
+if($debug === true) {
+    $close_shops = array();
+    $active_shops = array();
+    $active_shops[965] = "j103b83q";
+    $active_shops[943] = "winkels";
+} else {
+    unset($active_shops[943]);
+    unset($active_shops[965]);
+    unset($close_shops[943]);
+    unset($close_shops[965]);
+}
+// We should have 0 todo shops now
+// print_r($todo_shops);
+
+/*
+echo "Open\n";
+print_r($open_shops);
+echo "Active\n";
+print_r($active_shops);
+echo "Close\n";
+print_r($close_shops);
+die();
+*/
+
+// Foreach shop, select the site.
+foreach($active_shops as $filnr => $siteid) {
+    $filnr = sprintf("%04d", $filnr);
+    $select = $unifi_connection->set_site($siteid);
+
+    // fetch configured group settings, we need those later, we only use the Default group.
+    $wlangroups = $unifi_connection->list_wlan_groups($siteid);
+    $usergroups = $unifi_connection->list_usergroups($siteid);
+
+    if(isset($close_shops[floatval($filnr)])) {
+        echo "Delete site {$siteid} with id ". $usergroups[0]->site_id ." for shop {$filnr}\n";
+        if($debug===false) {
+            $delete = $unifi_connection->delete_site($usergroups[0]->site_id);
+        }
+        if($delete === false) {
+            echo "Failed to delete site for {$filnr}, id {$siteid}\n";
+        }
+        continue;
+    }
+
+    // fetch configured group settings, we need those later, we only use the Default group.
+    $wlangroups = $unifi_connection->list_wlan_groups($siteid);
+    $usergroups = $unifi_connection->list_usergroups($siteid);
+    if($debug===true) {
+        //var_export ($wlangroups);
+        //var_export ($usergroups);
+    }
+    foreach($wlangroups as $group){
+        // Check if template networks exist
+        if($group->name == "Default") {
+            $shawlangroup_id = $group->_id;
+        }
+    }
+    foreach($usergroups as $group){
+        // Check if template networks exist
+        if($group->name == "Default") {
+            $shausergroup_id = $group->_id;
+        }
+    }
+
+    // Include each time so site specific settings based on shop number are picked up
+    unset($wirednetworks);
+    unset($wlannetworks);
+    unset($siteconf);
+    include("settings.php");
+
+    refresh_networks();
+    refresh_wlans();
+    fetch_site_conf();
+
+    if($debug===true) {
+        // var_export ($siteconf);
+        //var_export ($wlanconf);
+        // var_export ($networkconf);
+        //print_r($wlannetworks);
+    }
+
+
+    foreach($sitesettings as $key => $values) {
+        if(compare_array_item($sitesettings[$key], $setting[$key])) {
+            echo "Update site setting {$key} id {$setting_id[$key]} for {$filnr}, id {$siteid}\n";
+            switch($key){
+                case "country":
+                    $update_site[$key] = $unifi_connection->set_site_country($setting_id[$key], $sitesettings[$key]);
+                    break;
+                case "locale":
+                    $update_site[$key] = $unifi_connection->set_site_locale($setting_id[$key], $sitesettings[$key]);
+                    break;
+                case "connectivity ":
+                    $update_site[$key] = $unifi_connection->set_site_connectivity($setting_id[$key], $sitesettings[$key]);
+                    break;
+                case "mgmt":
+                    $update_site[$key] = $unifi_connection->set_site_mgmt($setting_id[$key], $sitesettings[$key]);
+                    break;
+                case "guest_access":
+                    $update_site[$key] = $unifi_connection->set_site_guest_access($setting_id[$key], $sitesettings[$key]);
+                    break;
+                case "snmp":
+                    $update_site[$key] = $unifi_connection->set_site_snmp($setting_id[$key], $sitesettings[$key]);
+                    break;
+                case "ntp":
+                    $update_site[$key] = $unifi_connection->set_site_ntp($setting_id[$key], $sitesettings[$key]);
+                    break;
+                default:
+                    break;
+            }
+        }
+        if($update_site[$key] === false)
+            echo "Failed to update setting {$key} for {$filnr}, id {$siteid} ". print_r($sitesettings[$key], true) ."\n";
+    }
+
+    foreach($wirednetworks as $key => $values) {
+        // Template network didn't exist, create
+        if($wired[$key] === false) {
+            echo "Create new vlan {$key} for {$filnr}, id {$siteid}\n";
+            $addnetwork[$key] = $unifi_connection->create_network($wirednetworks[$key]);
+            // echo json_encode($addvlan, JSON_PRETTY_PRINT);
+        }
+        if($addnetwork[$key] === false)
+            echo "Failed to add network {$key} for {$filnr}, id {$siteid}\n";
+
+        // Do we need to update?
+        if(compare_array_item($wirednetworks[$key], $wired[$key])) {
+            echo "Update network {$key} id {$wired_id[$key]} for {$filnr}, id {$siteid}\n";
+            $updatenetwork[$key] = $unifi_connection->set_networksettings_base($wired_id[$key], $wirednetworks[$key]);
+        }
+        if($updatenetwork[$key] === false)
+            echo "Failed to update network {$key} for {$filnr}, id {$siteid} ". print_r($wirednetworks[$key], true) .  print_r($wired_id, true) ."\n";
+
+    }
+
+    foreach($wlannetworks as $key => $values) {
+        // Template network didn't exist, create
+        if($wlan[$key] === false) {
+            echo "Create new disabled wlan {$key} for {$filnr}, id {$siteid}\n";
+            $addwlan[$key] = $unifi_connection->create_wlan($wlannetworks[$key]['name'], $wlannetworks[$key]['x_passphrase'], $wlannetworks[$key]['usergroup_id'], $wlannetworks[$key]['wlangroup_id'], false);
+        }
+        if($addwlan[$key] === false)
+            echo "Failed to add wlan {$key} for {$filnr}, id {$siteid} ". print_r($wlannetworks[$key], true) ."\n";
+        else
+            refresh_wlans();
+
+        // Do we need to update?
+        if(compare_array_item($wlannetworks[$key], $wlan[$key])) {
+            echo "Update wlan {$key} id {$wlan_id[$key]} for {$filnr}, id {$siteid}\n";
+            $updatewlan[$key] = $unifi_connection->set_wlansettings_base($wlan_id[$key], $wlannetworks[$key]);
+        }
+        if($updatewlan[$key] === false)
+            echo "Failed to update wlan {$key} for {$filnr}, id {$siteid} ". print_r($wlannetworks[$key], true) . print_r($wlan_id, true) ."\n";
+
+    }
+
+    // Any devices for adoption?
+    $devices[$filnr] = $unifi_connection->list_devices();
+    foreach($devices[$filnr] as $device) {
+        if($device->adopted == 1)
+            continue;
+
+        // Does this unadopted device belong to this shop network?
+        if(netMatch($wirednetworks['LAN']['ip_subnet'], $device->ip)) {
+            // Adopt device in IP range. adopt_device($mac)
+            echo "Adopting device {$device->mac} with ip {$device->ip} in network {$wirednetworks['LAN']['ip_subnet']} for shop {$filnr}\n";
+            $unifi_connection->adopt_device($device->mac);
+            // print_r($device);
+        }
+    }
+
+    if($debug===true) {
+        //break;
+    }
+}
+
+$logout = $unifi_connection->logout();
+
+function refresh_networks() {
+    global $unifi_connection;
+    global $networkconf;
+    global $wired;
+    global $wired_id;
+    global $shasite_id;
+    global $wirednetworks;
+
+    // Fetch configured wired networks
+    $networkconf = $unifi_connection->list_networkconf();
+
+    foreach($wirednetworks as $key => $values) {
+        $wired[$key] = false;
+    }
+    // Lan netwerken
+    foreach($networkconf as $network){
+        // Check if template networks exist
+        foreach($wirednetworks as $key => $values) {
+            if(($network->name == "$key")) {
+                $wired[$key] = $network;
+                $wired_id[$key] = $network->_id;
+                $shasite_id = $network->site_id;
+            }
+        }
+    }
+}
+
+function refresh_wlans() {
+    global $unifi_connection;
+    global $wlanconf;
+    global $wlan;
+    global $wlan_id;
+    global $shasite_id;
+    global $wlannetworks;
+
+    // Fetch Wireless networks
+    $wlanconf = $unifi_connection->list_wlanconf();
+
+    foreach($wlannetworks as $key => $values)
+        $wlan[$key] = false;
+
+    foreach($wlanconf as $network){
+        // Check if template networks exist
+        foreach($wlannetworks as $key => $values) {
+            if($network->name == "$key") {
+                $wlan[$key] = $network;
+                $wlan_id[$key] = $network->_id;
+                $shasite_id = $network->site_id;
+            }
+        }
+    }
+}
+
+function fetch_site_conf() {
+    global $unifi_connection;
+    global $siteconf;
+    global $siteid;
+    global $sitesettings;
+    global $setting;
+    global $setting_id;
+
+    // Fetch site settings
+    $siteconf = $unifi_connection->list_settings($siteid);
+    foreach($sitesettings as $key => $values)
+        $sitesetting[$key] = false;
+
+    $setting = array();
+    foreach($siteconf as $arr) {
+        $setting[$arr->key] = $arr;
+        $setting_id[$arr->key] = $arr->_id;
+    }
+}
+
+// Return true or false
+function compare_array_item($setting, $existing) {
+    $existing = (array)$existing;
+    unset($setting['site_id']);
+    unset($setting['_id']);
+    unset($existing['_id']);
+    unset($existing['site_id']);
+    foreach($setting as $key => $value) {
+        if(!is_array($setting[$key])) {
+            if($setting[$key] != $existing[$key]){
+                echo "setting key {$key} value {$value} differs from {$existing[$key]} - ";
+                // print_r($setting);
+                // print_r($existing);
+                return true;
+            }
+        }
+        if(is_array($setting[$key])) {
+            $diff = array();
+            $diff = array_diff_assoc($setting[$key], $existing[$key]);
+            if(!empty($diff)) {
+                echo "setting subkey {$key} differs diff count ". count($diff)."\n";
+                // print_r($diff);
+                // print_r($setting);
+                // print_r($existing);
+                return true;
+            }
+        }
+    }
+    return false;
+}
+?>

examples/site_provisioning_example/settings.template.php

@@ -0,0 +1,197 @@
+<?php
+/**
+ * template settings file for site provisioning example script
+ *
+ * contributed by: @smos
+ */
+
+// Extract shop IP addressing from numeric shop number, you could use something else, static or using a database lookup.
+$octet1 = 10;
+if(strlen($filnr) == 3) {
+    $octet2 = floatval(substr($filnr,0,1));
+    $octet3 = floatval(substr($filnr,1,2));
+} else {
+    $octet2 = floatval(substr($filnr,0,2));
+    $octet3 = floatval(substr($filnr,2,2));
+}
+
+// Wired networks
+$wirednetworks['LAN'] = array(
+    'dhcpd_enabled' => true,
+    'dhcpd_start' => "{$octet1}.{$octet2}.{$octet3}.100",
+    'dhcpd_stop' => "{$octet1}.{$octet2}.{$octet3}.150",
+    'domain_name' => 'foo.bar.nl',
+    'dhcpd_dns_1' => '10.56.154.13',
+    'dhcpd_dns_2' => '10.34.234.66',
+    'dhcpd_ip_1' => "{$octet1}.{$octet2}.{$octet3}.254",
+    'dhcpguard_enabled' => true,
+    'ip_subnet' => "{$octet1}.{$octet2}.{$octet3}.254/24",
+    'is_nat' => true,
+    'name' => 'LAN',
+    'networkgroup' => 'LAN',
+    'purpose' => 'corporate',
+    'site_id' => $shasite_id,
+    'vlan_enabled' => false,
+ );
+$wirednetworks['shop-wifi'] = array(
+    'enabled' => true,
+    'is_nat' => true,
+    'dhcpd_ip_1' => '192.168.2.254',
+    'dhcpguard_enabled' => true,
+    'name' => 'shop-wifi',
+    'purpose' => 'vlan-only',
+    'site_id' => $shasite_id,
+    'vlan_enabled' => true,
+    'vlan' => 10,
+);
+// Wireless networks
+$wlannetworks["UBNT-{$filnr}"] = array(
+    'enabled' => true,
+    'is_guest' => true,
+    'mac_filter_enabled' => false,
+    'mac_filter_list' => array (),
+    'mac_filter_policy' => 'allow',
+    'name' => "UBNT-{$filnr}",
+    'usergroup_id' => $shausergroup_id,
+    'wlangroup_id' => $shawlangroup_id,
+    'schedule' =>
+    array (
+         0 => 'mon|0800-1800',
+         1 => 'tue|0800-1800',
+         2 => 'wed|0800-1800',
+         3 => 'thu|0800-1800',
+         4 => 'fri|0800-1800',
+         5 => 'sat|0800-1800',
+         6 => 'sun|0800-1800',
+        ),
+    'schedule_enabled' => true,
+    'security' => 'wpapsk',
+    'site_id' => $shasite_id,
+    'vlan' => '10',
+    'vlan_enabled' => true,
+    'wep_idx' => 1,
+    'wpa_enc' => 'ccmp',
+    'wpa_mode' => 'wpa2',
+    'x_passphrase' => 'datisgeheim',
+);
+$wlannetworks['CorporateWifi'] = array(
+    'enabled' => true,
+    'is_guest' => false,
+    'mac_filter_enabled' => false,
+    'mac_filter_list' => array (),
+    'mac_filter_policy' => 'allow',
+    'name' => "CorporateWifi",
+    'usergroup_id' => $shausergroup_id,
+    'wlangroup_id' => $shawlangroup_id,
+    'schedule' =>
+    array (
+         0 => 'mon|0800-1800',
+         1 => 'tue|0800-1800',
+         2 => 'wed|0800-1800',
+         3 => 'thu|0800-1800',
+         4 => 'fri|0800-1800',
+         5 => 'sat|0800-1800',
+         6 => 'sun|0800-1800',
+        ),
+    'schedule_enabled' => true,
+    'security' => 'wpapsk',
+    'site_id' => $shasite_id,
+    'wep_idx' => 1,
+    'wpa_enc' => 'ccmp',
+    'wpa_mode' => 'wpa2',
+    'x_passphrase' => 'SuperSecretPassword',
+);
+
+// Unset this network for test shops
+if(preg_match("/[0-9][9][0-9]+)/si", $filnr))
+    unset($wlannetworks['CorporateWifi']);
+
+// Site settings template
+$sitesettings['connectivity'] = array(
+    'enabled' => true,
+    'key' => 'connectivity',
+    'site_id' => $shasite_id,
+    'uplink_type' => 'gateway',
+);
+$sitesettings['guest_access'] = array(
+    'auth' => 'none',
+    'key' => 'guest_access',
+    'redirect_https' => true,
+    'redirect_to_https' => false,
+    'restricted_subnet_1' => '192.168.0.0/16',
+    'restricted_subnet_2' => '172.16.0.0/12',
+    'restricted_subnet_3' => '10.0.0.0/8',
+    'site_id' => $shasite_id,
+);
+$sitesettings['country'] = array(
+    'code' => '528',
+    'key' => 'country',
+    'site_id' => $shasite_id,
+);
+$sitesettings['locale'] = array(
+    'key' => 'locale',
+    'site_id' => $shasite_id,
+    'timezone' => 'Europe/Amsterdam',
+);/*
+$sitesettings['porta'] = array(
+    'key' => 'porta',
+    'site_id' => $shasite_id,
+    'ugw3_wan2_enabled' => false,
+);*/
+$sitesettings['snmp'] = array(
+    'community' => 'esenempee',
+    'key' => 'snmp',
+    'site_id' => $shasite_id,
+);
+$sitesettings['rsyslogd'] = array(
+    'key' => 'rsyslogd',
+    'port' => '514',
+    'site_id' => $shasite_id,
+);/*
+$sitesettings['auto_speedtest'] = array(
+    'enabled' => false,
+    'interval' => 20,
+    'key' => 'auto_speedtest',
+    'site_id' => $shasite_id,
+);*/
+$sitesettings['ntp'] = array(
+    'key' => 'ntp',
+    'ntp_server_1' => 'ntp.xs4all.nl',
+    'ntp_server_2' => '0.ubnt.pool.ntp.org',
+    'site_id' => $shasite_id,
+);
+/*
+$sitesettings['usg'] = array(
+    'broadcast_ping' => false,
+    'ftp_module' => true,
+    'gre_module' => true,
+    'h323_module' => true,
+    'key' => 'usg',
+    'mdns_enabled' => false,
+    'mss_clamp' => 'auto',
+    'offload_accounting' => true,
+    'offload_l2_blocking' => true,
+    'offload_sch' => true,
+    'pptp_module' => true,
+    'receive_redirects' => false,
+    'send_redirects' => true,
+    'sip_module' => true,
+    'site_id' => $shasite_id,
+    'syn_cookies' => true,
+    'tftp_module' => true,
+    'upnp_enabled' => false,
+    'upnp_nat_pmp_enabled' => true,
+    'upnp_secure_mode' => true,
+);*/
+$sitesettings['mgmt'] = array(
+    'advanced_feature_enabled' => false,
+    'alert_enabled' => true,
+    'auto_upgrade' => true,
+    'key' => 'mgmt',
+    'led_enabled' => true,
+    'site_id' => $shasite_id,
+    'unifi_idp_enabled' => true,
+    'x_ssh_auth_password_enabled' => true,
+    'x_ssh_bind_wildcard' => false,
+    'x_ssh_enabled' => true,
+);

examples/test_connection.php

@@ -3,7 +3,7 @@
  * Test the connection to your UniFi controller
  *
  * contributed by: Art of WiFi
- * description: PHP script to check/debug the connection to your controller using PHP and cURL
+ * description:    PHP script to check/debug the connection to your controller using PHP and cURL
  */
 
 /**
@@ -11,13 +11,14 @@
  * see the config.template.php file for an example.
  * (will only be used here to get the URL to the controller)
  */
-require_once('config.php');
+require_once 'config.php';
 
 /**
  * Check whether the cURL module supports SSL
+ * http://www.php.net/manual/en/function.curl-version.php
  */
-if (!curl_version()['features'] & CURL_VERSION_SSL) {
+if (!(curl_version()['features'] & CURL_VERSION_SSL)) {
-    print 'SSL is not supported with this cURL installation!' . PHP_EOL;
+    print PHP_EOL . 'SSL is not supported with this cURL installation!' . PHP_EOL;
 }
 
 /**
@@ -25,44 +26,53 @@ if (!curl_version()['features'] & CURL_VERSION_SSL) {
  */
 $ch = curl_init();
 
-/**
+if (is_resource($ch) || is_object($ch)) {
- * Set the required cURL options
+    /**
- */
+     * 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');
+     * NOTES:
-curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
+     * The cURL option CURLOPT_SSLVERSION can have a value of 0-6
-curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
+     * 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_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,
+    ];
 
-/**
+    curl_setopt_array($ch, $curl_options);
- * This cURL option 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);
 
-/**
+    /**
- * Be more verbose
+     * $results contains the output as returned by the cURL request,
- */
+     * returns true when successful, else returns false
-curl_setopt($ch, CURLOPT_VERBOSE, true);
+     */
+    print PHP_EOL . 'verbose output from the cURL request:' . PHP_EOL;
+    $results = curl_exec($ch);
 
-/**
+    print PHP_EOL . 'curl_getinfo output:' . PHP_EOL;
- * $results contains the output as returned by the cURL request,
+    print_r(curl_getinfo($ch));
- * returns true when successful, else returns false
- */
-print 'verbose output from the cURL request:' . PHP_EOL;
-$results = curl_exec($ch);
 
-print PHP_EOL . 'curl_getinfo output:' . PHP_EOL;
+    /**
-print_r(curl_getinfo($ch));
+     * If we receive a cURL error, output it before the results
+     */
+    if (curl_errno($ch)) {
+        print PHP_EOL . 'cURL error: ' . curl_error($ch) . PHP_EOL;
+    }
 
-/**
+    print PHP_EOL . 'test result:' . PHP_EOL;
- * If we receive a cURL error, output it before the results
+    if ($results) {
- */
+        print 'Controller connection success' . PHP_EOL;
-if (curl_errno($ch)) {
+        die;
-    print PHP_EOL . 'cURL error: ' . curl_error($ch) . PHP_EOL;
+    }
+
+    print 'Controller connection failed' . PHP_EOL;
+} else {
+    print PHP_EOL . 'ERROR: cURL could not be initialized!' . PHP_EOL;
 }
-
-print PHP_EOL . '$results:' . PHP_EOL;
-print_r($results);
-print PHP_EOL;

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;

examples/toggle_led.php

@@ -3,20 +3,20 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example to toggle the locate function (flashing LED) on an Access Point and
+ * description:    example to toggle the locate function (flashing LED) on an Access Point and
- *              output the response in json format
+ *                 output the response in json format
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * site id to use
@@ -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
+$unifi_connection = new UniFi_API\Client(
-$set_debug_mode   = $unifi_connection->set_debug($debug);
+    $controlleruser,
-$loginresults     = $unifi_connection->login();
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$set_debug_mode = $unifi_connection->set_debug($debug);
+$loginresults   = $unifi_connection->login();
 
 /**
  * using the new method/function

examples/unblock_list.php

@@ -0,0 +1,90 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: @malcolmcif, based on another Art of WiFi example
+ * description:    basic PHP script to unblock a list of mac addresses passed in via command line,
+ *                 output is to console in non json format
+ *
+ * usage:
+ *  php unblock_list.php <list of comma seperated mac addresses>
+ *
+ * example:
+ *  php unblock_list.php 09:09:09:09:09:09,10:10:10:10:10:10
+ *
+ */
+
+/**
+ * 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';
+$debug = false;
+
+/**
+ * the MAC addresses of the device(s) to unblock
+ */
+$macs_to_unblock = explode(',', $argv[1]);
+
+/**
+ * The site to authorize the device with
+ */
+$site_id = 'MUST_DEFINE_THIS';
+if ($site_id == "MUST_DEFINE_THIS") {
+    print 'ERROR: set the site id in your script';
+    return;
+}
+
+/**
+ * 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
+
+foreach ($macs_to_unblock as &$mac) {
+    // block_result is always true even if mac address does not exist :(
+    $block_result = $unifi_connection->unblock_sta($mac);
+
+    /**
+     * NOTE:
+     * during testing I had some strange behavior where clients were not reconnecting to the network correctly,
+     * they appeared unblocked and received a valid IP address but could not actually get any data.
+     * the clients did not come to life until I disabled the SSID and then re enabled it.
+     * I guessed maybe these commands were occurring too quickly for the controller so I have slowed them down;
+     * since introducing the sleep I have not seen the above behavior so it might be fixed
+     */
+    sleep(1);
+
+    $getid_result = $unifi_connection->stat_client($mac);
+
+    if (property_exists($getid_result[0], "oui")) {
+        // this field(manufacturer) seems to exist on valid mac addresses
+        if (property_exists($getid_result[0], "name")) {
+            $name = $getid_result[0]->name;
+        } else {
+            $name = $getid_result[0]->hostname;
+        }
+        print 'unblocked ' . $name . PHP_EOL;
+    } else {
+        print 'ERROR: could not unblock ' . $mac . PHP_EOL;
+        print '       check mac address is valid and part of your network' . PHP_EOL;
+    }
+}
+
+/**
+ * provide feedback in json format
+ */
+//echo json_encode($block_result, JSON_PRETTY_PRINT);

examples/update_ac-iw_ports.php

@@ -0,0 +1,85 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description:    example basic PHP script to update the port settings of an AC-IW device
+ *                 FYI: the AC-IW device has three ports, one for the wired uplink and two with external connectors
+ * note:           requires controller version 5.5.X or higher (to be verified)
+ */
+
+/**
+ * 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 to log in to the controller
+ */
+$site_id = '<short site name of a site the credentials used have access to>';
+
+/**
+ * the MAC address of the AC-IW device to re-configure
+ */
+$device_mac = '<enter MAC address>';
+
+/**
+ * port configuration id to apply to port #1 of the AC-IW device
+ * NOTE: port configurations are available through list_portconf()
+ */
+$port_conf_id_port_1 = '<_id of port configuration to apply to port #1>';
+
+/**
+ * port configuration id to apply to port #2 of the AC-IW device
+ * NOTE: port configurations are available through list_portconf()
+ */
+$port_conf_id_port_2 = '<_id of port configuration to apply to port #2>';
+
+/**
+ * prepare the payload to pass on to the API endpoint
+ */
+$new_ports_config = [
+    'port_overrides' => [
+        [
+            'port_idx'    => 1,
+            'portconf_id' => $port_conf_id_port_1
+        ],
+        [
+            'port_idx'    => 2,
+            'portconf_id' => $port_conf_id_port_2
+        ]
+    ]
+];
+
+/**
+ * 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(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();
+    echo json_encode($error, JSON_PRETTY_PRINT);
+}
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($update_device, JSON_PRETTY_PRINT);

examples/update_device_wlan_settings_5.5.X.php

@@ -0,0 +1,90 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description:    example basic PHP script to update WLAN settings of a device when using a controller version 5.5.X or higher
+ *                 where set_ap_radiosettings() throws an error
+ */
+
+/**
+ * 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 to log in to the controller
+ */
+$site_id = '<short site name of a site the credentials used have access to>';
+
+/**
+ * the MAC address of the access point to modify
+ */
+$ap_mac = '<enter MAC address>';
+
+/**
+ * power level for 2.4GHz
+ */
+$ng_tx_power_mode = 'low';
+
+/**
+ * channel for 2.4GHz
+ */
+$ng_channel = 6;
+
+/**
+ * power level for 5GHz
+ */
+$na_tx_power_mode = 'medium';
+
+/**
+ * channel for 5GHz
+ */
+$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
+);
+
+$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;
+    }
+
+    if ($radio->radio === 'na') {
+        $radio->tx_power_mode = $na_tx_power_mode;
+        $radio->channel       = $na_channel;
+    }
+}
+
+$update_device = $unifi_connection->set_device_settings_base($device_id, ['radio_table' => $radio_table]);
+
+if (!$update_device) {
+    $error = $unifi_connection->get_last_results_raw();
+    echo json_encode($error, JSON_PRETTY_PRINT);
+}
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($update_device, JSON_PRETTY_PRINT);

examples/update_switch_poe-mode.php

@@ -0,0 +1,105 @@
+<?php
+/**
+ * PHP API usage example to turn the PoE of the selected switch ports to "off" or "auto"
+ *
+ * contributed by: @Kaltt
+ * description:    A use case for this script is to turn off the PoE of the port where a camera is connected in order to turn off the camera
+ *
+ * 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.
+ */
+
+/**
+ * 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 to log in to the controller
+ */
+$site_id = '<short site name of a site the credentials used have access to>';
+
+/**
+ * the MAC address of the AC-IW device to re-configure
+ */
+$device_mac = '<enter MAC address>';
+
+/**
+ * $lanports is an array that defines which ports should be changed
+ */
+$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)
+{
+    /**
+     * 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)) {
+            $running_config[$i]->poe_mode = $poe_mode;
+            unset($ports[array_search($running_config[$i]->port_idx, $ports)]);
+        }
+    }
+
+    $add_conf = [];
+    foreach ($ports as $port) {
+        $add_conf[] = [
+            'port_idx' => $port,
+            'poe_mode' => $poe_mode
+        ];
+    }
+
+    return array_merge($running_config, $add_conf);
+}
+
+$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"
+ */
+if (isset($_GET['poe_mode'])) {
+    $poe_mode = $_GET['poe_mode'];
+} elseif (isset($argv[1])) {
+    $poe_mode = $argv[1];
+} else {
+    $poe_mode = 'auto';
+}
+
+$new_ports_config = [
+    'port_overrides' => update_ports($current_conf, $lanports, $poe_mode)
+];
+
+$update_device = $unifi_connection->set_device_settings_base($device_id, $new_ports_config);
+
+if (!$update_device) {
+    $error = $unifi_connection->get_last_results_raw();
+    echo json_encode($error, JSON_PRETTY_PRINT);
+}
+
+echo json_encode($update_device, JSON_PRETTY_PRINT);

src/Exceptions/CurlExtensionNotLoadedException.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when the required PHP cURL extension is not loaded in the runtime.
+ *
+ * @note Consumers can catch this to provide an installation hint or to disable any
+ *       functionality that requires cURL.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class CurlExtensionNotLoadedException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('The PHP curl extension is not loaded. Please correct this before proceeding!');
+    }
+}

src/Exceptions/CurlGeneralErrorException.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a general cURL error occurs while calling the UniFi API.
+ *
+ * @property-read mixed $httpResponseCode HTTP response code if available
+ * @property-read mixed $curlGetinfoResults Results from curl_getinfo() if available
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class CurlGeneralErrorException extends UnifiApiException
+{
+    /** @var mixed $_http_response_code */
+    private $_http_response_code;
+
+    /** @var mixed $_curl_getinfo_results */
+    private $_curl_getinfo_results;
+
+    public function __construct(string $message, $http_response_code, $_curl_getinfo_results)
+    {
+        $this->_http_response_code   = $http_response_code;
+        $this->_curl_getinfo_results = $_curl_getinfo_results;
+
+        parent::__construct($message, $http_response_code);
+    }
+
+    /**
+     * Get the HTTP response code.
+     *
+     * @return mixed
+     */
+    public function getHttpResponseCode()
+    {
+        return $this->_http_response_code;
+    }
+
+    /**
+     * Get the cURL curl_getinfo results.
+     *
+     * @return mixed
+     */
+    public function getCurlGetinfoResults()
+    {
+        return $this->_curl_getinfo_results;
+    }
+}

src/Exceptions/CurlTimeoutException.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a cURL request times out.
+ *
+ * @property-read mixed $httpResponseCode HTTP response code if available
+ * @property-read mixed $curlGetinfoResults Result of curl_getinfo() when available
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class CurlTimeoutException extends UnifiApiException
+{
+    /** @var mixed $_http_response_code */
+    private $_http_response_code;
+
+    /** @var mixed $_curl_getinfo_results */
+    private $_curl_getinfo_results;
+
+    public function __construct(string $message, $http_response_code, $curl_getinfo_results)
+    {
+        $this->_http_response_code   = $http_response_code;
+        $this->_curl_getinfo_results = $curl_getinfo_results;
+
+        parent::__construct($message, $http_response_code);
+    }
+
+    /**
+     * Get the HTTP response code.
+     *
+     * @return mixed
+     */
+    public function getHttpResponseCode()
+    {
+        return $this->_http_response_code;
+    }
+
+    /**
+     * Get the cURL curl_getinfo results.
+     *
+     * @return mixed
+     */
+    public function getCurlGetinfoResults()
+    {
+        return $this->_curl_getinfo_results;
+    }
+}

src/Exceptions/EmailInvalidException.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when an invalid email address is provided to the client.
+ *
+ * @note This Exception is used for input validation where a properly formatted email is required.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class EmailInvalidException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('Invalid email address provided.');
+    }
+}

src/Exceptions/InvalidBaseUrlException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when the provided base URL for the UniFi controller is invalid.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class InvalidBaseUrlException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('The base URL provided is invalid.');
+    }
+}

src/Exceptions/InvalidCurlMethodException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when an unsupported or invalid cURL method is requested by the client.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class InvalidCurlMethodException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('Invalid cURL method provided.');
+    }
+}

src/Exceptions/InvalidSiteNameException.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a provided short site name is invalid or cannot be used by the client.
+ *
+ * @note This Exception is thrown when the short site name contains illegal characters or when
+ *       the name does not correspond to any known site on the controller.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class InvalidSiteNameException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('Invalid site name provided.');
+    }
+}

src/Exceptions/JsonDecodeException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when the library fails to decode JSON returned by the controller.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class JsonDecodeException extends UnifiApiException
+{
+    // Intentionally empty - represents JSON decoding failures.
+}

src/Exceptions/LoginFailedException.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when the client fails to authenticate with the UniFi controller.
+ *
+ * @note This can indicate invalid credentials, connectivity problems, or a change
+ *       in the controller's authentication mechanism (e.g., MFA).
+ *
+ * @property-read mixed $httpResponseCode HTTP response code if available
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class LoginFailedException extends UnifiApiException
+{
+    /** @var mixed $_http_response_code */
+    private $_http_response_code;
+
+    public function __construct(string $message, $http_response_code)
+    {
+        $this->_http_response_code   = $http_response_code;
+
+        parent::__construct($message, $http_response_code);
+    }
+
+    /**
+     * Get the HTTP response code.
+     *
+     * @return mixed
+     */
+    public function getHttpResponseCode()
+    {
+        return $this->_http_response_code;
+    }
+}

src/Exceptions/LoginRequiredException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a method that requires authentication is called before logging in.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class LoginRequiredException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('This method requires the API client to be logged in first.');
+    }
+}

src/Exceptions/MacAddressEmptyException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a MAC address was expected, but none was provided (empty/null).
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class MacAddressEmptyException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('MAC address is empty.');
+    }
+}

src/Exceptions/MacAddressInvalidException.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a provided MAC address does not match expected formatting or
+ * validation rules.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class MacAddressInvalidException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('MAC address is invalid.');
+    }
+}

src/Exceptions/MethodDeprecatedException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a library method or API endpoint has been deprecated and should
+ * no longer be used.
+ *
+ * @note Consumers can catch this to provide migration guidance or suppress warnings for legacy callers.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class MethodDeprecatedException extends UnifiApiException
+{
+    // Intentionally empty - serves as a distinct exception type.
+}

src/Exceptions/NotAUnifiOsConsoleException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when the target host is not a UniFi OS console.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class NotAUnifiOsConsoleException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('This is not a UniFi OS console.');
+    }
+}

src/Exceptions/UnifiApiException.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+use Throwable;
+
+/**
+ * Base exception for the UniFi API client.
+ *
+ * @note All custom exceptions in this library extend this class so consumers can
+ *       catch a single type (\UniFi_API\Exceptions\UnifiApiException) when they
+ *       want to handle all client errors uniformly.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class UnifiApiException extends Exception
+{
+    /**
+     * UnifiApiException constructor.
+     *
+     * @param string         $message  Human-readable message describing the error.
+     * @param int            $code     Optional error code.
+     * @param Throwable|null $previous Optional previous exception for chaining.
+     */
+    public function __construct(string $message = 'An error occurred in the UniFi API client.', int $code = 0, ?Throwable $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+    }
+}