added user/client device stats methods/functions:

stat_5minutes_user()
stat_hourly_user()
stat_daily_user()
added example to demonstrate use of these new functions

README.md

@@ -1,6 +1,6 @@
 ## UniFi Controller API client class
 
-A PHP class which provides access to Ubiquiti's **UniFi Controller API**, versions 4.x.x and 5.x.x of the UniFi Controller software are supported (version 5.6.29 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 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).
 
 This class can be installed using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
 
@@ -20,6 +20,7 @@ The class currently supports the following functions/methods to get/post/put/del
 - create_radius_account()
 - create_site()
 - create_usergroup()
+- create_user()
 - create_voucher()
 - create_wlan()
 - delete_device()
@@ -31,12 +32,16 @@ The class currently supports the following functions/methods to get/post/put/del
 - disable_ap()
 - 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()
@@ -73,9 +78,18 @@ The class currently supports the following functions/methods to get/post/put/del
 - 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()
@@ -90,12 +104,15 @@ The class currently supports the following functions/methods to get/post/put/del
 - stat_allusers()
 - stat_auths()
 - stat_client()
-- stat_5minutes_aps() (supported on controller version 5.5.* and higher)
+- 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.* 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()
@@ -108,6 +125,8 @@ The class currently supports the following functions/methods to get/post/put/del
 - unset_locate_ap() (deprecated but still available as alias)
 - upgrade_device()
 - upgrade_device_external()
+- start_rolling_upgrade()
+- cancel_rolling_upgrade()
 
 Internal functions, getters/setters:
 
@@ -123,7 +142,7 @@ Please refer to the source code for more details on the functions/methods and th
 
 ## Requirements
 
-- a web server with PHP and cURL modules installed (tested on apache2 with PHP Version 5.6.1 and cURL 7.42.1)
+- a 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)
 - network connectivity between this web server and the server and port (normally TCP port 8443) where the UniFi Controller is running
 
 ## Installation ##
@@ -222,7 +241,7 @@ If you would like to contribute code (improvements), please open an issue and in
 This class is based on the 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.6.18-8261dc5066/unifi_sh_api
+- and the API as published by Ubiquiti: https://dl.ubnt.com/unifi/5.8.24/unifi_sh_api
 
 ## Important Disclaimer
 

examples/README.md

@@ -12,4 +12,4 @@ If you would like to share your own example file(s), please open an issue and in
 
 ## Important Disclaimer
 
-Use these examples at your own risk!
+Use these examples at your own risk!

examples/ap_upgrade_firmware.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: @4oo4
+ * description: example script to check and upgrade device firmware (can be scheduled with systemd/cron)
+ *              to the most current version
+ */
+require_once('vendor/autoload.php');
+require_once('config.php');
+
+/**
+ * site id of the AP to update
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * device MAC address formatted with colons, e.g. 'de:ad:be:ef:01:23'
+ */
+$device_mac = '<enter MAC address of device to update>';
+
+/**
+ * initialize the UniFi API connection class, log in to the controller
+ * (this example assumes you have already assigned the correct values in config.php to the variables used)
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, false);
+$login            = $unifi_connection->login();
+
+/**
+ * Run the actual upgrade
+ */
+$results = $unifi_connection->upgrade_device($device_mac);
+
+/**
+ * provide feedback in json format from $response given by upgrade_device();
+ */
+echo json_encode($results, JSON_PRETTY_PRINT);

examples/auth_guest_with_note.php

@@ -3,7 +3,9 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to auth a guest device and attach a note to it
+ * description: example basic PHP script to auth a guest device and attach a note to it,
+ *              this requires the device to be connected to the WLAN/LAN at moment of
+ *              authorization
  */
 
 /**

examples/block_list.php

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

examples/config.template.php

@@ -21,4 +21,4 @@ $controllerversion  = ''; // the version of the Controller software, eg. '4.6.6'
 /**
  * set to true (without quotes) to enable debug output to the browser and the PHP error log
  */
-$debug = false;
+$debug = false;

examples/extend_guest_auth.php

