API client class v1.1.46

- applied patches to update_switch_poe-mode.php as suggested by scrutinizer-ci.com
- placed warning that UniFI OS is not (yet) supported

.gitignore

@@ -1,2 +1,9 @@
 # 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 XML files
+*.xml

README.md

@@ -1,155 +1,19 @@
 ## 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.8.24 has been confirmed to work). It's a standalone version of the class which is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
+A PHP class which 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.35 has been confirmed to work). It's a standalone version of the class which is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
 
-This class can be installed using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
-
-## Methods and functions supported
-
-The class currently supports the following functions/methods to get/post/put/delete data through the UniFi Controller API:
-
-- login()
-- logout()
-- adopt_device()
-- archive_alarm()
-- authorize_guest()
-- block_sta()
-- count_alarms()
-- create_firewallgroup()
-- create_hotspotop()
-- create_network()
-- create_radius_account()
-- create_site()
-- create_usergroup()
-- create_user()
-- create_voucher()
-- create_wlan()
-- delete_device()
-- delete_firewallgroup()
-- delete_network()
-- delete_radius_account()
-- delete_site()
-- delete_usergroup()
-- delete_wlan()
-- disable_ap()
-- edit_firewallgroup()
-- edit_usergroup()
-- extend_guest_validity()
-- forget_sta() (supported on controller version 5.9.X and higher)
-- invite_admin()
-- revoke_admin()
-- led_override()
-- list_admins()
-- list_all_admins()
-- list_alarms()
-- list_aps() (deprecated but still available as alias)
-- list_clients()
-- list_country_codes()
-- list_current_channels()
-- list_dashboard()
-- list_devices()
-- list_dpi_stats()
-- list_dynamicdns()
-- list_events()
-- list_extension()
-- list_firewallgroups()
-- 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()
-- move_device()
-- power_cycle_switch_port()
-- reconnect_sta()
-- rename_ap()
-- restart_ap()
-- revoke_voucher()
-- set_ap_radiosettings()
-- set_device_settings_base()
-- set_guestlogin_settings()
-- set_guestlogin_settings_base()
-- set_locate_ap() (deprecated but still available as alias)
-- set_networksettings_base()
-- set_radius_account_base()
-- set_site_connectivity()
-- set_site_country()
-- set_site_guest_access()
-- set_site_locale()
-- set_site_mgmt()
-- set_site_name()
-- set_site_ntp()
-- set_site_snmp()
-- 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.X and higher)
-- stat_hourly_aps()
-- stat_daily_aps()
-- stat_5minutes_site() (supported on controller version 5.5.X and higher)
-- stat_hourly_site()
-- stat_daily_site()
-- stat_5minutes_user (supported on controller version 5.7.X and higher)
-- stat_hourly_user() (supported on controller version 5.7.X and higher)
-- stat_daily_user() (supported on controller version 5.7.X and higher)
-- 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()
-- start_rolling_upgrade()
-- cancel_rolling_upgrade()
-
-Internal functions, getters/setters:
-
-- set_debug()
-- get_debug()
-- 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.
+This class 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
 
-- a web server with PHP and cURL modules installed (tested on apache2 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.0.7 and cURL 7.37.0)
+- a web server with PHP and cURL modules installed (tested on Apache 2.4 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.2.24 and cURL 7.58.0)
 - network connectivity between this web server and the server and port (normally TCP port 8443) where the UniFi Controller is running
 
-## Installation ##
+## UniFi OS Support
+
+Currently, UniFi OS-based controllers (UniFi Dream Machine Pro) are **not supported** due to several breaking changes to the API.
+
+## Installation
 
 You can use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client class.
 
@@ -224,17 +88,171 @@ Please refer to the `examples/` directory for some more detailed examples which
 
 #### IMPORTANT NOTES:
 
-1. 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.
-
-2. 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:
+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:
 
    `https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard`
 
