diff --git a/README.md b/README.md index c46d20e..9b29e0f 100755 --- a/README.md +++ b/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.7.23 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,7 +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.* and higher) +- forget_sta() (supported on controller version 5.9.X and higher) - invite_admin() - revoke_admin() - led_override() @@ -103,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() @@ -237,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.23/unifi_sh_api +- and the API as published by Ubiquiti: https://dl.ubnt.com/unifi/5.8.24/unifi_sh_api ## Important Disclaimer diff --git a/examples/list_user_stats.php b/examples/list_user_stats.php new file mode 100755 index 0000000..7d7feab --- /dev/null +++ b/examples/list_user_stats.php @@ -0,0 +1,51 @@ +'; + +/** + * MAC address of client to fetch stats for + */ +$mac = ''; + +/** + * 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); \ No newline at end of file diff --git a/src/Client.php b/src/Client.php index c911f22..7cf3777 100755 --- a/src/Client.php +++ b/src/Client.php @@ -440,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 = Unix timestamp in seconds * optional parameter = Unix timestamp in seconds * @@ -508,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 = Unix timestamp in seconds * optional parameter = Unix timestamp in seconds * optional parameter = AP MAC address to return stats for @@ -579,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 address of user/client device to return stats for + * optional parameter = Unix timestamp in seconds + * optional parameter = Unix timestamp in seconds + * optional parameter = 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 address of user/client device to return stats for + * optional parameter = Unix timestamp in seconds + * optional parameter = Unix timestamp in seconds + * optional parameter = 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 address of user/client device to return stats for + * optional parameter = Unix timestamp in seconds + * optional parameter = Unix timestamp in seconds + * optional parameter = 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 * -----------------------