@@ -26,25 +26,25 @@ $set_debug_mode   = $unifi_connection->set_debug($debug);
 $loginresults     = $unifi_connection->login();
 
 if ($loginresults === 400) {
-	print "UniFi controller login failure, please check your credentials in config.php.\n";
+    print "UniFi controller login failure, please check your credentials in config.php.\n";
 } else {
-	$guestlist = $unifi_connection->list_guests();
-	// 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>";
+    $guestlist = $unifi_connection->list_guests();
+    // print "<pre>"; print_r ($guestlist); print "</pre>";
+    // loop thru all known guests
+    foreach ($guestlist as $guest) {
+        // print "<pre>"; print_r ($guest); print "</pre>";
+        print "<pre>" . $guest->_id . " (" . $guest->mac . "), valid until " . date (DATE_ATOM, $guest->end) . " (" . $guest->end . ")</pre>";
 
-		// just a sample: only extend validity of guests which have end date after 2017-04-02
-		if ($guest->end > 1491166482) {
-			// 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";
-		}
-	}
+        // just a sample: only extend validity of guests which have end date after 2017-04-02
+        if ($guest->end > 1491166482) {
+            // extend clients five times = five days
+            if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
+            if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
+            if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
+            if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
+            if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
+        }
+    }
 
-	$logout_results = $unifi_connection->logout();
+    $logout_results = $unifi_connection->logout();
 }

examples/list_ap_connected_users.php

@@ -3,7 +3,7 @@
  * 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
  */
 
@@ -36,7 +36,7 @@ $aps_array        = $unifi_connection->list_aps();
  */
 header('Content-Type: text/html; charset=utf-8');
 foreach ($aps_array as $ap) {
-	if ($ap->type === 'uap') {
-		echo '<b>AP name:</b>' . $ap->name . ' <b>model:</b>' . $ap->model . ' <b># connected clients:</b>' . $ap->num_sta . '<br>';
-	}
+    if ($ap->type === 'uap') {
+        echo '<b>AP name:</b>' . $ap->name . ' <b>model:</b>' . $ap->model . ' <b># connected clients:</b>' . $ap->num_sta . '<br>';
+    }
 }

examples/list_site_health.php

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

examples/list_user_stats.php

@@ -0,0 +1,51 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to pull stats for s epcific user/client device from the UniFi controller and output in json format
+ */
+
+/**
+ * using the composer autoloader
+ */
+require_once('vendor/autoload.php');
+
+/**
+ * include the config file (place your credentials etc. there if not already present)
+ * see the config.template.php file for an example
+ */
+require_once('config.php');
+
+/**
+ * the site to use
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * MAC address of client to fetch stats for
+ */
+$mac = '<MAC address>';
+
+/**
+ * array of attributes to collect
+ * valid attributes:
+ * rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets, tx_packets
+ */
+//$attribs = ['rx_bytes', 'tx_bytes', 'signal', 'rx_rate', 'tx_rate', 'rx_retries', 'tx_retries', 'rx_packets', 'tx_packets'];
+$attribs = ['rx_bytes', 'tx_bytes'];
+
+/**
+ * initialize the UniFi API connection class and log in to the controller and do our thing
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, true);
+$set_debug_mode   = $unifi_connection->set_debug(false);
+$loginresults     = $unifi_connection->login();
+//$data             = $unifi_connection->stat_5minutes_user($mac, null, null, $attribs);
+//$data             = $unifi_connection->stat_hourly_user($mac, null, null, $attribs);
+$data             = $unifi_connection->stat_daily_user($mac, null, null, $attribs);
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($data, JSON_PRETTY_PRINT);

examples/site_provisioning_example/README.md

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

examples/site_provisioning_example/config.template.php

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

examples/site_provisioning_example/provision.php

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

examples/site_provisioning_example/settings.template.php

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

examples/unblock_list.php

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

examples/update_ac-iw_ports.php

@@ -0,0 +1,78 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to update the port settings of an AC-IW device
+ *              FYI: the AC-IW device has three ports, one for the wired uplink and two with external connectors
+ * note: requires controller version 5.5.X or higher (to be verified)
+ */
+
+/**
+ * using the composer autoloader
+ */
+require_once('vendor/autoload.php');
+
+/**
+ * include the config file (place your credentials etc. there if not already present)
+ * see the config.template.php file for an example
+ */
+require_once('config.php');
+
+/**
+ * the site to use to log in to the controller
+ */
+$site_id = '<short site name of a site the credentials used have access to>';
+
+/**
+ * the MAC address of the AC-IW device to re-configure
+ */
+$device_mac = '<enter MAC address>';
+
+/**
+ * port configuration id to apply to port #1 of the AC-IW device
+ * NOTE: port configurations are available through list_portconf()
+ */
+$port_conf_id_port_1 = '<_id of port configuration to apply to port #1>';
+
+/**
+ * port configuration id to apply to port #2 of the AC-IW device
+ * NOTE: port configurations are available through list_portconf()
+ */
+$port_conf_id_port_2 = '<_id of port configuration to apply to port #2>';
+
+/**
+ * prepare the payload to pass on to the API endpoint
+ */
+$new_ports_config = [
+    'port_overrides' => [
+        [
+            'port_idx' => 1,
+            'portconf_id' => $port_conf_id_port_1
+        ],
+        [
+            'port_idx' => 2,
+            'portconf_id' => $port_conf_id_port_2
+        ]
+    ]
+];
+
+/**
+ * initialize the UniFi API connection class and log in to the controller and do our thing
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, 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;
+$update_device    = $unifi_connection->set_device_settings_base($device_id, $new_ports_config);
+
+if(!$update_device){
+    $error = $unifi_connection->get_last_results_raw();
+    echo json_encode($error, JSON_PRETTY_PRINT);
+}
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($update_device, JSON_PRETTY_PRINT);

examples/update_device_wlan_settings_5.5.X.php

@@ -3,7 +3,7 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to update WLAN settings 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
  */
 

