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,6 +32,7 @@ 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()
@@ -102,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()
@@ -137,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 ##
@@ -236,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.7.20/unifi_sh_api
+- and the API as published by Ubiquiti: https://dl.ubnt.com/unifi/5.8.24/unifi_sh_api
 
 ## Important Disclaimer
 

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/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/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);

src/Client.php

@@ -138,8 +138,8 @@ class Client
                 }
 
                 if ($code === 400) {
-                     trigger_error('We have received an HTTP response status: 400. Probably a controller login failure');
+                    trigger_error('We have received an HTTP response status: 400. Probably a controller login failure');
-                     return $code;
+                    return $code;
                 }
             }
         }
@@ -358,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
+     * required parameter <user_id> = id of the client-device to be modified
-     * optional parameter <note>    = note to be applied to the user device
+     * 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)
     {
@@ -397,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
      *
@@ -465,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
@@ -536,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
      * -----------------------
@@ -1995,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)
     {