From 2b34890a67fda58a586e6fa7d70002062f723c6d Mon Sep 17 00:00:00 2001 From: malle-pietje Date: Sat, 20 Jun 2020 16:12:13 +0200 Subject: [PATCH] - minor syntax improvement based on Scrutinizer feedback - added create_dynamicdns() and set_dynamicdns() methods, "borrowed" routes from @smos - made a start at changing the function/method comments to PHPDoc format (PSR-5) which will support auto-generated class documentation (https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#5-the-phpdoc-format) --- README.md | 84 +++++++++---------- src/Client.php | 215 +++++++++++++++++++++++++++---------------------- 2 files changed, 160 insertions(+), 139 deletions(-) diff --git a/README.md b/README.md index 07ada86..e66481f 100755 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ## UniFi Controller API client class -A PHP class that provides access to Ubiquiti's [**UniFi SDN Controller**](https://unifi-sdn.ui.com/) API, versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.12.66 has been confirmed to work) as well as UbiOS-based controllers (version 5.12.59 has been confirmed to work). This class is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser). +A PHP class that provides access to Ubiquiti's [**UniFi SDN Controller**](https://unifi-sdn.ui.com/) API, versions 4.X.X and 5.X.X of the UniFi SDN 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. @@ -23,7 +23,7 @@ You can use [Composer](#composer), [Git](#git) or simply [Download the Release]( ### Composer -The preferred method is via [composer](https://getcomposer.org). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed. +The preferred installation method is through [composer](https://getcomposer.org). Follow these [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed. Once composer is installed, simply execute this command from the shell in your project directory: @@ -108,16 +108,20 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL - logout() - adopt_device() - archive_alarm() +- assign_existing_admin() - authorize_guest() - block_sta() +- cancel_rolling_upgrade() +- cmd_stat() - count_alarms() +- create_dynamicdns() - create_firewallgroup() - create_hotspotop() - create_network() - create_radius_account() - create_site() -- create_usergroup() - create_user() +- create_usergroup() - create_voucher() - create_wlan() - custom_api_request() @@ -135,12 +139,10 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL - extend_guest_validity() - forget_sta() (supported on controller version 5.9.X and higher) - invite_admin() -- assign_existing_admin() -- revoke_admin() - led_override() - list_admins() -- list_all_admins() - list_alarms() +- list_all_admins() - list_aps() (deprecated but still available as alias) - list_backups() - list_clients() @@ -177,14 +179,16 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL - locate_ap() - move_device() - power_cycle_switch_port() +- reboot_cloudkey() - reconnect_sta() - rename_ap() - restart_ap() (deprecated but still available as alias) - restart_device() -- reboot_cloudkey() +- revoke_admin() - revoke_voucher() - set_ap_radiosettings() - set_device_settings_base() +- set_dynamicdns() - set_guestlogin_settings() - set_guestlogin_settings_base() - set_ips_settings_base() (supported on controller version 5.9.10 and higher) @@ -199,11 +203,11 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL - set_site_name() - set_site_ntp() - set_site_snmp() -- set_super_mgmt_settings_base() -- set_super_smtp_settings_base() -- set_super_identity_settings_base() - set_sta_name() - set_sta_note() +- set_super_identity_settings_base() +- set_super_mgmt_settings_base() +- set_super_smtp_settings_base() - set_usergroup() - set_wlan_mac_filter() - set_wlansettings() @@ -213,26 +217,27 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL - site_ledson() (deprecated but still available as alias) - spectrum_scan() - spectrum_scan_state() +- start_rolling_upgrade() +- stat_5minutes_aps() (supported on controller version 5.5.X and higher) +- stat_5minutes_gateway() (supported on controller version 5.7.X and higher) +- stat_5minutes_site() (supported on controller version 5.5.X and higher) +- stat_5minutes_user (supported on controller version 5.7.X and higher) - stat_allusers() - stat_auths() - stat_client() -- stat_5minutes_aps() (supported on controller version 5.5.X and higher) -- stat_hourly_aps() - stat_daily_aps() -- stat_5minutes_gateway() (supported on controller version 5.7.X and higher) -- stat_hourly_gateway() (supported on controller version 5.7.X and higher) - stat_daily_gateway() (supported on controller version 5.7.X and higher) -- stat_5minutes_site() (supported on controller version 5.5.X and higher) -- stat_hourly_site() - stat_daily_site() -- stat_5minutes_user (supported on controller version 5.7.X and higher) -- stat_hourly_user() (supported on controller version 5.7.X and higher) - stat_daily_user() (supported on controller version 5.7.X and higher) +- stat_hourly_aps() +- stat_hourly_gateway() (supported on controller version 5.7.X and higher) +- stat_hourly_site() +- stat_hourly_user() (supported on controller version 5.7.X and higher) +- stat_ips_events() (supported on controller version 5.9.10 and higher) - stat_payment() - stat_sessions() - stat_sites() - stat_speedtest_results() -- stat_ips_events() (supported on controller version 5.9.10 and higher) - stat_sta_sessions_latest() - stat_status() - stat_sysinfo() @@ -242,32 +247,29 @@ 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() -- cmd_stat() Other functions, getters/setters: -- set_debug() -- get_debug() -- set_site() -- get_site() -- set_cookies() -- get_cookies() -- get_cookie() (renamed from getcookie(), deprecated but still available, use get_cookies() instead) -- get_last_results_raw() -- get_last_error_message() -- set_request_type() -- get_request_type() -- set_ssl_verify_peer() -- get_ssl_verify_peer() -- set_ssl_verify_host() -- get_ssl_verify_host() -- set_connection_timeout() -- get_connection_timeout() -- set_is_unifi_os() -- get_is_unifi_os() - get_class_version() +- get_connection_timeout() +- get_cookie() (renamed from getcookie(), deprecated but still available, use get_cookies() instead) +- get_cookies() +- get_debug() +- get_is_unifi_os() +- get_last_error_message() +- get_last_results_raw() +- get_request_type() +- get_site() +- get_ssl_verify_host() +- get_ssl_verify_peer() +- set_connection_timeout() +- set_cookies() +- set_debug() +- set_is_unifi_os() +- set_request_type() +- set_site() +- set_ssl_verify_host() +- set_ssl_verify_peer() ## Need help or have suggestions? diff --git a/src/Client.php b/src/Client.php index eff1694..1dd0ac7 100755 --- a/src/Client.php +++ b/src/Client.php @@ -1,6 +1,8 @@ /unifi_sh_api * - * Copyright (c) 2017, Art of WiFi - * - * This source file is subject to the MIT license that is bundled - * with this package in the file LICENSE.md - */ - -namespace UniFi_API; - -/** - * the UniFi API client class + * @package art-of-wifi/unifi-api-client + * @author Art of WiFi + * @version 1.1.57 + * @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 */ class Client { @@ -33,7 +31,7 @@ class Client protected $is_loggedin = false; protected $is_unifi_os = false; protected $exec_retries = 0; - protected $class_version = '1.1.56'; + protected $class_version = '1.1.57'; private $cookies = ''; private $request_type = 'GET'; private $request_types_allowed = ['GET', 'POST', 'PUT', 'DELETE']; @@ -45,18 +43,17 @@ class Client /** * Construct an instance of the UniFi API client class - * --------------------------------------------------- - * returns a new class instance - * required parameter = string; user name to use when connecting to the UniFi controller - * required parameter = string; password to use when connecting to the UniFi controller - * optional parameter = string; base URL of the UniFi controller which *must* include 'https://'' prefix, - * a port suffix (e.g. :8443) is required for non-UniFi OS controllers, - * do not add trailing slashes, defaults to 'https://127.0.0.1:8443' - * optional parameter = string; short site name to access, defaults to 'default' - * optional parameter = string; the version number of the controller - * optional parameter = 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 value (false) - * disables validation of the controller certificate + * + * @param string $user user name to use when connecting to the UniFi controller + * @param string $password password to use when connecting to the UniFi controller + * @param string $baseurl optional, base URL of the UniFi controller which *must* include 'https://'' prefix, + * a port suffix (e.g. :8443) is required for non-UniFi OS controllers, + * do not add trailing slashes, defaults to 'https://127.0.0.1:8443' + * @param string $site optional, short site name to access, defaults to 'default' + * @param string $version optional, the version number of the controller + * @param bool $ssl_verify optional, 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 value (false) + * disables validation of the controller certificate */ public function __construct($user, $password, $baseurl = '', $site = '', $version = '', $ssl_verify = false) { @@ -81,7 +78,7 @@ class Client $this->version = trim($version); } - if ((boolean)$ssl_verify === true) { + if ((boolean) $ssl_verify === true) { $this->curl_ssl_verify_peer = true; $this->curl_ssl_verify_host = 2; } @@ -91,8 +88,7 @@ class Client * This method is called as soon as there are no other references to the class instance * https://www.php.net/manual/en/language.oop5.decon.php * - * NOTES: - * to force the class instance to log out when you're done, simply call logout() + * NOTE: to force the class instance to log out when you're done, simply call logout() */ public function __destruct() { @@ -113,8 +109,8 @@ class Client /** * Login to the UniFi controller - * ----------------------------- - * returns true upon success + * + * @return bool returns true upon success */ public function login() { @@ -240,8 +236,8 @@ class Client /** * Logout from the UniFi controller - * -------------------------------- - * returns true upon success + * + * @return bool returns true upon success */ public function logout() { @@ -298,14 +294,14 @@ class Client /** * Authorize a client device - * ------------------------- - * return true on success - * required parameter = client MAC address - * required parameter = minutes (from now) until authorization expires - * optional parameter = upload speed limit in kbps - * optional parameter = download speed limit in kbps - * optional parameter = data transfer limit in MB - * optional parameter = AP MAC address to which client is connected, should result in faster authorization + * + * @param string $mac client MAC address + * @param int $minutes minutes (from now) until authorization expires + * @param int $up optional, upload speed limit in kbps + * @param int $down optional, download speed limit in kbps + * @param int $MBytes optional, data transfer limit in MB + * @param int $ap_mac optional, AP MAC address to which client is connected, should result in faster authorization + * @return bool returns true upon success */ public function authorize_guest($mac, $minutes, $up = null, $down = null, $MBytes = null, $ap_mac = null) { @@ -335,9 +331,9 @@ class Client /** * Unauthorize a client device - * --------------------------- - * return true on success - * required parameter = client MAC address + * + * @param string $mac client MAC address + * @return bool returns true upon success */ public function unauthorize_guest($mac) { @@ -348,9 +344,9 @@ class Client /** * Reconnect a client device - * ------------------------- - * return true on success - * required parameter = client MAC address + * + * @param string $mac client MAC address + * @return bool returns true upon success */ public function reconnect_sta($mac) { @@ -361,9 +357,9 @@ class Client /** * Block a client device - * --------------------- - * return true on success - * required parameter = client MAC address + * + * @param string $mac client MAC address + * @return bool returns true upon success */ public function block_sta($mac) { @@ -374,9 +370,9 @@ class Client /** * Unblock a client device - * ----------------------- - * return true on success - * required parameter = client MAC address + * + * @param string $mac client MAC address + * @return bool returns true upon success */ public function unblock_sta($mac) { @@ -387,13 +383,13 @@ class Client /** * Forget one or more client devices - * --------------------------------- - * return true on success - * required parameter = array of client MAC addresses * * NOTE: * only supported with controller versions 5.9.X and higher, can be * slow (up to 5 minutes) on larger controllers + * + * @param array $macs array of client MAC addresses (strings) + * @return bool returns true upon success */ public function forget_sta($macs) { @@ -404,15 +400,15 @@ class Client /** * 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 = client MAC address - * required parameter = _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 to be given to the new user/client-device - * optional parameter = note to be applied to the new user/client-device - * optional parameter = boolean; defines whether the new user/client-device is a guest or not - * optional parameter = boolean; defines whether the new user/client-device is wired or not + * + * @param string $mac client MAC address + * @param string $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() + * @param string $name optional, name to be given to the new user/client-device + * @param string $note optional, note to be applied to the new user/client-device + * @param bool $is_guest optional, defines whether the new user/client-device is a guest or not + * @param bool $is_wired optional, defines whether the new user/client-device is wired or not + * @return array returns an array with a single object containing details of the new user/client-device on success, else returns false */ public function create_user($mac, $user_group_id, $name = null, $note = null, $is_guest = null, $is_wired = null) { @@ -441,13 +437,11 @@ class Client /** * Add/modify/remove a client-device note - * -------------------------------------- - * return true on success - * required parameter = id of the client-device to be modified - * optional parameter = note to be applied to the client-device * - * NOTES: - * - when note is empty or not set, the existing note for the client-device will be removed and "noted" attribute set to false + * @param string $user_id id of the client-device to be modified + * @param string $note optional, note to be applied to the client-device, when empty or not set, + * the existing note for the client-device will be removed and "noted" attribute set to false + * @return bool returns true upon success */ public function set_sta_note($user_id, $note = null) { @@ -459,13 +453,11 @@ class Client /** * Add/modify/remove a client device name - * -------------------------------------- - * return true on success - * required parameter = id of the client device to be modified - * optional parameter = name to be applied to the client device * - * NOTES: - * - when name is empty or not set, the existing name for the client device will be removed + * @param string $user_id id of the client-device to be modified + * @param string $note optional, name to be applied to the client device, when empty or not set, + * the existing name for the client device will be removed + * @return bool returns true upon success */ public function set_sta_name($user_id, $name = null) { @@ -476,16 +468,16 @@ class Client /** * 5 minutes site stats method - * --------------------------- - * returns an array of 5-minute stats objects for the current site - * optional parameter = Unix timestamp in milliseconds - * optional parameter = Unix timestamp in milliseconds * * NOTES: * - defaults to the past 12 hours * - this function/method is only supported on controller versions 5.5.* and later * - make sure that the retention policy for 5 minutes stats is set to the correct value in * the controller settings + * + * @param int $start optional, Unix timestamp in milliseconds + * @param int $end optional, Unix timestamp in milliseconds + * @return array returns an array of 5-minute stats objects for the current site */ public function stat_5minutes_site($start = null, $end = null) { @@ -1500,7 +1492,7 @@ class Client return false; } - $payload= [ + $payload = [ 'name' => trim($name), 'email' => trim($email), 'for_sso' => $enable_sso, @@ -1832,16 +1824,6 @@ class Client return $this->fetch_results('/api/s/' . $this->site . '/list/portforward'); } - /** - * List dynamic DNS settings - * ------------------------- - * returns an array of dynamic DNS settings - */ - public function list_dynamicdns() - { - return $this->fetch_results('/api/s/' . $this->site . '/list/dynamicdns'); - } - /** * List port configurations * ------------------------ @@ -2221,6 +2203,43 @@ class Client return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/sitemgr', $payload); } + /** + * List dynamic DNS settings (using REST) + * -------------------------------------- + * returns an array of dynamic DNS settings + */ + public function list_dynamicdns() + { + return $this->fetch_results('/api/s/' . $this->site . '/rest/dynamicdns'); + } + + /** + * Create dynamic DNS settings, base (using REST) + * ---------------------------------------------- + * return true on success + * required parameter = stdClass object or associative array containing the configuration to apply to the site, must be a + * (partial) object/array structured in the same manner as is returned by list_dynamicdns() for the site. + */ + public function create_dynamicdns($payload) + { + return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/dynamicdns', $payload); + } + + /** + * Update site dynamic DNS, base (using REST) + * ------------------------------------------ + * return true on success + * required parameter = 24 char string; _id of the settings which can be found with the list_dynamicdns() function + * required parameter = stdClass object or associative array containing the configuration to apply to the site, must be a + * (partial) object/array structured in the same manner as is returned by list_dynamicdns() for the site. + */ + public function set_dynamicdns($dynamicdns_id, $payload) + { + $this->request_type = 'PUT'; + + return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/dynamicdns/' . trim($dynamicdns_id), $payload); + } + /** * List network settings (using REST) * ---------------------------------- @@ -2620,7 +2639,7 @@ class Client */ public function spectrum_scan($ap_mac) { - $payload = ['cmd' => 'spectrum-scan', 'mac' => strtolower($ap_mac)]; + $payload = ['cmd' => 'spectrum-scan', 'mac' => strtolower($ap_mac)]; return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr', $payload); } @@ -3151,11 +3170,11 @@ class Client * Fetch results * ------------- * execute the cURL request and return results - * required parameter = request path - * optional parameter = payload to pass with the request - * optional parameter = whether the method should return a boolean result, else return + * required parameter = string, request path + * optional parameter = PHP associative array or stdClass Object, payload to pass with the request + * optional parameter = boolean, whether the method should return a boolean result, else return * the "data" array - * optional parameter = whether the method requires to be logged in or not + * optional parameter = boolean, whether the method requires to be logged in or not */ protected function fetch_results($path, $payload = null, $boolean = false, $login_required = true) { @@ -3199,9 +3218,9 @@ class Client * Fetch results where output should be boolean (true/false) * --------------------------------------------------------- * execute the cURL request and return a boolean value - * required parameter = request path - * optional parameter = payload to pass with the request - * optional parameter = whether the method requires to be logged in or not + * required parameter = string, request path + * optional parameter = PHP associative array or stdClass Object, payload to pass with the request + * optional parameter = boolean, whether the method requires to be logged in or not */ protected function fetch_results_boolean($path, $payload = null, $login_required = true) {