src/Client.php

@@ -13,7 +13,6 @@
  * This source file is subject to the MIT license that is bundled
  * with this package in the file LICENSE.md
  */
-
 namespace UniFi_API;
 
 /**
@@ -43,12 +42,12 @@ class Client
      * return a new class instance
      * required parameter <user>       = string; user name to use when connecting to the UniFi controller
      * required parameter <password>   = string; password to use when connecting to the UniFi controller
-     * optional parameter <baseurl>    = string; base URL of the UniFi controller, must include "https://" prefix and port suffix (:8443)
+     * optional parameter <baseurl>    = string; base URL of the UniFi controller, *must* include "https://" prefix and port suffix (:8443)
      * optional parameter <site>       = string; short site name to access, defaults to "default"
      * optional parameter <version>    = string; the version number of the controller, defaults to "5.4.16"
      * optional parameter <ssl_verify> = boolean; whether to validate the controller's SSL certificate or not, a value of true is
-     *                                   recommended for production environments to prevent potential MitM attacks, default (false) is to
-     *                                   not validate the controller certificate
+     *                                   recommended for production environments to prevent potential MitM attacks, default value (false)
+     *                                   is to not validate the controller certificate
      */
     function __construct($user, $password, $baseurl = '', $site = '', $version = '', $ssl_verify = false)
     {
@@ -139,8 +138,8 @@ class Client
                 }
 
                 if ($code === 400) {
-                     trigger_error('We have received an HTTP response status: 400. Probably a controller login failure');
-                     return $code;
+                    trigger_error('We have received an HTTP response status: 400. Probably a controller login failure');
+                    return $code;
                 }
             }
         }
