updated README to include new functions/methods

- applied minor improvements based on Scrutinizer reports
- applied minor changes to `authorize_guest()` to further improve handling of 0/null/empty values passed
- restricted protocols to be used by cURL to only allow http and https for improved security
- added methods/functions `list_device_name_mappings()` and `stat_full_status()`

.gitignore

@@ -5,5 +5,9 @@
 /vendor/
 /composer.lock
 
+# ignore phpdoc files
+/build
+.phpdoc-md
+
 # ignore XML files
 *.xml

README.md

@@ -1,8 +1,9 @@
 ## UniFi Controller API client class
 
-A PHP class that provides access to Ubiquiti's [**UniFi SDN Controller**](https://unifi-sdn.ui.com/) API, versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.12.72 has been confirmed to work) as well as UbiOS-based controllers (version 5.12.59 has been confirmed to work). This class is used by our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
+A PHP class that provides access to Ubiquiti's [**UniFi Network Controller**](https://unifi-network.ui.com/) API, versions 4.X.X, 5.X.X and 6.0.X of the UniFi Network Controller software are supported (version 6.0.43 has been confirmed to work) as well as UniFi OS-based controllers (version 5.12.59 has been confirmed to work). This class is used by our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
+
+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.
 
-The package can be installed manually or using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
 
 ## Requirements
 
