fixed functions assign_existing_admin() and invite_admin() to support controller versions 5.9 and higher because of changes in controller behavior

added function/method assign_existing_admin()
fixed code for function/method invite_admin()

.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,152 +1,12 @@
 ## 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 API**](https://unifi-sdn.ui.com/), versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.10.5 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.10 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 ##
@@ -224,17 +84,164 @@ 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, 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.
+
+## Methods and functions 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()
+- 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()
+- 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()
+- 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_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 +249,10 @@ 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 done 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.ubnt.com/unifi/5.9.29/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/block_list.php

@@ -25,9 +25,9 @@ require_once('vendor/autoload.php');
  */
 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]);
 
@@ -35,8 +35,7 @@ $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,8 +47,7 @@ $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);
 
@@ -65,20 +63,16 @@ foreach ($macs_to_block as &$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/extend_guest_auth.php

@@ -29,20 +29,18 @@ 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>";
+        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";
+            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/unblock_list.php

@@ -29,14 +29,13 @@ $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);
 }