@@ -359,14 +358,57 @@ class Client
     }
 
     /**
-     * Add/modify/remove a client device note
+     * Forget one or more client devices
+     * ---------------------------------
+     * return true on success
+     * required parameter <macs> = array of client MAC addresses
+     *
+     * NOTE:
+     * only supported with controller versions 5.9.X and higher
+     */
+    public function forget_sta($macs)
+    {
+        if (!$this->is_loggedin) return false;
+        $json     = json_encode(['cmd' => 'forget-sta', 'macs' => $macs]);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/cmd/stamgr', 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Create a new user/client-device
+     * -------------------------------
+     * return an array with a single object containing details of the new user/client-device on success, else return false
+     * required parameter <mac>           = client MAC address
+     * required parameter <user_group_id> = _id value for the user group the new user/client-device should belong to which
+     *                                      can be obtained from the output of list_usergroups()
+     * optional parameter <name>          = name to be given to the new user/client-device
+     * optional parameter <note>          = note to be applied to the new user/client-device
+     */
+    public function create_user($mac, $user_group_id, $name = null, $note = null)
+    {
+        if (!$this->is_loggedin) return false;
+        $this->request_type = 'POST';
+        $new_user           = ['mac' => $mac, 'usergroup_id' => $user_group_id];
+        if (!is_null($name)) $new_user['name'] = $name;
+        if (!is_null($note)) {
+            $new_user['note'] = $note;
+            $new_user['noted'] = true;
+        }
+        $json               = ['objects' => [['data' => $new_user]]];
+        $json               = json_encode($json);
+        $response           = $this->exec_curl('/api/s/'.$this->site.'/group/user', 'json='.$json);
+        return $this->process_response($response);
+    }
+
+    /**
+     * Add/modify/remove a client-device note
      * --------------------------------------
      * return true on success
-     * required parameter <user_id> = id of the user device to be modified
-     * optional parameter <note>    = note to be applied to the user device
+     * required parameter <user_id> = id of the client-device to be modified
+     * optional parameter <note>    = note to be applied to the client-device
      *
      * NOTES:
-     * - when note is empty or not set, the existing note for the user will be removed and "noted" attribute set to false
+     * - when note is empty or not set, the existing note for the client-device will be removed and "noted" attribute set to false
      */
     public function set_sta_note($user_id, $note = null)
     {
@@ -398,7 +440,7 @@ class Client
     /**
      * 5 minutes site stats method
      * ---------------------------
-     * returns an array of 5 minutes stats objects for the current site
+     * returns an array of 5-minute stats objects for the current site
      * optional parameter <start> = Unix timestamp in seconds
      * optional parameter <end>   = Unix timestamp in seconds
      *
@@ -466,7 +508,7 @@ class Client
     /**
      * 5 minutes stats method for a single access point or all access points
      * ---------------------------------------------------------------------
-     * returns an array of 5 minutes stats objects
+     * returns an array of 5-minute stats objects
      * optional parameter <start> = Unix timestamp in seconds
      * optional parameter <end>   = Unix timestamp in seconds
      * optional parameter <mac>   = AP MAC address to return stats for
@@ -537,6 +579,92 @@ class Client
         return $this->process_response($response);
     }
 
+    /**
+     * 5 minutes stats method for a single user/client device
+     * ------------------------------------------------------
+     * returns an array of 5-minute stats objects
+     * required parameter <mac>     = MAC address of user/client device to return stats for
+     * optional parameter <start>   = Unix timestamp in seconds
+     * optional parameter <end>     = Unix timestamp in seconds
+     * optional parameter <attribs> = array containing attributes (strings) to be returned, valid values are:
+     *                                rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets, tx_packets
+     *                                default is ['rx_bytes', 'tx_bytes']
+     *
+     * NOTES:
+     * - defaults to the past 12 hours
+     * - only supported with UniFi controller versions 5.8.X and higher
+     * - make sure that the retention policy for 5 minutes stats is set to the correct value in
+     *   the controller settings
+     * - make sure that "Clients Historical Data" has been enabled in the UniFi controller settings in the Maintenance section
+     */
+    public function stat_5minutes_user($mac, $start = null, $end = null, $attribs = null)
+    {
+        if (!$this->is_loggedin) return false;
+        $end      = is_null($end) ? ((time())*1000) : intval($end);
+        $start    = is_null($start) ? $end-(12*3600*1000) : intval($start);
+        $attribs  = is_null($attribs) ? ['time', 'rx_bytes', 'tx_bytes'] : array_merge(['time'], $attribs);
+        $json     = ['attrs' => $attribs, 'start' => $start, 'end' => $end, 'mac' => $mac];
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/stat/report/5minutes.user', 'json='.$json);
+        return $this->process_response($response);
+    }
+
+    /**
+     * Hourly stats method for a a single user/client device
+     * -----------------------------------------------------
+     * returns an array of hourly stats objects
+     * required parameter <mac>     = MAC address of user/client device to return stats for
+     * optional parameter <start>   = Unix timestamp in seconds
+     * optional parameter <end>     = Unix timestamp in seconds
+     * optional parameter <attribs> = array containing attributes (strings) to be returned, valid values are:
+     *                                rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets, tx_packets
+     *                                default is ['rx_bytes', 'tx_bytes']
+     *
+     * NOTES:
+     * - defaults to the past 7*24 hours
+     * - only supported with UniFi controller versions 5.8.X and higher
+     * - make sure that "Clients Historical Data" has been enabled in the UniFi controller settings in the Maintenance section
+     */
+    public function stat_hourly_user($mac, $start = null, $end = null, $attribs = null)
+    {
+        if (!$this->is_loggedin) return false;
+        $end      = is_null($end) ? ((time())*1000) : intval($end);
+        $start    = is_null($start) ? $end-(7*24*3600*1000) : intval($start);
+        $attribs  = is_null($attribs) ? ['time', 'rx_bytes', 'tx_bytes'] : array_merge(['time'], $attribs);
+        $json     = ['attrs' => $attribs, 'start' => $start, 'end' => $end, 'mac' => $mac];
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/stat/report/hourly.user', 'json='.$json);
+        return $this->process_response($response);
+    }
+
+    /**
+     * Daily stats method for a single user/client device
+     * --------------------------------------------------
+     * returns an array of daily stats objects
+     * required parameter <mac>     = MAC address of user/client device to return stats for
+     * optional parameter <start>   = Unix timestamp in seconds
+     * optional parameter <end>     = Unix timestamp in seconds
+     * optional parameter <attribs> = array containing attributes (strings) to be returned, valid values are:
+     *                                rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets, tx_packets
+     *                                default is ['rx_bytes', 'tx_bytes']
+     *
+     * NOTES:
+     * - defaults to the past 7*24 hours
+     * - only supported with UniFi controller versions 5.8.X and higher
+     * - make sure that "Clients Historical Data" has been enabled in the UniFi controller settings in the Maintenance section
+     */
+    public function stat_daily_user($mac, $start = null, $end = null, $attribs = null)
+    {
+        if (!$this->is_loggedin) return false;
+        $end      = is_null($end) ? ((time())*1000) : intval($end);
+        $start    = is_null($start) ? $end-(7*24*3600*1000) : intval($start);
+        $attribs  = is_null($attribs) ? ['time', 'rx_bytes', 'tx_bytes'] : array_merge(['time'], $attribs);
+        $json     = ['attrs' => $attribs, 'start' => $start, 'end' => $end, 'mac' => $mac];
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/stat/report/daily.user', 'json='.$json);
+        return $this->process_response($response);
+    }
+
     /**
      * Show all login sessions
      * -----------------------
@@ -881,6 +1009,142 @@ class Client
         return $this->process_response_boolean($response);
     }
 
+    /**
+     * Change a site's name
+     * --------------------
+     * return true on success
+     * required parameter <site_name> = string; the long name for the site
+     *
+     * NOTES: immediately after being changed, the site will be available in the output of the list_sites() function
+     */
+    public function set_site_name($site_name)
+    {
+        if (!$this->is_loggedin) return false;
+        $json     = json_encode(['cmd' => 'update-site', 'desc' => $site_name]);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/cmd/sitemgr', 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Set site country
+     * ----------------
+     * required parameter <setting> = stdClass object or associative array containing the configuration to apply to the network, must be a (partial)
+     *                                object structured in the same manner as is returned by list_settings() for the "country" key.
+     *                                Valid country codes can be obtained using the list_country_codes() function/method.
+     *                                Do not include the _id property, it will be assigned by the controller and returned upon success.
+     * return true on success
+     */
+    public function set_site_country($country_id, $setting)
+    {
+        if (!$this->is_loggedin) return false;
+        $this->request_type = 'PUT';
+        $json     = json_encode($setting);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/setting/country/'.trim($country_id), 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Set site locale
+     * ---------------
+     * required parameter <setting> = stdClass object or associative array containing the configuration to apply to the network, must be a (partial)
+     *                                object structured in the same manner as is returned by list_settings() for the "locale" key.
+     *                                Do not include the _id property, it will be assigned by the controller and returned upon success.
+     * return true on success
+     */
+    public function set_site_locale($locale_id, $setting)
+    {
+        if (!$this->is_loggedin) return false;
+        $this->request_type = 'PUT';
+        $json     = json_encode($setting);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/setting/locale/'.trim($locale_id), 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Set site snmp
+     * -------------
+     * required parameter <setting> = stdClass object or associative array containing the configuration to apply to the network, must be a (partial)
+     *                                object structured in the same manner as is returned by list_settings() for the "snmp" key.
+     *                                Do not include the _id property, it will be assigned by the controller and returned upon success.
+     * return true on success
+     */
+    public function set_site_snmp($snmp_id, $setting)
+    {
+        if (!$this->is_loggedin) return false;
+        $this->request_type = 'PUT';
+        $json     = json_encode($setting);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/setting/snmp/'.trim($snmp_id), 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Set site mgmt
+     * -------------
+     * required parameter <setting> = stdClass object or associative array containing the configuration to apply to the network, must be a (partial)
+     *                                object structured in the same manner as is returned by list_settings() for the "mgmt" key.
+     *                                Do not include the _id property, it will be assigned by the controller and returned upon success.
+     * return true on success
+     */
+    public function set_site_mgmt($mgmt_id, $setting)
+    {
+        if (!$this->is_loggedin) return false;
+        $this->request_type = 'PUT';
+        $json     = json_encode($setting);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/setting/mgmt/'.trim($mgmt_id), 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Set site guest access
+     * ---------------------
+     * required parameter <setting> = stdClass object or associative array containing the configuration to apply to the network, must be a (partial)
+     *                                object structured in the same manner as is returned by list_settings() for the "guest_access" key.
+     *                                Do not include the _id property, it will be assigned by the controller and returned upon success.
+     * return true on success
+     */
+    public function set_site_guest_access($guest_access_id, $setting)
+    {
+        if (!$this->is_loggedin) return false;
+        $this->request_type = 'PUT';
+        $json     = json_encode($setting);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/setting/guest_access/'.trim($guest_access_id), 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Set site ntp
+     * ------------
+     * required parameter <setting> = stdClass object or associative array containing the configuration to apply to the network, must be a (partial)
+     *                                object structured in the same manner as is returned by list_settings() for the "ntp" key.
+     *                                Do not include the _id property, it will be assigned by the controller and returned upon success.
+     * return true on success
+     */
+    public function set_site_ntp($ntp_id, $setting)
+    {
+        if (!$this->is_loggedin) return false;
+        $this->request_type = 'PUT';
+        $json     = json_encode($setting);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/setting/ntp/'.trim($ntp_id), 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Set site connectivity
+     * ---------------------
+     * required parameter <setting> = stdClass object or associative array containing the configuration to apply to the network, must be a (partial)
+     *                                object structured in the same manner as is returned by list_settings() for the "connectivity" key.
+     *                                Do not include the _id property, it will be assigned by the controller and returned upon success.
+     * return true on success
+     */
+    public function set_site_connectivity($connectivity_id, $setting)
+    {
+        if (!$this->is_loggedin) return false;
+        $this->request_type = 'PUT';
+        $json     = json_encode($setting);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/rest/setting/connectivity/'.trim($connectivity_id), 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
     /**
      * List admins
      * -----------
@@ -906,6 +1170,77 @@ class Client
         return $this->process_response($response);
     }
 
+    /**
+     * Invite a new admin for access to the current site
+     * -------------------------------------------------
+     * returns true on success
+     * required parameter <name>           = string, name to assign to the new admin user
+     * required parameter <email>          = email address to assign to the new admin user
+     * optional parameter <enable_sso>     = boolean, whether or not SSO will be allowed for the new admin
+     *                                       default value is true which enables the SSO capability
+     * optional parameter <readonly>       = boolean, whether or not the new admin will have readonly
+     *                                       permissions, default value is true which gives the new admin
+     *                                       administrator permissions
+     * optional parameter <device_adopt>   = boolean, whether or not the new admin will have permissions to
+     *                                       adopt devices, default value is false. Only applies when readonly
+     *                                       is true.
+     * optional parameter <device_restart> = boolean, whether or not the new admin will have permissions to
+     *                                       restart devices, default value is false. Only applies when readonly
+     *                                       is true.
+     *
+     * NOTES:
+     * - after issuing a valid request, an invite will be sent to the email address provided
+     * - issuing this command against an existing admin will trigger a "re-invite"
+     */
+    public function invite_admin($name, $email, $enable_sso = true, $readonly = false, $device_adopt = false, $device_restart = false)
+    {
+        if (!$this->is_loggedin) return false;
+        $email_valid = filter_var(trim($email), FILTER_VALIDATE_EMAIL);
+        if (!$email_valid) {
+            trigger_error('The email address provided is invalid!');
+            return false;
+        }
+
+        $json = ['name' => trim($name), 'email' => trim($email), 'for_sso' => $enable_sso, 'cmd' => 'invite-admin'];
+        if ($readonly) {
+            $json['role'] = 'readonly';
+            $permissions = [];
+            if ($device_adopt) {
+                $permissions[] = "API_DEVICE_ADOPT";
+            }
+
+            if ($device_restart) {
+                $permissions[] = "API_DEVICE_RESTART";
+            }
+
+            if (count($permissions) > 0) {
+                $json['permissions'] = $permissions;
+            }
+        }
+
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/cmd/sitemgr', 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Revoke an admin
+     * ---------------
+     * returns true on success
+     * required parameter <admin_id> = id of the admin to revoke which can be obtained using the
+     *                                 list_all_admins() method/function
+     *
+     * NOTES:
+     * only non-superadmins account can be revoked
+     */
+    public function revoke_admin($admin_id)
+    {
+        if (!$this->is_loggedin) return false;
+        $json     = json_encode(['admin' => $admin_id, 'cmd' => 'revoke-admin']);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/cmd/sitemgr', 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
     /**
      * List wlan_groups
      * ----------------
@@ -1106,6 +1441,22 @@ class Client
         return $this->process_response($response);
     }
 
+    /**
+     * List country codes
+     * ------------------
+     * returns an array of available country codes
+     *
+     * NOTES:
+     * these codes following the ISO standard:
+     * https://en.wikipedia.org/wiki/ISO_3166-1_numeric
+     */
+    public function list_country_codes()
+    {
+        if (!$this->is_loggedin) return false;
+        $response = $this->exec_curl('/api/s/'.$this->site.'/stat/ccode');
+        return $this->process_response($response);
+    }
+
     /**
      * List port forwarding settings
      * -----------------------------
@@ -1131,8 +1482,8 @@ class Client
     }
 
     /**
-     * List port configuration
-     * -----------------------
+     * List port configurations
+     * ------------------------
      * returns an array of port configurations
      */
     public function list_portconf()
@@ -1356,6 +1707,20 @@ class Client
         return $this->process_response_boolean($response);
     }
 
+    /**
+     * Update guestlogin settings, base
+     * ------------------------------------------
+     * return true on success
+     * required parameter <network_settings> = stdClass object or associative array containing the configuration to apply to the guestlogin, must be a (partial)
+     *                                         object/array structured in the same manner as is returned by list_settings() for the guest_access.
+     */
+    public function set_guestlogin_settings_base($guestlogin_settings) {
+        if (!$this->is_loggedin) return false;
+        $json     = json_encode($guestlogin_settings, JSON_UNESCAPED_SLASHES);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/set/setting/guest_access', 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
     /**
      * Rename access point
      * -------------------
@@ -1718,6 +2083,38 @@ class Client
         return $this->process_response_boolean($response);
     }
 
+    /**
+     * Start rolling upgrade
+     * ---------------------
+     * return true on success
+     *
+     * NOTES:
+     * - updates all access points to the latest firmware known to the controller in a
+     *   staggered/rolling fashion
+     */
+    public function start_rolling_upgrade()
+    {
+        if (!$this->is_loggedin) return false;
+        $json     = ['cmd' => 'set-rollupgrade'];
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/cmd/devmgr', 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Cancel rolling upgrade
+     * ---------------------
+     * return true on success
+     */
+    public function cancel_rolling_upgrade()
+    {
+        if (!$this->is_loggedin) return false;
+        $json     = ['cmd' => 'unset-rollupgrade'];
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/'.$this->site.'/cmd/devmgr', 'json='.$json);
+        return $this->process_response_boolean($response);
+    }
+
     /**
      * Power-cycle the PoE output of a switch port
      * -------------------------------------------
@@ -1727,6 +2124,7 @@ class Client
      *
      * NOTES:
      * - only applies to switches and their PoE ports...
+     * - port must be actually providing power
      */
     public function power_cycle_switch_port($switch_mac, $port_idx)
     {