@@ -11,15 +12,17 @@ The package can be installed manually or using composer/[packagist](https://pack
 - you must use **local accounts**, not UniFi Cloud accounts, to access the UniFi Controller API through this class
 
 
-## UbiOS Support
+## UniFi OS Support
 
-Support for UbiOS-based controllers (UniFi Dream Machine Pro) has been added as of version 1.1.47. The class automatically detects UbiOS devices and adjusts URLs and several functions/methods accordingly. If your own code applies strict validation of the URL that is passed to the constructor, please adapt your logic to allow URLs without a port suffix when dealing with a UbiOS-based controller.
+Support for UniFi OS-based controllers (UniFi Dream Machine Pro or Cloud Key Gen2/Cloud Key Gen2 Plus with firmware version 2.0.24 or higher) has been added as of version 1.1.47. The class automatically detects UniFi OS devices and adjusts URLs and several functions/methods accordingly. If your own code applies strict validation of the URL that is passed to the constructor, please adapt your logic to allow URLs without a port suffix when dealing with a UniFi OS-based controller.
+
+Please test all methods you plan on using thoroughly before using the API Client with UniFi OS devices in a production environment.
 
-Please test all methods you plan on using thoroughly before using the API Client with UbiOS devices in a production environment.
 
 ## Installation
 
-You can use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client class.
+Use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client class.
+
 
 ### Composer
 
@@ -31,7 +34,7 @@ Once composer is installed, simply execute this command from the shell in your p
 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
 {
@@ -44,9 +47,10 @@ composer require art-of-wifi/unifi-api-client
 Finally, be sure to include the autoloader in your code:
 
 ```php
-require_once('vendor/autoload.php');
+require_once 'vendor/autoload.php';
 ```
 
+
 ### Git
 
 Execute the following `git` command from the shell in your project directory:
@@ -58,17 +62,19 @@ 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');
+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:
+If you prefer not to use composer or git, simply [download the package](https://github.com/Art-of-WiFi/UniFi-API-client/archive/master.zip), uncompress the zip file, then include the file containing the class in your code like so:
 
 ```php
-require_once('path/to/src/Client.php');
+require_once 'path/to/src/Client.php';
 ```
 
+
 ## Example usage
 
 A basic example how to use the class:
@@ -77,7 +83,7 @@ A basic example how to use the class:
 /**
  * load the class using the composer autoloader
  */
-require_once('vendor/autoload.php');
+require_once 'vendor/autoload.php';
 
 /**
  * initialize the Unifi API connection class, log in to the controller and request the alarms collection
@@ -88,17 +94,19 @@ $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.
+Please refer to the `examples/` directory for some more detailed examples which can be used as a starting point for your own PHP code.
+
 
 #### IMPORTANT NOTES:
 
-1. In the above example, `$site_id` is the short site "name" (usually 8 characters long) that is visible in the URL when managing the site in the UniFi SDN Controller. For example with this URL:
+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 last 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.
+2. The last 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.
+
 
 ## Functions/methods supported
 
@@ -114,6 +122,9 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
 - cancel_rolling_upgrade()
 - cmd_stat()
 - count_alarms()
+- check_controller_update()
+- check_firmware_update()
+- create_apgroup() (supported with controller versions 6.0.X and higher)
 - create_dynamicdns()
 - create_firewallgroup()
 - create_hotspotop()
@@ -125,6 +136,7 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
 - create_voucher()
 - create_wlan()
 - custom_api_request()
+- delete_apgroup() (supported with controller versions 6.0.X and higher)
 - delete_device()
 - delete_firewallgroup()
 - delete_network()
@@ -133,6 +145,7 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
 - delete_usergroup()
 - delete_wlan()
 - disable_ap()
+- edit_apgroup() (supported with controller versions 6.0.X and higher)
 - edit_client_fixedip()
 - edit_firewallgroup()
 - edit_usergroup()
@@ -143,6 +156,7 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
 - list_admins()
 - list_alarms()
 - list_all_admins()
+- list_apgroups() (supported with controller versions 6.0.X and higher)
 - list_aps() (deprecated but still available as alias)
 - list_backups()
 - list_clients()
@@ -150,6 +164,7 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
 - list_current_channels()
 - list_dashboard()
 - list_devices()
+- list_device_name_mappings()
 - list_dpi_stats()
 - list_dynamicdns()
 - list_events()
@@ -241,8 +256,13 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
 - stat_speedtest_results()
 - stat_sta_sessions_latest()
 - stat_status()
+- stat_full_status()
 - stat_sysinfo()
 - stat_voucher()
+- stat_monthly_aps()
+- stat_monthly_gateway()
+- stat_monthly_site()
+- stat_monthly_user()
 - unauthorize_guest()
 - unblock_sta()
 - unset_locate_ap() (deprecated but still available as alias)
@@ -259,7 +279,7 @@ Other functions, getters/setters:
 - get_is_unifi_os()
 - get_last_error_message()
 - get_last_results_raw()
-- get_request_type()
+- get_request_method()
 - get_site()
 - get_ssl_verify_host()
 - get_ssl_verify_peer()
@@ -267,7 +287,7 @@ Other functions, getters/setters:
 - set_cookies()
 - set_debug()
 - set_is_unifi_os()
-- set_request_type()
+- set_request_method()
 - set_site()
 - set_ssl_verify_host()
 - set_ssl_verify_peer()
@@ -277,10 +297,12 @@ Other functions, getters/setters:
 
 There is still work to be done to add functionality and further improve the usability of this class, so all suggestions/comments are welcome. Please use the GitHub [issue list](https://github.com/Art-of-WiFi/UniFi-API-client/issues) or the Ubiquiti Community forums (https://community.ubnt.com/t5/UniFi-Wireless/PHP-class-to-access-the-UniFi-controller-API-updates-and/td-p/1512870) to share your suggestions and questions.
 
+
 ## Contribute
 
 If you would like to contribute code (improvements), please open an issue and include your code there or else create a pull request.
 
+
 ## Credits
 
 This class is based on the initial work by the following developers:
@@ -290,7 +312,8 @@ This class is based on the initial work by the following developers:
 
 and the API as published by Ubiquiti:
 
-- https://dl.ui.com/unifi/5.12.35/unifi_sh_api
+- https://dl.ui.com/unifi/6.0.41/unifi_sh_api
+
 
 ## Important Disclaimer
 

examples/ap_scanning_state.php

@@ -3,19 +3,19 @@
  * 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

examples/ap_upgrade_firmware.php

@@ -3,11 +3,11 @@
  * PHP API usage example
  *
  * contributed by: @4oo4
- * description: example script to upgrade device firmware (can be scheduled with systemd/cron)
+ * description:    example script to upgrade device firmware (can be scheduled with systemd/cron)
- *              to the most current version
+ *                 to the most current version
  */
-require_once('vendor/autoload.php');
+require_once 'vendor/autoload.php';
-require_once('config.php');
+require_once 'config.php';
 
 /**
  * site id of the AP to update

examples/auth_guest_basic.php

@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example 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

examples/auth_guest_with_note.php

@@ -3,21 +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
+ *                 this requires the device to be connected to the WLAN/LAN at moment of
- *              authorization
+ *                 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

examples/block_list.php

@@ -3,27 +3,26 @@
  * 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,
+ * description:    basic PHP script to block a list of mac addresses passed in via command line,
- *              output is to console in non json format
+ *                 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');
+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';
 $debug = false;
 
 /**

examples/change_super_mgmt.php

@@ -3,14 +3,14 @@
  * 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
+ * description:    example basic PHP script to modify the super_mgmt settings for UniFi controller and output results
- *              in json format
+ *                 in json format
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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
@@ -18,7 +18,7 @@ require_once('vendor/autoload.php');
  *
  * NOTE: in this case you need to enter Super Administrator account credentials in config.php
  */
-require_once('config.php');
+require_once 'config.php';
 $site_id = 'default';
 $debug   = false;
 

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

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
  */
 
 /**

examples/create_site.php

@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to create a new site, returns true upon success
+ * description:    example basic PHP script to create a new site, 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 site to use to log in to the controller

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)

examples/delete_site.php

@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to delete a site, returns true upon success
+ * description:    example basic PHP script to delete a site, 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 site to use to log in to the controller

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

examples/disable_switch_port.php

@@ -0,0 +1,78 @@
+<?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, false);
+$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

@@ -3,20 +3,20 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to execute a custom API request using the
+ * description:    example basic PHP script to execute a custom API request using the
- *              custom_api_request() function/method
+ *                 custom_api_request() function/method
  */
 
 /**
  * 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 authorize the device with
@@ -27,10 +27,10 @@ $site_id = '<enter your site id here>';
 /**
  * parameters
  */
-$url          = '/api/s/' . $site_id . '/stat/fwupdate/latest-version';
+$url            = '/api/s/' . $site_id . '/stat/fwupdate/latest-version';
-$request_type = 'GET';
+$request_method = 'GET';
-$payload      = null;
+$payload        = null;
-$return       = 'array';
+$return         = 'array';
 
 /**
  * initialize the UniFi API connection class and log in to the controller and do our thing
@@ -38,7 +38,7 @@ $return       = 'array';
 $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_type, $payload, $return);
+$results          = $unifi_connection->custom_api_request($url, $request_method, $payload, $return);
 
 /**
  * provide feedback in JSON format or as PHP Object

examples/extend_guest_auth.php

@@ -3,19 +3,19 @@
  * 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!

examples/list_alarms.php

@@ -3,19 +3,19 @@
  * 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:    example basic PHP script to pull current alarms from the UniFi controller and output 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 site to use

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

examples/list_connected_users.php

@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: @gahujipo
- * description: example to pull connected users and their details from the UniFi controller and output the results
+ * description:    example to pull connected users and their details 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 which you wish to query

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

examples/list_sites.php

@@ -0,0 +1,46 @@
+<?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

examples/list_user_stats.php

@@ -3,19 +3,19 @@
  * 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
+ * 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');
+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

examples/modify_smartpower_pdu_outlet.php

@@ -0,0 +1,87 @@
+<?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) {
+    $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);
+        echo PHP_EOL;
+    } else {
+        echo 'not a PDU device?';
+        echo PHP_EOL;
+    }
+} else {
+    echo 'we encountered a login error!';
+    echo PHP_EOL;
+}

examples/reconnect_client.php

@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to force a client device to reconnect
+ * description:    example basic PHP script to force a client device to reconnect
  */
 
 /**
  * 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 to reconnect

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,7 +11,7 @@
  * 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

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

examples/unblock_list.php

@@ -3,8 +3,8 @@
  * 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,
+ * description:    basic PHP script to unblock a list of mac addresses passed in via command line,
- *              output is to console in non json format
+ *                 output is to console in non json format
  *
  * usage:
  *  php unblock_list.php <list of comma seperated mac addresses>
@@ -17,13 +17,13 @@
 /**
  * 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';
 $debug = false;
 
 /**

examples/update_ac-iw_ports.php

@@ -3,21 +3,21 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to update the port settings of an AC-IW device
+ * 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
+ *                 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)
+ * note:           requires controller version 5.5.X or higher (to be verified)
  */
 
 /**
  * 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 to log in to the controller

examples/update_device_wlan_settings_5.5.X.php

@@ -3,20 +3,20 @@
  * 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
+ * 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
+ *                 where set_ap_radiosettings() throws an error
  */
 
 /**
  * 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 to log in to the controller

examples/update_switch_poe-mode.php

@@ -13,13 +13,13 @@
 /**
  * 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 to log in to the controller