diff --git a/README.md b/README.md index 69acc46..1839625 100755 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ A PHP class that provides access to Ubiquiti's [**UniFi Network Controller**](https://unifi-network.ui.com/) API, versions 4.X.X and 5.X.X of the UniFi Network Controller software are supported (version 5.12.72 has been confirmed to work) as well as UbiOS-based controllers (version 5.12.59 has been confirmed to work). This class is used by our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser). -The package can be installed manually or using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects. +The package can be installed manually or by using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects. ## Requirements @@ -114,6 +114,9 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL - cancel_rolling_upgrade() - cmd_stat() - count_alarms() +- check_controller_update() +- check_firmware_update() +- create_apgroup() (supported with controller versions 6.0.X and higher) - create_dynamicdns() - create_firewallgroup() - create_hotspotop() @@ -125,6 +128,7 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL - create_voucher() - create_wlan() - custom_api_request() +- delete_apgroup() (supported with controller versions 6.0.X and higher) - delete_device() - delete_firewallgroup() - delete_network() @@ -133,6 +137,7 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL - delete_usergroup() - delete_wlan() - disable_ap() +- edit_apgroup() (supported with controller versions 6.0.X and higher) - edit_client_fixedip() - edit_firewallgroup() - edit_usergroup() @@ -143,6 +148,7 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL - list_admins() - list_alarms() - list_all_admins() +- list_apgroups() (supported with controller versions 6.0.X and higher) - list_aps() (deprecated but still available as alias) - list_backups() - list_clients() diff --git a/src/Client.php b/src/Client.php index 000cba0..c5699ec 100755 --- a/src/Client.php +++ b/src/Client.php @@ -10,9 +10,9 @@ namespace UniFi_API; * and the API as published by Ubiquiti: * https://www.ubnt.com/downloads/unifi//unifi_sh_api * - * @package art-of-wifi/unifi-api-client + * @package UniFi Controller API client class * @author Art of WiFi - * @version 1.1.57 + * @version 1.1.59 * @license This class is subject to the MIT license that is bundled with this package in the file LICENSE.md * @example See this directory in the package repository for a variety of examples: * https://github.com/Art-of-WiFi/UniFi-API-client/tree/master/examples @@ -31,7 +31,7 @@ class Client protected $is_loggedin = false; protected $is_unifi_os = false; protected $exec_retries = 0; - protected $class_version = '1.1.58'; + protected $class_version = '1.1.59'; private $cookies = ''; private $request_type = 'GET'; private $request_types_allowed = ['GET', 'POST', 'PUT', 'DELETE']; @@ -473,7 +473,7 @@ class Client } /** - * 5 minutes site stats + * Fetch 5 minutes site stats * * NOTES: * - defaults to the past 12 hours @@ -505,7 +505,7 @@ class Client } /** - * Hourly site stats + * Fetch hourly site stats * * NOTES: * - defaults to the past 7*24 hours @@ -535,7 +535,7 @@ class Client } /** - * Daily site stats + * Fetch daily site stats * * NOTES: * - defaults to the past 52*7*24 hours @@ -565,7 +565,7 @@ class Client } /** - * 5 minutes stats for a single access point or all access points + * Fetch 5 minutes stats for a single access point or all access points * * NOTES: * - defaults to the past 12 hours @@ -593,7 +593,7 @@ class Client } /** - * Hourly stats for a single access point or all access points + * Fetch hourly stats for a single access point or all access points * * NOTES: * - defaults to the past 7*24 hours @@ -620,7 +620,7 @@ class Client } /** - * Daily stats for a single access point or all access points + * Fetch daily stats for a single access point or all access points * * NOTES: * - defaults to the past 7*24 hours @@ -647,7 +647,7 @@ class Client } /** - * 5 minutes stats for a single user/client device + * Fetch 5 minutes stats for a single user/client device * * NOTES: * - defaults to the past 12 hours @@ -675,7 +675,7 @@ class Client } /** - * Hourly stats for a single user/client device + * Fetch hourly stats for a single user/client device * * NOTES: * - defaults to the past 7*24 hours @@ -703,7 +703,7 @@ class Client } /** - * Daily stats for a single user/client device + * Fetch daily stats for a single user/client device * * NOTES: * - defaults to the past 7*24 hours @@ -712,7 +712,7 @@ class Client * the controller settings * - make sure that "Clients Historical Data" has been enabled in the UniFi controller settings in the Maintenance section * - * @param string $mac MAC address of user/client device to return stats fo + * @param string $mac MAC address of user/client device to return stats for * @param int $start optional, Unix timestamp in milliseconds * @param int $end optional, Unix timestamp in milliseconds * @param array $attribs array containing attributes (strings) to be returned, valid values are: @@ -731,15 +731,7 @@ class Client } /** - * 5 minutes gateway stats method - * ------------------------------ - * returns an array of 5-minute stats objects for the gateway belonging to the current site - * optional parameter = Unix timestamp in milliseconds - * optional parameter = Unix timestamp in milliseconds - * optional parameter = array containing attributes (strings) to be returned, valid values are: - * mem, cpu, loadavg_5, lan-rx_errors, lan-tx_errors, lan-rx_bytes, - * lan-tx_bytes, lan-rx_packets, lan-tx_packets, lan-rx_dropped, lan-tx_dropped - * default is ['time', 'mem', 'cpu', 'loadavg_5'] + * Fetch 5 minutes gateway stats * * NOTES: * - defaults to the past 12 hours @@ -747,6 +739,14 @@ class Client * - make sure that the retention policy for 5 minutes stats is set to the correct value in * the controller settings * - requires a USG + * + * @param int $start optional, Unix timestamp in milliseconds + * @param int $end optional, Unix timestamp in milliseconds + * @param array $attribs array containing attributes (strings) to be returned, valid values are: + * mem, cpu, loadavg_5, lan-rx_errors, lan-tx_errors, lan-rx_bytes, + * lan-tx_bytes, lan-rx_packets, lan-tx_packets, lan-rx_dropped, lan-tx_dropped + * default is ['time', 'mem', 'cpu', 'loadavg_5'] + * @return array returns an array of 5-minute stats objects for the gateway belonging to the current site */ public function stat_5minutes_gateway($start = null, $end = null, $attribs = null) { @@ -759,19 +759,19 @@ class Client } /** - * Hourly gateway stats method - * --------------------------- - * returns an array of hourly stats objects for the gateway belonging to the current site - * optional parameter = Unix timestamp in milliseconds - * optional parameter = Unix timestamp in milliseconds - * optional parameter = array containing attributes (strings) to be returned, valid values are: - * mem, cpu, loadavg_5, lan-rx_errors, lan-tx_errors, lan-rx_bytes, - * lan-tx_bytes, lan-rx_packets, lan-tx_packets, lan-rx_dropped, lan-tx_dropped - * default is ['time', 'mem', 'cpu', 'loadavg_5'] + * Fetch hourly gateway stats * * NOTES: * - defaults to the past 7*24 hours * - requires a USG + * + * @param int $start optional, Unix timestamp in milliseconds + * @param int $end optional, Unix timestamp in milliseconds + * @param array $attribs array containing attributes (strings) to be returned, valid values are: + * mem, cpu, loadavg_5, lan-rx_errors, lan-tx_errors, lan-rx_bytes, + * lan-tx_bytes, lan-rx_packets, lan-tx_packets, lan-rx_dropped, lan-tx_dropped + * default is ['time', 'mem', 'cpu', 'loadavg_5'] + * @return array returns an array of hourly stats objects for the gateway belonging to the current site */ public function stat_hourly_gateway($start = null, $end = null, $attribs = null) { @@ -784,19 +784,19 @@ class Client } /** - * Daily gateway stats method - * -------------------------- - * returns an array of daily stats objects for the gateway belonging to the current site - * optional parameter = Unix timestamp in milliseconds - * optional parameter = Unix timestamp in milliseconds - * optional parameter = array containing attributes (strings) to be returned, valid values are: - * mem, cpu, loadavg_5, lan-rx_errors, lan-tx_errors, lan-rx_bytes, - * lan-tx_bytes, lan-rx_packets, lan-tx_packets, lan-rx_dropped, lan-tx_dropped - * default is ['time', 'mem', 'cpu', 'loadavg_5'] + * Fetch daily gateway stats * * NOTES: * - defaults to the past 52*7*24 hours * - requires a USG + * + * @param int $start optional, Unix timestamp in milliseconds + * @param int $end optional, Unix timestamp in milliseconds + * @param array $attribs array containing attributes (strings) to be returned, valid values are: + * mem, cpu, loadavg_5, lan-rx_errors, lan-tx_errors, lan-rx_bytes, + * lan-tx_bytes, lan-rx_packets, lan-tx_packets, lan-rx_dropped, lan-tx_dropped + * default is ['time', 'mem', 'cpu', 'loadavg_5'] + * @return array returns an array of hourly stats objects for the gateway belonging to the current site */ public function stat_daily_gateway($start = null, $end = null, $attribs = null) { @@ -809,15 +809,15 @@ class Client } /** - * Method to fetch speed test results - * ---------------------------------- - * returns an array of speed test result objects - * optional parameter = Unix timestamp in milliseconds - * optional parameter = Unix timestamp in milliseconds + * Fetch speed test results * * NOTES: * - defaults to the past 24 hours * - requires a USG + * + * @param int $start optional, Unix timestamp in milliseconds + * @param int $end optional, Unix timestamp in milliseconds + * @return array returns an array of speed test result objects */ public function stat_speedtest_results($start = null, $end = null) { @@ -828,18 +828,19 @@ class Client return $this->fetch_results('/api/s/' . $this->site . '/stat/report/archive.speedtest', $payload); } + /** - * Method to fetch IPS/IDS event - * ----------------------------- - * returns an array of IPS/IDS event objects - * optional parameter = Unix timestamp in milliseconds - * optional parameter = Unix timestamp in milliseconds - * optional parameter = Maximum number of events to return, defaults to 10000 + * Fetch IPS/IDS events * * NOTES: * - defaults to the past 24 hours * - requires a USG * - supported in UniFi controller versions 5.9.X and higher + * + * @param int $start optional, Unix timestamp in milliseconds + * @param int $end optional, Unix timestamp in milliseconds + * @param int $limit optional, maximum number of events to return, defaults to 10000 + * @return array returns an array of IPS/IDS event objects */ public function stat_ips_events($start = null, $end = null, $limit = null) { @@ -852,16 +853,16 @@ class Client } /** - * Show all login sessions - * ----------------------- - * returns an array of login session objects for all devices or a single device - * optional parameter = Unix timestamp in seconds - * optional parameter = Unix timestamp in seconds - * optional parameter = client MAC address to return sessions for (can only be used when start and end are also provided) - * optional parameter = client type to return sessions for, can be 'all', 'guest' or 'user'; default value is 'all' + * Fetch login sessions * * NOTES: * - defaults to the past 7*24 hours + * + * @param int $start optional, Unix timestamp in milliseconds + * @param int $end optional, Unix timestamp in milliseconds + * @param string $mac optional, client MAC address to return sessions for (can only be used when start and end are also provided) + * @param string $type optional, client type to return sessions for, can be 'all', 'guest' or 'user'; default value is 'all' + * @return array returns an array of login session objects for all devices or a single device */ public function stat_sessions($start = null, $end = null, $mac = null, $type = 'all') { @@ -880,11 +881,14 @@ class Client } /** - * Show latest 'n' login sessions for a single client device - * --------------------------------------------------------- - * returns an array of latest login session objects for given client device - * required parameter = client MAC address - * optional parameter = maximum number of sessions to get (default value is 5) + * Fetch latest 'n' login sessions for a single client device + * + * NOTES: + * - defaults to the past 7*24 hours + * + * @param string $mac client MAC address + * @param int $limit optional, maximum number of sessions to get (default value is 5) + * @return array returns an array of login session objects for all devices or a single device */ public function stat_sta_sessions_latest($mac, $limit = null) { @@ -895,14 +899,14 @@ class Client } /** - * Show all authorizations - * ----------------------- - * returns an array of authorization objects - * optional parameter = Unix timestamp in seconds - * optional parameter = Unix timestamp in seconds + * Fetch authorizations * * NOTES: * - defaults to the past 7*24 hours + * + * @param int $start optional, Unix timestamp in milliseconds + * @param int $end optional, Unix timestamp in milliseconds + * @return array returns an array of authorization objects */ public function stat_auths($start = null, $end = null) { @@ -914,14 +918,14 @@ class Client } /** - * List all client devices ever connected to the site - * -------------------------------------------------- - * returns an array of client device objects - * optional parameter = hours to go back (default is 8760 hours or 1 year) + * Fetch client devices that connected to the site within given timeframe * * NOTES: * - is only used to select clients that were online within that period, * the returned stats per client are all-time totals, irrespective of the value of + * + * @param int $historyhours optional, hours to go back (default is 8760 hours or 1 year) + * @return array returns an array of client device objects */ public function stat_allusers($historyhours = 8760) { @@ -931,10 +935,13 @@ class Client } /** - * List guest devices - * ------------------ - * returns an array of guest device objects with valid access - * optional parameter = time frame in hours to go back to list guests with valid access (default = 24*365 hours) + * Fetch guest devices + * + * NOTES: + * - defaults to the past 7*24 hours + * + * @param int $within optional, time frame in hours to go back to list guests with valid access (default = 24*365 hours) + * @return array returns an array of guest device objects with valid access */ public function list_guests($within = 8760) { @@ -944,10 +951,10 @@ class Client } /** - * List online client device(s) - * ---------------------------- - * returns an array of online client device objects, or in case of a single device request, returns a single client device object - * optional parameter = the MAC address of a single online client device for which the call must be made + * Fetch online client device(s) + * + * @param string $client_mac optional, the MAC address of a single online client device for which the call must be made + * @return array returns an array of online client device objects, or in case of a single device request, returns a single client device object */ public function list_clients($client_mac = null) { @@ -955,10 +962,10 @@ class Client } /** - * Get details for a single client device - * -------------------------------------- - * returns an object with the client device information - * required parameter = client device MAC address + * Fetch details for a single client device + * + * @param string $client_mac optional, client device MAC address + * @return array returns an object with the client device information */ public function stat_client($client_mac) { @@ -967,10 +974,10 @@ class Client /** * Assign client device to another group - * ------------------------------------- - * return true on success - * required parameter = id of the user device to be modified - * required parameter = id of the user group to assign user to + * + * @param string $user_id id of the user device to be modified + * @param string $group_id id of the user group to assign user to + * @return bool returns true upon success */ public function set_usergroup($user_id, $group_id) { @@ -981,13 +988,12 @@ class Client /** * Update client fixedip (using REST) - * ------------------------------ - * returns an array containing a single object with attributes of the updated client on success - * required parameter = _id value for the client - * required parameter = boolean defining whether if use_fixedip is true or false - * optional parameter = _id value for the network where the ip belongs to - * optional parameter = value of client's fixed_ip field * + * @param string $client_id _id value for the client + * @param bool $use_fixedip determines whether use_fixedip is true or false + * @param string $network_id optional, _id value for the network where the ip belongs to + * @param string $fixed_ip optional, IP address, value of client's fixed_ip field + * @return array returns an array containing a single object with attributes of the updated client on success */ public function edit_client_fixedip($client_id, $use_fixedip, $network_id = null, $fixed_ip = null) { @@ -1011,9 +1017,9 @@ class Client } /** - * List user groups - * ---------------- - * returns an array of user group objects + * Fetch user groups + * + * @return array returns an array of user group objects */ public function list_usergroups() { @@ -1037,13 +1043,13 @@ class Client /** * Modify user group (using REST) - * ------------------------------ - * returns an array containing a single object with attributes of the updated usergroup on success - * required parameter = _id value of the user group - * required parameter = _id value of the site - * required parameter = name of the user group - * optional parameter = limit download bandwidth in Kbps (default = -1, which sets bandwidth to unlimited) - * optional parameter = limit upload bandwidth in Kbps (default = -1, which sets bandwidth to unlimited) + * + * @param string $group_id _id value of the user group + * @param string $site_id _id value of the site + * @param string $group_name name of the user group + * @param integer $group_dn limit download bandwidth in Kbps (default = -1, which sets bandwidth to unlimited) + * @param integer $group_up limit upload bandwidth in Kbps (default = -1, which sets bandwidth to unlimited) + * @return array returns an array containing a single object with attributes of the updated usergroup on success */ public function edit_usergroup($group_id, $site_id, $group_name, $group_dn = -1, $group_up = -1) { @@ -1061,9 +1067,9 @@ class Client /** * Delete user group (using REST) - * ------------------------------ - * returns true on success - * required parameter = _id value of the user group + * + * @param string $group_id _id value of the user group to delete + * @return bool returns true on success */ public function delete_usergroup($group_id) { @@ -1072,6 +1078,65 @@ class Client return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/usergroup/' . trim($group_id)); } + /** + * Fetch AP groups + * + * @return array returns an array containing the current AP groups on success + */ + public function list_apgroups() + { + return $this->fetch_results('/v2/api/site/' . $this->site . '/apgroups/' . trim($group_id)); + } + + /** + * Create AP group + * + * @param string $group_name name to assign to the AP group + * @param array $device_macs optional, array containing the MAC addresses (strings) of the APs to add to the new group + * @return object returns a single object with attributes of the new AP group on success + */ + public function create_apgroup($group_name, $device_macs = []) + { + $payload = ['device_macs' => $device_macs, 'name' => $group_name]; + + return $this->fetch_results('/v2/api/site/' . $this->site . '/apgroups', $payload); + } + + /** + * Modify AP group + * + * @param string $group_id _id value of the AP group to modify + * @param string $group_name name to assign to the AP group + * @param array $device_macs array containing the members of the AP group which overwrites the existing + * group_members (passing an empty array will clear the AP member list) + * @return object returns a single object with attributes of the updated AP group on success + */ + public function edit_apgroup($group_id, $group_name, $device_macs) + { + $this->request_type = 'PUT'; + $payload = [ + '_id' => $group_id, + 'attr_no_delete' => false, + 'name' => $group_name, + 'device_macs' => $device_macs + ]; + + return $this->fetch_results('/v2/api/site/' . $this->site . '/apgroups/' . trim($group_id), $payload); + } + + /** + * Delete AP group + * + * @param string $group_id _id value of the AP group to delete + * @return bool returns true on success + */ + public function delete_apgroup($group_id) + { + $this->request_type = 'DELETE'; + + return $this->fetch_results_boolean('/v2/api/site/' . $this->site . '/apgroups/' . trim($group_id)); + } + /** * List firewall groups (using REST) * --------------------------------- @@ -2547,6 +2612,35 @@ class Client return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/evtmgr', $payload); } + /** + * Check controller update + * + * NOTE: + * triggers an update of the controller cached known latest version. + * + * @return array returns an array with a single object containing details of the current known latest controller version info + * on success, else returns false + */ + public function check_controller_update() + { + return $this->fetch_results('/api/s/' . $this->site . '/stat/fwupdate/latest-version'); + } + + /** + * Check firmware update + * + * NOTE: + * triggers a Device Firmware Update in Classic Settings > System settings > Maintenance + * + * @return bool returns true upon success + */ + public function check_firmware_update() + { + $payload = ['cmd' => 'check-firmware-update']; + + return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/productinfo', $payload); + } + /** * Upgrade a device to the latest firmware * --------------------------------------- @@ -3236,11 +3330,26 @@ class Client */ if (isset($response->meta->msg)) { $this->last_error_message = $response->meta->msg; + if ($this->debug) { + trigger_error('Debug: Last error message: ' . $this->last_error_message); + } } + } + } - if ($this->debug) { - trigger_error('Debug: Last error message: ' . $this->last_error_message); + /** + * to deal with a response coming from the new v2 API + */ + if(strpos($path, '/v2/api/') === 0) { + if (isset($response->errorCode)) { + if (isset($response->message)) { + $this->last_error_message = $response->message; + if ($this->debug) { + trigger_error('Debug: Last error message: ' . $this->last_error_message); + } } + } else { + return $response; } }