-   In this case, `jl3z2shm` is the value required for $site_id.
+   `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.
+
+## Functions/methods supported
+
+The class currently supports the following functions/methods to GET/POST/PUT/DELETE data through the UniFi Controller API. Please refer to the source code for more details on the functions/methods and their respective parameters.
+
+- login()
+- logout()
+- adopt_device()
+- archive_alarm()
+- authorize_guest()
+- block_sta()
+- count_alarms()
+- create_firewallgroup()
+- create_hotspotop()
+- create_network()
+- create_radius_account()
+- create_site()
+- create_usergroup()
+- create_user()
+- create_voucher()
+- create_wlan()
+- custom_api_request()
+- delete_device()
+- delete_firewallgroup()
+- delete_network()
+- delete_radius_account()
+- delete_site()
+- delete_usergroup()
+- delete_wlan()
+- disable_ap()
+- edit_client_fixedip()
+- edit_firewallgroup()
+- edit_usergroup()
+- extend_guest_validity()
+- forget_sta() (supported on controller version 5.9.X and higher)
+- invite_admin()
+- assign_existing_admin()
+- revoke_admin()
+- led_override()
+- list_admins()
+- list_all_admins()
+- list_alarms()
+- list_aps() (deprecated but still available as alias)
+- list_backups()
+- list_clients()
+- list_country_codes()
+- list_current_channels()
+- list_dashboard()
+- list_devices()
+- list_dpi_stats()
+- list_dynamicdns()
+- list_events()
+- list_extension()
+- list_firewallgroups()
+- 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()
+- move_device()
+- power_cycle_switch_port()
+- reconnect_sta()
+- rename_ap()
+- restart_ap() (deprecated but still available as alias)
+- restart_device()
+- reboot_cloudkey()
+- revoke_voucher()
+- set_ap_radiosettings()
+- set_device_settings_base()
+- set_guestlogin_settings()
+- set_guestlogin_settings_base()
+- set_ips_settings_base() (supported on controller version 5.9.10 and higher)
+- set_locate_ap() (deprecated but still available as alias)
+- set_networksettings_base()
+- set_radius_account_base()
+- set_site_connectivity()
+- set_site_country()
+- set_site_guest_access()
+- set_site_locale()
+- set_site_mgmt()
+- set_site_name()
+- set_site_ntp()
+- set_site_snmp()
+- set_super_mgmt_settings_base()
+- set_super_smtp_settings_base()
+- set_super_identity_settings_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.X and higher)
+- stat_hourly_aps()
+- stat_daily_aps()
+- stat_5minutes_gateway() (supported on controller version 5.7.X and higher)
+- stat_hourly_gateway() (supported on controller version 5.7.X and higher)
+- stat_daily_gateway() (supported on controller version 5.7.X and higher)
+- stat_5minutes_site() (supported on controller version 5.5.X and higher)
+- stat_hourly_site()
+- stat_daily_site()
+- stat_5minutes_user (supported on controller version 5.7.X and higher)
+- stat_hourly_user() (supported on controller version 5.7.X and higher)
+- stat_daily_user() (supported on controller version 5.7.X and higher)
+- stat_payment()
+- stat_sessions()
+- stat_sites()
+- stat_speedtest_results()
+- stat_ips_events() (supported on controller version 5.9.10 and higher)
+- 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()
+- start_rolling_upgrade()
+- cancel_rolling_upgrade()
+- cmd_stat()
+
+Internal functions, getters/setters:
+
+- set_debug()
+- get_debug()
+- set_site()
+- get_site()
+- get_cookie() (renamed from getcookie())
+- get_last_results_raw()
+- get_last_error_message()
 
 ## 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.
+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
 
@@ -242,10 +260,14 @@ If you would like to contribute code (improvements), please open an issue and in
 
 ## Credits
 
-This class is 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
 - fbagnol: https://github.com/fbagnol/class.unifi.php
-- and the API as published by Ubiquiti: https://dl.ubnt.com/unifi/5.8.24/unifi_sh_api
+
+and the API as published by Ubiquiti:
+
+- https://dl.ui.com/unifi/5.12.35/unifi_sh_api
 
 ## Important Disclaimer
 

examples/README.md

@@ -9,6 +9,17 @@ Then update the contents of your new config.php with your controller details and
 
 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.

examples/ap_scanning_state.php

@@ -19,6 +19,7 @@ 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>';

examples/ap_upgrade_firmware.php

@@ -3,7 +3,7 @@
  * PHP API usage example
  *
  * contributed by: @4oo4
- * description: example script to check and 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
  */
 require_once('vendor/autoload.php');
@@ -11,6 +11,7 @@ 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>';
 

examples/auth_guest_basic.php

@@ -3,7 +3,7 @@
  * 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
  */
 
 /**
@@ -22,6 +22,16 @@ require_once('config.php');
  */
 $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
  */
@@ -42,7 +52,7 @@ $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/block_list.php

@@ -24,19 +24,18 @@ require_once('vendor/autoload.php');
  * see the config.template.php file for an example
  */
 require_once('config.php');
+$debug = false;
 
-$debug=false;
 /**
-  * the MAC address(es) of the device(s) to block
+ * the MAC address(es) of the device(s) to block
  */
-$macs_to_block = explode(',',$argv[1]);
+$macs_to_block = explode(',', $argv[1]);
 
 /**
  * The site to authorize the device with
  */
 $site_id = 'MUST_DEFINE_THIS';
-if ($site_id == "MUST_DEFINE_THIS")
-{
+if ($site_id == "MUST_DEFINE_THIS") {
     print 'ERROR: set the site id in your script';
     return;
 }
@@ -48,10 +47,9 @@ $unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $
 $set_debug_mode   = $unifi_connection->set_debug($debug);
 $loginresults     = $unifi_connection->login(); // always true regardless of site id
 
-foreach ($macs_to_block as &$mac)
-{
+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);
+    $block_result = $unifi_connection->block_sta($mac);
 
     /**
      * NOTE:
@@ -63,22 +61,18 @@ foreach ($macs_to_block as &$mac)
      */
     sleep(1);
 
-    $getid_result   = $unifi_connection->stat_client($mac);
+    $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
-        {
+    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
-        {
+        } else {
             $name = $getid_result[0]->hostname;
         }
         print 'blocked ' . $name . PHP_EOL;
-    }
-    else
-    {
+    } else {
         print 'ERROR: could not block ' . $mac . PHP_EOL;
         print '       check mac address is valid and part of your network' . PHP_EOL;
     }

examples/change_super_mgmt.php

@@ -0,0 +1,65 @@
+<?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, true);
+$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/execute_custom_api_request.php

@@ -0,0 +1,47 @@
+<?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_type = '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_type, $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

@@ -17,7 +17,9 @@ require_once('vendor/autoload.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*";
 
@@ -29,20 +31,39 @@ if ($loginresults === 400) {
     print "UniFi controller login failure, please check your credentials in config.php.\n";
 } else {
     $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
+    /**
+     * loop thru all known guests
+     */
+    foreach ($guestlist as $guest) {
+        print "<pre>" . $guest->_id . " (" . $guest->mac . "), valid until " . date(DATE_ATOM, $guest->end) . " (" . $guest->end . ")</pre>";
+
+        /**
+         * 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";
+            /**
+             * 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";
+            }
         }
     }
 

examples/list_connected_users.php

@@ -0,0 +1,37 @@
+<?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/reconnect_client.php

@@ -0,0 +1,45 @@
+<?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/unblock_list.php

@@ -24,19 +24,18 @@ require_once('vendor/autoload.php');
  * see the config.template.php file for an example
  */
 require_once('config.php');
+$debug = false;
 
-$debug=false;
 /**
  * the MAC addresses of the device(s) to unblock
  */
-$macs_to_unblock = explode(',',$argv[1]);
+$macs_to_unblock = explode(',', $argv[1]);
 
 /**
  * The site to authorize the device with
  */
 $site_id = 'MUST_DEFINE_THIS';
-if ($site_id == "MUST_DEFINE_THIS")
-{
+if ($site_id == "MUST_DEFINE_THIS") {
     print 'ERROR: set the site id in your script';
     return;
 }
@@ -48,10 +47,9 @@ $unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $
 $set_debug_mode   = $unifi_connection->set_debug($debug);
 $loginresults     = $unifi_connection->login(); // always true regardless of site id
 
-foreach ($macs_to_unblock as &$mac)
-{
+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);
+    $block_result = $unifi_connection->unblock_sta($mac);
 
     /**
      * NOTE:
@@ -63,22 +61,17 @@ foreach ($macs_to_unblock as &$mac)
      */
     sleep(1);
 
-    $getid_result   = $unifi_connection->stat_client($mac);
+    $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"))
-        {
+    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
-        {
+        } else {
             $name = $getid_result[0]->hostname;
         }
         print 'unblocked ' . $name . PHP_EOL;
-    }
-    else
-    {
+    } else {
         print 'ERROR: could not unblock ' . $mac . PHP_EOL;
         print '       check mac address is valid and part of your network' . PHP_EOL;
     }

examples/update_ac-iw_ports.php

@@ -67,7 +67,7 @@ $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){
+if (!$update_device) {
     $error = $unifi_connection->get_last_results_raw();
     echo json_encode($error, JSON_PRETTY_PRINT);
 }

examples/update_device_wlan_settings_5.5.X.php

@@ -58,13 +58,13 @@ $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'){
+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'){
+    if ($radio->radio === 'na') {
         $radio->tx_power_mode = $na_tx_power_mode;
         $radio->channel = $na_channel;
     }
@@ -72,7 +72,7 @@ foreach($radio_table as $radio){
 
 $update_device = $unifi_connection->set_device_settings_base($device_id, ['radio_table' => $radio_table]);
 
-if(!$update_device){
+if (!$update_device) {
     $error = $unifi_connection->get_last_results_raw();
     echo json_encode($error, JSON_PRETTY_PRINT);
 }

examples/update_switch_poe-mode.php

@@ -0,0 +1,94 @@
+<?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"
+ */
+
+/**
+ * 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, false);
+$set_debug_mode   = $unifi_connection->set_debug(false);
+$loginresults     = $unifi_connection->login();
+$data             = $unifi_connection->list_devices($device_mac);
+$device_id        = $data[0]->device_id;
+$current_conf     = $data[0]->port_overrides;
+
+/**
+ * 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);