From 8acaa694cadd505c3272bcf1469118ad0f7d52e6 Mon Sep 17 00:00:00 2001 From: malle-pietje Date: Thu, 28 Nov 2024 12:11:08 +0100 Subject: [PATCH] - updated the README file - updated @throws tags in the doc blocks to reflect the correct exception classes where necessary, in other cases "Exception" is mentioned - minor changes - bumped version to 2.0.2 --- README.md | 102 +++++++++++--------- composer.json | 3 +- examples/list_alarms.php | 11 +-- src/Client.php | 201 +++++++++++++++++++-------------------- 4 files changed, 165 insertions(+), 152 deletions(-) diff --git a/README.md b/README.md index 57a17f7..978f68a 100755 --- a/README.md +++ b/README.md @@ -1,5 +1,10 @@ ## UniFi Controller API client class +[![License](https://img.shields.io/github/license/Art-of-WiFi/UniFi-API-client)](https://github.com/Art-of-WiFi/UniFi-API-client/blob/main/LICENSE) +[![Packagist Version](https://img.shields.io/packagist/v/art-of-wifi/unifi-api-client)](https://packagist.org/packages/art-of-wifi/unifi-api-client) +[![Downloads](https://img.shields.io/packagist/dt/art-of-wifi/unifi-api-client)](https://packagist.org/packages/art-of-wifi/unifi-api-client) +[![PHP Version](https://img.shields.io/packagist/php-v/art-of-wifi/unifi-api-client)](https://packagist.org/packages/art-of-wifi/unifi-api-client) + A PHP class that provides access to Ubiquiti's [**UniFi Network Application**](https://unifi-network.ui.com/) API. This class is used by our API Browser tool, which can be found @@ -22,8 +27,7 @@ easy inclusion in your projects. See the [installation instructions](#Installati - a server with: - PHP **7.4.0** or higher (use version [1.1.83](https://github.com/Art-of-WiFi/UniFi-API-client/releases/tag/v1.1.83) for PHP 7.3.x and lower) - - PHP json and PHP cURL modules - - tested on Apache 2.4 with PHP 7.4.27 and cURL 7.60.0 and with PHP 8.3.11 and cURL 7.81.0 + - PHP json and PHP cURL modules enabled - direct network connectivity between this server and the host and port (usually TCP port 8443 or port 443 for UniFi OS) where the UniFi Controller is running - you **must** use an **account with local access permissions** to access the UniFi Controller API through this class @@ -32,8 +36,10 @@ easy inclusion in your projects. See the [installation instructions](#Installati ## UniFi OS Support -Support for UniFi OS-based controllers has been added as of version 1.1.47. These devices/services have been verified -to work: +Besides the "software-based" UniFi controllers, this class also supports UniFi OS-based controllers starting from +version **1.1.47**. + +These devices/services have been verified to work: - UniFi Dream Router (UDR) - UniFi Dream Machine (UDM) - UniFi Dream Machine Pro (UDM PRO) @@ -62,12 +68,12 @@ https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostn The "custom firewall rule" approach described there is the recommended method. -## Upgrading from a previous version +## Upgrading from previous versions When upgrading from a version before **2.0.0**, please: - change your code to use the new Exceptions that are thrown by the class - test the client with your code for any breaking changes -- make sure you are using composer to install the class because the code is no longer held within a single file +- make sure you are using [Composer](#composer) to install the class because the code is no longer held within a single file ## Installation @@ -77,18 +83,17 @@ Use [Composer](#composer) or [Git](#git) to install the API client class. ### Composer -The preferred installation method is through [composer](https://getcomposer.org). -Follow these [installation instructions](https://getcomposer.org/doc/00-intro.md) if you don't have composer +The preferred installation method is through [Composer](https://getcomposer.org). +Follow these [installation instructions](https://getcomposer.org/doc/00-intro.md) if you don't have Composer installed already. -Once composer is installed, simply execute this command from the shell in your project -directory: +Once Composer is installed, execute this command from the shell in your project directory: ```sh composer require art-of-wifi/unifi-api-client ``` -Or manually add the package to your composer.json file: +Or manually add the package to your `composer.json` file: ```javascript { @@ -143,9 +148,32 @@ $login = $unifi_connection->login(); $results = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects ``` -## Example Exception handling +#### IMPORTANT NOTES: + +1. In the above example, `$site_id` is the short site "name" (usually 8 characters long) that is visible in the URL when + managing the site in the UniFi Network Controller. For example, with this URL: + + `https://:8443/manage/site/jl3z2shm/dashboard` + + `jl3z2shm` is the short site "name" and the value to assign to $site_id. + +2. The 6th optional parameter that is passed to the constructor in the above example (`true`), enables validation of + the controller's SSL certificate, which is otherwise **disabled** by default. It is **highly recommended** to enable + this feature in production environments where you have a valid SSL cert installed on the UniFi Controller that is + associated with the FQDN in the `controller_url` parameter. This option was added with API client version 1.1.16. + +3. Using an administrator account (`$controller_user` in the above example) with **read-only** permissions can limit + visibility on certain collection/object properties. See this + [issue](https://github.com/Art-of-WiFi/UniFi-API-client/issues/129) and this + [issue](https://github.com/Art-of-WiFi/UniFi-API-browser/issues/94) for an example where the WPA2 password isn't + visible for **read-only** administrator accounts. + + +## Exception handling + +The class now throws **Exceptions** for various error conditions instead of using PHP's `trigger_error()` function. This +allows for more granular error handling in your application code. -The class now throws Exceptions for various error conditions instead of using PHP's `trigger_error()` function. Here is an example of how to catch these Exceptions: ```php getMessage(). PHP_EOL; } catch (Exception $e) { + /** catch any other Exceptions that might be thrown */ echo 'General Exception: ' . $e->getMessage(). PHP_EOL; } ``` -Please refer to the `examples/` directory for some more detailed examples that can be used as a starting point for your -own PHP code. +Although the PHP DocBlocks for most public methods/functions contain `@throws Exception`, it is recommended to catch +other specific Exceptions that can be thrown by the API Client class to provide more detailed error messages to your +application code. -The `list_alarms.php` example there is a good starting point to see how to use the new Exception handling. +In most cases, the class will let Exceptions bubble up to the calling code, but in some cases it will catch them and +throw a new Exception with a more specific message. - -#### IMPORTANT NOTES: - -1. In the above example, `$site_id` is the short site "name" (usually 8 characters long) that is visible in the URL when - managing the site in the UniFi Network Controller. For example, with this URL: - - `https://:8443/manage/site/jl3z2shm/dashboard` - - `jl3z2shm` is the short site "name" and the value to assign to $site_id. - -2. The 6th optional parameter that is passed to the constructor in the above example (`true`), enables validation of - the controller's SSL certificate, which is otherwise **disabled** by default. It is **highly recommended** to enable - this feature in production environments where you have a valid SSL cert installed on the UniFi Controller that is - associated with the FQDN in the `controller_url` parameter. This option was added with API client version 1.1.16. - -3. Using an administrator account (`$controller_user` in the above example) with **read-only** permissions can limit - visibility on certain collection/object properties. See this - [issue](https://github.com/Art-of-WiFi/UniFi-API-client/issues/129) and this - [issue](https://github.com/Art-of-WiFi/UniFi-API-browser/issues/94) for an example where the WPA2 password isn't - visible for **read-only** administrator accounts. +The `list_alarms.php` example in the `examples/` directory is a good starting point to see how you can implement +Exception handling. ## Functions/methods supported The class currently supports a large and growing number of functions/methods to access the UniFi Controller API. -Please refer to the comments in the source code for more details on each of the functions/methods, +Please refer to the comments/PHP DocBlocks in the source code for more details on each of the functions/methods, their purpose, and their respective parameters. If you are using an advanced IDE such as PHPStorm or VS Code, you can use its code completion and other @@ -270,12 +283,6 @@ When encountering issues with the UniFi API using other libraries, cURL or Postm Please use the [Discussions](https://github.com/Art-of-WiFi/UniFi-API-client/discussions) section instead. -## Contribute - -If you would like to contribute code (improvements), please open an issue and include -your code there or else create a pull request. - - ## Credits This class is based on the initial work by the following developers: @@ -287,6 +294,15 @@ and the API as published by Ubiquiti: - https://dl.ui.com/unifi/8.6.9/unifi_sh_api +## Contributors + +A big thanks to all the contributors who have helped with this project! + +[![Contributors](https://img.shields.io/github/contributors/Art-of-WiFi/UniFi-API-client)](https://github.com/Art-of-WiFi/UniFi-API-client/graphs/contributors) + +If you would like to contribute to this project, please open an issue and include +your suggestions or code there or else create a pull request. + ## Important Disclaimer diff --git a/composer.json b/composer.json index 4043a24..fed23ff 100755 --- a/composer.json +++ b/composer.json @@ -8,7 +8,8 @@ "unifi", "controller", "api", - "client" + "client", + "unifi os" ], "homepage": "https://github.com/Art-of-WiFi/UniFi-API-client", "license": "MIT", diff --git a/examples/list_alarms.php b/examples/list_alarms.php index 5d8db3d..3c01881 100755 --- a/examples/list_alarms.php +++ b/examples/list_alarms.php @@ -6,7 +6,6 @@ * description: An example basic PHP script to pull current alarms from the UniFi controller and output in JSON format, * also demonstrates how to catch exceptions. */ - use UniFi_API\Exceptions\CurlExtensionNotLoadedException; use UniFi_API\Exceptions\CurlGeneralErrorException; use UniFi_API\Exceptions\CurlTimeoutException; @@ -38,10 +37,10 @@ require_once 'config.php'; */ $site_id = ''; +/** + * initialize the UniFi API connection class and log in to the controller and do our thing + */ try { - /** - * initialize the UniFi API connection class and log in to the controller and do our thing - */ $unifi_connection = new UniFi_API\Client( $controlleruser, $controllerpassword, @@ -55,7 +54,7 @@ try { $data = $unifi_connection->list_alarms(); /** - * provide feedback in json format + * echo the results in JSON format */ echo json_encode($data, JSON_PRETTY_PRINT); } catch (CurlExtensionNotLoadedException $e) { @@ -66,7 +65,6 @@ try { echo 'InvalidSiteNameException: ' . $e->getMessage(). PHP_EOL; } catch (JsonDecodeException $e) { echo 'JsonDecodeException: ' . $e->getMessage(). PHP_EOL; - echo $unifi_connection->get_last_results_raw(); } catch (LoginRequiredException $e) { echo 'LoginRequiredException: ' . $e->getMessage(). PHP_EOL; } catch (CurlGeneralErrorException $e) { @@ -76,5 +74,6 @@ try { } catch (LoginFailedException $e) { echo 'LoginFailedException: ' . $e->getMessage(). PHP_EOL; } catch (Exception $e) { + /** catch any other Exceptions that might be thrown */ echo 'General Exception: ' . $e->getMessage(). PHP_EOL; } \ No newline at end of file diff --git a/src/Client.php b/src/Client.php index 032042e..d07eff5 100755 --- a/src/Client.php +++ b/src/Client.php @@ -33,7 +33,7 @@ use UniFi_API\Exceptions\MethodDeprecatedException; class Client { /** Constants. */ - const CLASS_VERSION = '2.0.0'; + const CLASS_VERSION = '2.0.2'; const CURL_METHODS_ALLOWED = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']; const DEFAULT_CURL_METHOD = 'GET'; @@ -131,7 +131,7 @@ class Client * * @see https://www.php.net/manual/en/language.oop5.decon.php * @note to force the class instance to log out when you're done, call logout() - * @throws CurlGeneralErrorException|CurlTimeoutException + * @throws CurlGeneralErrorException|CurlTimeoutException|CurlTimeoutException */ public function __destruct() { @@ -151,7 +151,7 @@ class Client * * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses * @return bool returns true upon a successful login - * @throws CurlGeneralErrorException|CurlTimeoutException|LoginFailedException|CurlTimeoutException + * @throws LoginFailedException|CurlTimeoutException|CurlGeneralErrorException */ public function login(): bool { @@ -229,7 +229,7 @@ class Client } /** If the HTTP response code is 200, we are logged in. */ - if ($http_code >= 200) { + if ($http_code === 200) { curl_close($ch); return $this->is_logged_in = true; } @@ -417,7 +417,7 @@ class Client * @param bool|null $is_wired optional, defines whether the new user/client-device is wired or not * @return array|bool returns an array with a single object containing details of the new user/client-device on * success, else returns false - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function create_user( string $mac, @@ -497,7 +497,7 @@ class Client * Example values: * 'airtime_avg', 'latency_avg', 'latency_min', 'latency_max' * @return array|bool returns an array of 5-minute stats objects for the current site - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_5minutes_site(int $start = null, int $end = null, array $attribs = null) { @@ -521,7 +521,7 @@ class Client * @param int|null $end optional, Unix timestamp in milliseconds * @param array|null $attribs optional, array of attributes to collect. * @return array|bool returns an array of hourly stats objects for the current site - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception * @see stat_5minutes_site() for details on attribs */ public function stat_hourly_site(int $start = null, int $end = null, array $attribs = null) @@ -543,7 +543,7 @@ class Client * @param int|null $end optional, Unix timestamp in milliseconds * @param array|null $attribs optional, array of attributes to collect. * @return array|bool returns an array of daily stats objects for the current site - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception * @see stat_5minutes_site() for details on attribs */ public function stat_daily_site(int $start = null, int $end = null, array $attribs = null) @@ -565,7 +565,7 @@ class Client * @param int|null $end optional, Unix timestamp in milliseconds * @param array|null $attribs optional, array of attributes to collect. * @return array|bool returns an array of monthly stats objects for the current site - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception * @see stat_5minutes_site() for details on attribs */ public function stat_monthly_site(int $start = null, int $end = null, array $attribs = null) @@ -614,7 +614,7 @@ class Client * 'na-rx_bytes', * 'ng-rx_bytes', * @return array|bool returns an array of 5-minute stats objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_5minutes_aps(int $start = null, int $end = null, string $mac = null, array $attribs = null) { @@ -642,7 +642,7 @@ class Client * stats for all APs are returned * @param array|null $attribs optional, array of attributes to collect, default: (bytes, num_sta, time). * @return array|bool returns an array of hourly stats objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception * @see stat_5minutes_aps() for supported attribs */ public function stat_hourly_aps(int $start = null, int $end = null, string $mac = null, array $attribs = null) @@ -671,7 +671,7 @@ class Client * stats for all APs are returned * @param array|null $attribs optional, array of attributes to collect, default: (bytes, num_sta, time). * @return array|bool returns an array of daily stats objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception * @see stat_5minutes_aps() for supported attribs */ public function stat_daily_aps(int $start = null, int $end = null, string $mac = null, array $attribs = null) @@ -700,7 +700,7 @@ class Client * stats for all APs are returned * @param array|null $attribs optional, array of attributes to collect, default: (bytes, num_sta, time). * @return array|bool returns an array of monthly stats objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception * @see stat_5minutes_aps() for supported attribs */ public function stat_monthly_aps(int $start = null, int $end = null, string $mac = null, array $attribs = null) @@ -734,7 +734,7 @@ class Client * tx_packets, satisfaction, wifi_tx_attempts, 'duration' * default value is ['rx_bytes', 'tx_bytes', 'time'] * @return array|bool returns an array of 5-minute stats objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_5minutes_user(string $mac = null, int $start = null, int $end = null, array $attribs = null) { @@ -760,7 +760,7 @@ class Client * @param int|null $end optional, Unix timestamp in milliseconds * @param array|null $attribs array containing attributes (strings) to be returned * @return array|bool returns an array of hourly stats objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception * @see stat_5minutes_user() for details on attribs */ public function stat_hourly_user(string $mac = null, int $start = null, int $end = null, array $attribs = null) @@ -791,7 +791,7 @@ class Client * @param int|null $end optional, Unix timestamp in milliseconds * @param array|null $attribs array containing attributes (strings) to be returned * @return array|bool returns an array of daily stats objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception * @see stat_5minutes_user() for details on attribs */ public function stat_daily_user(string $mac = null, int $start = null, int $end = null, array $attribs = null) @@ -822,7 +822,7 @@ class Client * @param int|null $end optional, Unix timestamp in milliseconds * @param array|null $attribs array containing attributes (strings) to be returned * @return array|bool returns an array of monthly stats objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception * @see stat_5minutes_user() for details on attribs */ public function stat_monthly_user(string $mac = null, int $start = null, int $end = null, array $attribs = null) @@ -854,7 +854,7 @@ class Client * lan-tx_bytes, lan-rx_packets, lan-tx_packets, lan-rx_dropped, lan-tx_dropped * default is ['time', 'mem', 'cpu', 'loadavg_5'] * @return array|bool returns an array of 5-minute stats objects for the gateway belonging to the current site - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_5minutes_gateway(int $start = null, int $end = null, array $attribs = null) { @@ -875,7 +875,7 @@ class Client * @param int|null $end optional, Unix timestamp in milliseconds * @param array|null $attribs array containing attributes (strings) to be returned * @return array|bool returns an array of hourly stats objects for the gateway belonging to the current site - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception * @see stat_5minutes_gateway() for details on attribs */ public function stat_hourly_gateway(int $start = null, int $end = null, array $attribs = null) @@ -897,7 +897,7 @@ class Client * @param int|null $end optional, Unix timestamp in milliseconds * @param array|null $attribs array containing attributes (strings) to be returned * @return array|bool returns an array of hourly stats objects for the gateway belonging to the current site - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception * @see stat_5minutes_gateway() for details on attribs */ public function stat_daily_gateway(int $start = null, int $end = null, array $attribs = null) @@ -919,7 +919,7 @@ class Client * @param int|null $end optional, Unix timestamp in milliseconds * @param array|null $attribs array containing attributes (strings) to be returned * @return array|bool returns an array of monthly stats objects for the gateway belonging to the current site - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception * @see stat_5minutes_gateway() for details on attribs */ public function stat_monthly_gateway(int $start = null, int $end = null, array $attribs = null) @@ -940,7 +940,7 @@ class Client * @param int|null $start optional, Unix timestamp in milliseconds * @param int|null $end optional, Unix timestamp in milliseconds * @return array|bool returns an array of speed test result objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_speedtest_results(int $start = null, int $end = null) { @@ -961,7 +961,7 @@ class Client * @param int|null $end optional, Unix timestamp in milliseconds * @param int|null $limit optional, maximum number of events to return, defaults to 10000 * @return array|bool returns an array of IPS/IDS event objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_ips_events(int $start = null, int $end = null, int $limit = null) { @@ -985,7 +985,7 @@ class Client * @param string $type optional, client type to return sessions for, can be 'all', 'guest' or 'user'; default * value is 'all' * @return array|bool returns an array of login session objects for all devices or a single device - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_sessions(int $start = null, int $end = null, string $mac = null, string $type = 'all') { @@ -1012,7 +1012,7 @@ class Client * @param string $mac client MAC address * @param int|null $limit optional, maximum number of sessions to get (default value is 5) * @return array|bool returns an array of login session objects for all devices or a single device - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_sta_sessions_latest(string $mac, int $limit = null) { @@ -1030,7 +1030,7 @@ class Client * @param int|null $start optional, Unix timestamp in milliseconds * @param int|null $end optional, Unix timestamp in milliseconds * @return array|bool returns an array of authorization objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_auths(int $start = null, int $end = null) { @@ -1048,7 +1048,7 @@ class Client * the returned stats per client are all-time totals, irrespective of the value of $historyhours * @param int $historyhours optional, hours to go back (default is 8760 hours or 1 year) * @return array|bool returns an array of client device objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_allusers(int $historyhours = 8760) { @@ -1064,7 +1064,7 @@ class Client * @param int $within optional, time frame in hours to go back to list guests with valid access (default = 24*365 * hours) * @return array|bool returns an array of guest device objects with valid access - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_guests(int $within = 8760) { @@ -1080,7 +1080,7 @@ class Client * made * @return array|bool returns an array of online client device objects, or in case of a single device request, returns a * single client device object, false upon error - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_clients(string $mac = null) { @@ -1096,7 +1096,7 @@ class Client * * @param string $mac client device MAC address * @return array|bool returns an object with the client device information - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_client(string $mac) { @@ -1110,7 +1110,7 @@ class Client * fingerprint_source in the client device objects, the default value is 0 * @return array|bool an array of fingerprints, contain dev_ids, dev_type_ids, family_ids, os_name_ids, os_class_ids * and vendor_ids, false upon error - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_fingerprint_devices(int $fingerprint_source = 0) { @@ -1140,7 +1140,7 @@ class Client * @param string|null $network_id optional, _id value for the network where the ip belongs to * @param string|null $fixed_ip optional, IP address, value of client device's fixed_ip field * @return array|bool returns an array containing a single object with attributes of the updated client on success - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function edit_client_fixedip(string $client_id, bool $use_fixedip, string $network_id = null, string $fixed_ip = null) { @@ -1170,7 +1170,7 @@ class Client * @param string $client_id _id value for the client device * @param string $name name of the client * @return array|bool returns an array containing a single object with attributes of the updated client on success - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function edit_client_name(string $client_id, string $name) { @@ -1192,7 +1192,7 @@ class Client * Fetch user groups * * @return array|bool returns an array of user group objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_usergroups() { @@ -1207,7 +1207,7 @@ class Client * @param int $group_up limit upload bandwidth in Kbps (default = -1, which sets bandwidth to unlimited) * @return array|bool containing a single object with attributes of the new usergroup ("_id", "name", * "qos_rate_max_down", "qos_rate_max_up", "site_id") on success - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function create_usergroup(string $group_name, int $group_dn = -1, int $group_up = -1) { @@ -1229,7 +1229,7 @@ class Client * @param int $group_dn limit download bandwidth in Kbps (default = -1, which sets bandwidth to unlimited) * @param int $group_up limit upload bandwidth in Kbps (default = -1, which sets bandwidth to unlimited) * @return array|bool returns an array containing a single object with attributes of the updated usergroup on success - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function edit_usergroup(string $group_id, string $site_id, string $group_name, int $group_dn = -1, int $group_up = -1) { @@ -1264,7 +1264,7 @@ class Client * Fetch AP groups * * @return array|bool containing the current AP groups on success - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_apgroups() { @@ -1278,7 +1278,7 @@ class Client * @param array $device_macs optional, array containing the MAC addresses (strings) of the APs to add to the new * group * @return array|bool containing a single object with attributes of the new AP group on success - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function create_apgroup(string $group_name, array $device_macs = []) { @@ -1295,7 +1295,7 @@ class Client * @param array $device_macs array containing the members of the AP group which overwrites the existing * group_members (passing an empty array clears the AP member list) * @return array|bool containing a single object with attributes of the updated AP group on success - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function edit_apgroup(string $group_id, string $group_name, array $device_macs) { @@ -1330,7 +1330,7 @@ class Client * * @param string $group_id optional, _id value of the single firewall group to list * @return array|bool containing the current firewall groups or the selected firewall group on success - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_firewallgroups(string $group_id = '') { @@ -1346,7 +1346,7 @@ class Client * port numbers) * (default is an empty array) * @return array|bool containing a single object with attributes of the new firewall group on success - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function create_firewallgroup(string $group_name, string $group_type, array $group_members = []) { @@ -1371,7 +1371,7 @@ class Client * @param array $group_members array containing the members of the group (IPv4 addresses, IPv6 addresses or port * numbers) which overwrites the existing group_members (default is an empty array) * @return array|bool containing a single object with attributes of the updated firewall group on success - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function edit_firewallgroup(string $group_id, string $site_id, string $group_name, string $group_type, array $group_members = []) { @@ -1410,7 +1410,7 @@ class Client * Fetch firewall rules (using REST). * * @return array|bool containing the current firewall rules on success - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_firewallrules() { @@ -1422,7 +1422,7 @@ class Client * * @param string $route_id _id value of the static route to get settings for * @return array|bool containing the static routes and their settings - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_routing(string $route_id = '') { @@ -1433,7 +1433,7 @@ class Client * Fetch health metrics. * * @return array|bool containing health metric objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_health() { @@ -1446,7 +1446,7 @@ class Client * @param boolean $five_minutes when true, return stats based on 5 minute intervals, * returns hourly stats by default (supported on controller versions 5.5.* and higher) * @return array|bool containing dashboard metric objects (available since controller version 4.9.1.alpha) - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_dashboard(bool $five_minutes = false) { @@ -1459,7 +1459,7 @@ class Client * Fetch client devices. * * @return array|bool containing known client device objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_users() { @@ -1470,7 +1470,7 @@ class Client * List of UniFi devices with a basic subset of properties (e.g., mac, state, adopted, disabled, type, model, name). * * @return array|bool an array containing known UniFi device objects, false upon error - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_devices_basic() { @@ -1484,7 +1484,7 @@ class Client * to filter by. May also be a (lowercase) string containing a single MAC address * @return array|bool an array containing known UniFi device objects, optionally filtered by the * parameter, false upon error - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_devices($macs = []) { @@ -1498,7 +1498,7 @@ class Client * * @note this endpoint was introduced with controller versions 5.5.X * @return array|bool containing known device tag objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_tags() { @@ -1549,7 +1549,7 @@ class Client * @note this endpoint was introduced with controller versions 5.5.X * @param string $tag_id required, the _id value of the tag to retrieve * @return array|bool containing matching tag objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function get_tag(string $tag_id) { @@ -1578,7 +1578,7 @@ class Client * * @param int $within optional, hours to go back to list discovered "rogue" access points (default = 24 hours) * @return array|bool containing rogue/neighboring access point objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_rogueaps(int $within = 24) { @@ -1591,7 +1591,7 @@ class Client * Fetch known rogue access points. * * @return array|bool containing known rogue access point objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_known_rogueaps() { @@ -1604,7 +1604,7 @@ class Client * @note this is an experimental function, please do not use unless you know exactly what you're doing * @param int $days number of days for which the backup must be generated * @return array|bool URL from where the backup file can be downloaded once generated, false upon failure - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function generate_backup(int $days = -1) { @@ -1619,7 +1619,7 @@ class Client * @note this is an experimental function, please do not use unless you know exactly what you're doing * @param string $filepath the path to the generated backup file * @return string|bool the raw content of the backup file, false upon failure - * @throws InvalidCurlMethodException|CurlGeneralErrorException|LoginFailedException + * @throws Exception|CurlGeneralErrorException|CurlTimeoutException */ public function download_backup(string $filepath) { @@ -1630,7 +1630,7 @@ class Client * Fetch auto backups. * * @return array|bool containing objects with backup details on success - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_backups() { @@ -1644,7 +1644,7 @@ class Client * * @note this is an experimental function, please do not use unless you know exactly what you're doing * @return array|bool URL from where the backup/export file can be downloaded once generated, false upon failure - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function generate_backup_site() { @@ -1658,7 +1658,7 @@ class Client * * @return array|bool a list of sites on this controller that the credentials used have access to, * together with some basic attributes for each site - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_sites() { @@ -1670,7 +1670,7 @@ class Client * * @note this endpoint was introduced with controller version 5.2.9 * @return array|bool statistics for all sites hosted on this controller - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_sites() { @@ -1683,7 +1683,7 @@ class Client * @param string $description the long name for the new site * @return array|bool false on failure or a single object with attributes of the new site ("_id", "desc", "name") on * success - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function create_site(string $description) { @@ -1852,7 +1852,7 @@ class Client * Fetch admins. * * @return array|bool containing administrator objects for selected site - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_admins() { @@ -1865,7 +1865,7 @@ class Client * Fetch all admins. * * @return array|bool containing administrator objects for all sites - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_all_admins() { @@ -1891,8 +1891,7 @@ class Client * restart devices, default value is false. With versions < 5.9.X this only applies * when readonly is true. * @return bool true on success - * @throws EmailInvalidException - * @throws Exception + * @throws EmailInvalidException|Exception */ public function invite_admin( string $name, @@ -1997,8 +1996,7 @@ class Client * restart devices, default value is false. With versions < 5.9.X this only applies * when readonly is true. * @return bool true on success - * @throws EmailInvalidException - * @throws Exception + * @throws EmailInvalidException|Exception */ public function update_admin( string $admin_id, @@ -2077,7 +2075,7 @@ class Client * Fetch WLAN groups. * * @return array|bool containing known wlan_groups - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_wlan_groups() { @@ -2088,7 +2086,7 @@ class Client * Fetch sysinfo. * * @return array containing known sysinfo data - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_sysinfo() { @@ -2139,7 +2137,7 @@ class Client * Fetch self. * * @return array|bool containing information about the logged-in user - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_self() { @@ -2151,7 +2149,7 @@ class Client * * @param int|null $create_time optional, create time of the vouchers to fetch in Unix timestamp in seconds * @return array|bool containing hotspot voucher objects - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_voucher(int $create_time = null) { @@ -2165,7 +2163,7 @@ class Client * * @param int|null $within optional, number of hours to go back to fetch payments * @return array|bool containing hotspot payments - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function stat_payment(int $within = null) { @@ -2197,7 +2195,7 @@ class Client * Fetch hotspot operators (using REST). * * @return array|bool containing hotspot operators - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_hotspotop() { @@ -2218,7 +2216,7 @@ class Client * @param int|null $megabytes data transfer limit in MB * @return array|bool containing a single object/array which contains the create_time(stamp) of the voucher(s) * created, false upon failure - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function create_voucher( int $minutes, @@ -2287,7 +2285,7 @@ class Client * Fetch port forwarding stats. * * @return array|bool containing port forwarding stats - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_portforward_stats() { @@ -2298,7 +2296,7 @@ class Client * Fetch DPI stats. * * @return array|bool containing DPI stats - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_dpi_stats() { @@ -2313,7 +2311,7 @@ class Client * @param array|null $cat_filter optional, array containing numeric category ids to filter by, * only to be combined with a "by_app" value for $type * @return array|bool containing filtered DPI stats - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_dpi_stats_filtered(string $type = 'by_cat', array $cat_filter = null) { @@ -2334,7 +2332,7 @@ class Client * Fetch current channels. * * @return array|bool containing currently allowed channels - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_current_channels() { @@ -2348,7 +2346,7 @@ class Client * https://en.wikipedia.org/wiki/ISO_3166-1_numeric * * @return array|bool containing available country codes - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_country_codes() { @@ -2359,7 +2357,7 @@ class Client * Fetch port forwarding settings. * * @return array|bool containing port forwarding settings - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_portforwarding() { @@ -2370,7 +2368,7 @@ class Client * Fetch port configurations. * * @return array|bool containing port configurations - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_portconf() { @@ -2381,7 +2379,7 @@ class Client * Fetch VoIP extensions. * * @return array|bool containing VoIP extensions - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_extension() { @@ -2392,7 +2390,7 @@ class Client * Fetch site settings. * * @return array|bool containing site configuration settings - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_settings() { @@ -2853,7 +2851,7 @@ class Client * Fetch dynamic DNS settings (using REST). * * @return array|bool containing dynamic DNS settings - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_dynamicdns() { @@ -2899,7 +2897,7 @@ class Client * * @param string $network_id optional, _id value of the network to get settings for * @return array|bool containing (non-wireless) networks and their settings - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_networkconf(string $network_id = '') { @@ -2914,7 +2912,7 @@ class Client * list_networkconf() for the specific network type. Do not include the _id property, * it is assigned by the controller and returned upon success. * @return array|bool containing a single object with details of the new network on success, else returns false - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function create_network($payload) { @@ -2959,7 +2957,7 @@ class Client * @param string $wlan_id optional, _id value of the wlan to fetch the settings for * @return array|bool containing wireless networks and their settings, or an array containing a single wireless network * when using the parameter - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_wlanconf(string $wlan_id = '') { @@ -3148,7 +3146,7 @@ class Client * value is 0 * @param integer $limit optional, number of events to return, default value is 3000 * @return array|bool containing known events - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_events(int $historyhours = 720, int $start = 0, int $limit = 3000) { @@ -3170,7 +3168,7 @@ class Client * Example: ["archived" => false, "key" => "EVT_GW_WANTransition"] * return only unarchived for a specific key * @return array|bool containing known alarms - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_alarms(array $payload = []) { @@ -3183,7 +3181,7 @@ class Client * @param bool|null $archived optional, if true all alarms are counted, if false only non-archived (active) alarms are * counted, by default all alarms are counted * @return array|bool containing the alarm count - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function count_alarms(bool $archived = null) { @@ -3217,7 +3215,7 @@ class Client * @note triggers an update of the controller's cached, latest known version. * @return array|bool returns an array with a single object containing details of the current known latest * controller version info on success, else returns false - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function check_controller_update() { @@ -3321,7 +3319,7 @@ class Client * @param string $type optional, "available" or "cached", determines which firmware types to return, * default value is "available" * @return array|bool containing firmware versions - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_firmware(string $type = 'available') { @@ -3370,7 +3368,7 @@ class Client * @param string $mac MAC address of the AP * @return array|bool containing relevant information (results if available) regarding the RF scanning state of the * AP - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function spectrum_scan_state(string $mac) { @@ -3399,7 +3397,7 @@ class Client * * @note this function/method is only supported on controller versions 5.5.19 and later * @return array|bool objects containing all Radius profiles for the current site - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_radius_profiles() { @@ -3411,7 +3409,7 @@ class Client * * @note this function/method is only supported on controller versions 5.5.19 and later * @return array|bool objects containing all Radius accounts for the current site - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function list_radius_accounts() { @@ -3456,7 +3454,7 @@ class Client * 15 E.164 with NSAP format subaddress * @param string|null $vlan optional, VLAN to assign to the account * @return bool|array containing a single object for the newly created account upon success, else returns false - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function create_radius_account( string $name, @@ -3581,7 +3579,7 @@ class Client * The 'data' key in the returned array contains the actual system log entries. * The returned array also contains the page number and size, and the total number of entries * available. - * @throws JsonDecodeException|LoginRequiredException + * @throws Exception */ public function get_system_log(string $class = 'device-alert', int $start = null, int $end = null, int $page_number = 0, int $page_size = 100, array $custom_payload = []) { @@ -3656,7 +3654,7 @@ class Client * @param string $return optional, string; determines how to return results, when "boolean" the method must * return a boolean result or "array" when the method must return an array (default) * @return bool|array returns results as requested, returns false on incorrect parameters - * @throws JsonDecodeException|LoginRequiredException|Exception + * @throws Exception */ public function custom_api_request(string $path, string $method = 'GET', $payload = null, string $return = 'array') { @@ -4079,7 +4077,7 @@ class Client * the "data" array * @param boolean $login_required optional, whether the method requires to be logged in or not * @return bool|array returns an array with the "data" array on success, else returns boolean if $boolean is true - * @throws JsonDecodeException|LoginRequiredException|Exception|LoginRequiredException + * @throws Exception */ protected function fetch_results( string $path, @@ -4150,7 +4148,7 @@ class Client * request * @param bool $login_required optional, whether the method requires to be logged in or not * @return bool [description] - * @throws Exception|JsonDecodeException|LoginRequiredException + * @throws Exception */ protected function fetch_results_boolean(string $path, $payload = null, bool $login_required = true): bool { @@ -4161,7 +4159,7 @@ class Client * Capture the latest JSON error and throw an Exception. * * @return bool true, if no error occurred - * @throws JsonDecodeException|LoginRequiredException when a JSON error occurred + * @throws JsonDecodeException when a JSON error occurred */ protected function get_json_last_error(): bool { @@ -4342,7 +4340,7 @@ class Client * @param string $path path for the request * @param object|array|null $payload optional, payload to pass with the request * @return bool|string response returned by the controller API - * @throws InvalidCurlMethodException|CurlGeneralErrorException|LoginFailedException|CurlTimeoutException + * @throws CurlGeneralErrorException|CurlTimeoutException|InvalidCurlMethodException|LoginFailedException */ protected function exec_curl(string $path, $payload = null) { @@ -4368,7 +4366,6 @@ class Client $json_payload = json_encode($payload, JSON_UNESCAPED_SLASHES); $curl_options[CURLOPT_POSTFIELDS] = $json_payload; - /** * Should not use GET (the default request type) or DELETE when passing a payload, * switch to POST instead.