added curl option to specifically support http (originally suggested by @Kyouma54 in PR #251)

bumped version to 2.0.4

LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016, Art of WiFi
+Copyright (c) 2024, Art of WiFi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,77 +1,114 @@
 ## UniFi Controller API client class
 
-A PHP class that provides access to Ubiquiti's [**UniFi Network Controller**](https://unifi-network.ui.com/) API.
+[![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)
 
-UniFi Network Controller software versions 4.X.X, 5.X.X, 6.X.X, and 7.X.X (version 7.2.93 has been confirmed to work)
+A PHP class that provides access to Ubiquiti's [**UniFi Network Application**](https://unifi-network.ui.com/) API.
-are supported as well as UniFi OS-based controllers. This class is used by our API browser tool which can be found
+
+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 by using
 composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for
-easy inclusion in your projects.
+easy inclusion in your projects. See the [installation instructions](#Installation) below for more details.
+
+## Supported Versions
+
+| Software                             | Versions                                             |
+|--------------------------------------|------------------------------------------------------|
+| UniFi Network Application/controller | 5.x, 6.x, 7.x, 8.x, 9.0.x (**9.0.101 is confirmed**) |
+| UniFi OS                             | 3.x, 4.1.x (**4.1.9 is confirmed**)                  |
+
 
 ## Requirements
 
 - a server with:
-  - PHP 5.5.0 or higher 
+  - 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) 
-  - PHP json and PHP cURL modules
+    for PHP 7.3.x and lower)
-  - tested on Apache 2.4 with PHP 5.6.1 and cURL 7.42.1 and with PHP 7.4.9 and cURL 7.68.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 **accounts with local access**, not UniFi Cloud accounts, to access the UniFi Controller API 
+- you **must** use an **account with local access permissions** to access the UniFi Controller API through this class
-  through this class
+- do not use UniFi Cloud accounts and do not enable 2FA for the accounts that you use with this class
+
 
 ## UniFi OS Support
 
-Support for UniFi OS-based controllers has been added as of version 1.1.47:
+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)
 - UniFi Cloud Key Gen2 (UCK G2), firmware version 2.0.24 or higher
 - UniFi Cloud Key Gen2 Plus (UCK G2 Plus), firmware version 2.0.24 or higher
-- UniFi Cloud Console, details [here](https://help.ui.com/hc/en-us/articles/4415364143511)
+- UniFi Express (UX)
+- UniFi Dream Wall (UDW)
+- UniFi Cloud Gateway Ultra (UCG-Ultra)
+- UniFi CloudKey Enterprise (CK-Enterprise)
+- UniFi Enterprise Fortress Gateway (EFG)
+- Official UniFi Hosting, details [here](https://help.ui.com/hc/en-us/articles/4415364143511)
 
-The class automatically detects UniFi OS-based controllers and adjusts URLs and several functions/methods accordingly.
+The class automatically detects UniFi OS consoles and adjusts the URLs and several functions/methods accordingly.
-If your own code implements strict validation of the URL that is passed to the constructor, please adapt your
-logic to allow URLs without a port suffix or with port 443 when working with a UniFi OS-based controller.
 
-> **IMPORTANT NOTE**: cookies are no longer supported with UniFi OS-based controllers. If your application code does use cookies,
+UniFi OS-based controllers require you to connect using port **443** instead of **8443** which is used for
-  they will be ignored automatically when working with UniFi OS-based controllers.
+"software-based" controllers. If your own code implements strict validation of the URL that is passed to the
+constructor, please adapt your logic to allow URLs without a port suffix or with port 443 when working with a
+UniFi OS-based controller.
+
+
+### Remote API access to UniFi OS-based controllers
+When connecting to a UniFi OS-based gateway through the WAN interface, you need to create a specific firewall rule to
+allow this. See this blog post on the Art of WiFi website for more details:
+https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a-udm-pro
+
+The "custom firewall rule" approach described there is the recommended method.
+
+
+## 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](#composer) to install the class because the code is no longer held within a single file
 
-Please test all methods you plan on using thoroughly before using the API Client with
-UniFi OS devices in a production environment.
 
 ## Installation
 
-Use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the 
+Use [Composer](#composer) or [Git](#git) to install the API client class.
-API client class.
+
 
 ### Composer
 
-The preferred installation method is through [composer](https://getcomposer.org). 
+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
+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
+Once Composer is installed, execute this command from the shell in your project directory:
-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
 {
     "require": {
-        "art-of-wifi/unifi-api-client": "^1.1"
+        "art-of-wifi/unifi-api-client": "^2.0"
     }
 }
 ```
 
-Finally, be sure to include the autoloader in your code:
+Finally, be sure to include the composer autoloader in your code if your framework doesn't already do this for you:
 
 ```php
+/**
+ * load the class using the composer autoloader
+ */
 require_once 'vendor/autoload.php';
 ```
 
@@ -86,22 +123,15 @@ git clone https://github.com/Art-of-WiFi/UniFi-API-client.git
 When git is done cloning, include the file containing the class like so in your code:
 
 ```php
-require_once 'path/to/src/Client.php';
+/**
-```
+ * load the class directly instead of using the composer autoloader
-
+ */
-### Download the Release
-
-If you prefer not to use composer or git,
-simply [download the package](https://github.com/Art-of-WiFi/UniFi-API-client/archive/master.zip), unpack the zip
-file, then include the file containing the class in your code like so:
-
-```php
 require_once 'path/to/src/Client.php';
 ```
 
 ## Example usage
 
-A basic example how to use the class:
+A basic example of how to use the class:
 
 ```php
 /**
@@ -118,20 +148,17 @@ $login            = $unifi_connection->login();
 $results          = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects
 ```
 
-Please refer to the `examples/` directory for some more detailed examples which can be used as a starting point for your
-own PHP code.
-
 #### 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:
+   managing the site in the UniFi Network Controller. For example, with this URL:
 
    `https://<controller IP address or FQDN>: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
+   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.
 
@@ -141,213 +168,120 @@ own PHP code.
    [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.
+
+Here is an example of how to catch these Exceptions:
+```php
+<?php
+/**
+ * PHP API usage example with Exception handling
+ */
+use UniFi_API\Exceptions\CurlExtensionNotLoadedException;
+use UniFi_API\Exceptions\CurlGeneralErrorException;
+use UniFi_API\Exceptions\CurlTimeoutException;
+use UniFi_API\Exceptions\InvalidBaseUrlException;
+use UniFi_API\Exceptions\InvalidSiteNameException;
+use UniFi_API\Exceptions\JsonDecodeException;
+use UniFi_API\Exceptions\LoginFailedException;
+use UniFi_API\Exceptions\LoginRequiredException;
+
+/**
+ * load the class using the composer autoloader
+ */
+require_once 'vendor/autoload.php';
+
+/**
+ * include the config file (place your credentials etc. there if not already present)
+ */
+require_once 'config.php';
+
+/**
+ * initialize the UniFi API connection class, log in to the controller and request the alarms collection
+ * (this example assumes you have already assigned the correct values to the variables in config.php)
+ */
+try {
+    $unifi_connection = new UniFi_API\Client($controller_user, $controller_password, $controller_url, $site_id, $controller_version, true);
+    $login            = $unifi_connection->login();
+    $results          = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects
+} catch (CurlExtensionNotLoadedException $e) {
+    echo 'CurlExtensionNotLoadedException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidBaseUrlException $e) {
+    echo 'InvalidBaseUrlException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidSiteNameException $e) {
+    echo 'InvalidSiteNameException: ' . $e->getMessage(). PHP_EOL;
+} catch (JsonDecodeException $e) {
+    echo 'JsonDecodeException: ' . $e->getMessage(). PHP_EOL;
+} catch (LoginRequiredException $e) {
+    echo 'LoginRequiredException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlGeneralErrorException $e) {
+    echo 'CurlGeneralErrorException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlTimeoutException $e) {
+    echo 'CurlTimeoutException: ' . $e->getMessage(). PHP_EOL;
+} 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;
+}
+```
+
+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.
+
+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.
+
+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 the following functions/methods to GET/POST/PUT/DELETE data
+The class currently supports a large and growing number of functions/methods to access the UniFi Controller API. 
-through the UniFi Controller API. Please refer to the comments in the source code for
+Please refer to the comments/PHP DocBlocks in the source code for more details on each of the functions/methods,
-more details on each of the functions/methods and their respective parameters.
+their purpose, and their respective parameters.
 
-- login()
+If you are using an advanced IDE such as PHPStorm or VS Code, you can use its code completion and other
-- logout()
+features to explore the available functions/methods thanks to the extensive PHP DocBlocks throughout the code.
-- adopt_device()
-- archive_alarm()
-- assign_existing_admin()
-- authorize_guest()
-- block_sta()
-- cancel_rolling_upgrade()
-- check_controller_update()
-- check_firmware_update()
-- cmd_stat()
-- count_alarms()
-- create_apgroup() (supported with controller versions 6.0.X and higher)
-- create_dynamicdns()
-- create_firewallgroup()
-- create_hotspotop()
-- create_network()
-- create_radius_account()
-- create_site()
-- create_user()
-- create_usergroup()
-- create_voucher()
-- create_wlan()
-- custom_api_request()
-- delete_apgroup() (supported with controller versions 6.0.X and higher)
-- delete_device()
-- delete_firewallgroup()
-- delete_network()
-- delete_radius_account()
-- delete_site()
-- delete_usergroup()
-- delete_wlan()
-- disable_ap()
-- edit_apgroup() (supported with controller versions 6.0.X and higher)
-- edit_client_fixedip()
-- edit_client_name()
-- edit_firewallgroup()
-- edit_usergroup()
-- extend_guest_validity()
-- forget_sta() (supported on controller version 5.9.X and higher)
-- generate_backup()
-- generate_backup_site()
-- invite_admin()
-- led_override()
-- 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()
-- list_country_codes()
-- list_current_channels()
-- list_dashboard()
-- list_device_name_mappings()
-- list_devices()
-- list_dpi_stats()
-- list_dynamicdns()
-- list_events()
-- list_extension()
-- list_firewallgroups()
-- list_firmware()
-- list_guests()
-- list_health()
-- list_hotspotop()
-- list_known_rogueaps()
-- list_networkconf()
-- list_portconf()
-- list_portforward_stats()
-- list_portforwarding()
-- list_radius_accounts() (supported on controller version 5.5.19 and higher)
-- list_radius_profiles()
-- list_rogueaps()
-- list_routing()
-- list_self()
-- list_settings()
-- list_sites()
-- list_tags() (supported on controller version 5.5.19 and higher)
-- list_usergroups()
-- list_users()
-- list_wlan_groups()
-- list_wlanconf()
-- locate_ap()
-- move_device()
-- power_cycle_switch_port()
-- reboot_cloudkey()
-- reconnect_sta()
-- rename_ap()
-- restart_ap() (deprecated but still available as alias)
-- restart_device()
-- revoke_admin()
-- revoke_voucher()
-- set_ap_radiosettings()
-- set_device_settings_base()
-- set_dynamicdns()
-- set_element_adoption() (supported on controller version 5.13.X and higher)
-- set_guestlogin_settings()
-- set_guestlogin_settings_base()
-- set_ips_settings_base() (supported on controller version 5.9.10 and higher)
-- set_locate_ap() (deprecated but still available as alias)
-- set_networksettings_base()
-- set_radius_account_base()
-- set_site_connectivity()
-- set_site_country()
-- set_site_guest_access()
-- set_site_locale()
-- set_site_mgmt()
-- set_site_name()
-- set_site_ntp()
-- set_site_snmp()
-- 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()
-- set_wlansettings_base()
-- site_leds()
-- site_ledsoff() (deprecated but still available as alias)
-- 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_daily_aps()
-- stat_daily_gateway() (supported on controller version 5.7.X and higher)
-- stat_daily_site()
-- stat_daily_user() (supported on controller version 5.7.X and higher)
-- stat_full_status()
-- 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_monthly_aps()
-- stat_monthly_gateway()
-- stat_monthly_site()
-- stat_monthly_user()
-- stat_payment()
-- stat_sessions()
-- stat_sites()
-- stat_speedtest_results()
-- stat_sta_sessions_latest()
-- stat_status()
-- stat_sysinfo()
-- stat_voucher()
-- unauthorize_guest()
-- unblock_sta()
-- unset_locate_ap() (deprecated but still available as alias)
-- upgrade_device()
-- upgrade_device_external()
 
-Other functions, getters/setters:
 
-- get_class_version()
+## Looking for version 1.x.x?
-- get_cookie() (renamed from getcookie(), deprecated but still available, use get_cookies() instead)
+
-- get_cookies()
+With versions 1.x.x of the API client, the code was contained within a single file which can be useful in specific
-- get_curl_connection_timeout()
+cases.
-- get_curl_http_version()
+This has changed with version 2.0.0 where the code is now split into multiple files and is managed using composer.
-- get_curl_method()
+
-- get_curl_request_timeout()
+If you are looking for the version 1.x.x code, you can tell composer to install that version by using the following
-- get_curl_request_timeout()
+syntax in your `composer.json` file:
-- get_curl_ssl_verify_host()
+
-- get_curl_ssl_verify_peer()
+```javascript
-- get_debug()
+{
-- get_is_unifi_os()
+    "require": {
-- get_last_error_message()
+        "art-of-wifi/unifi-api-client": "^1.1"
-- get_last_results_raw()
+    }
-- get_site()
+}
-- set_connection_timeout()
+```
-- set_cookies()
+
-- set_curl_http_version()
+Alternatively, you can download the latest 1.x.x code from the [releases page](https://github.com/Art-of-WiFi/UniFi-API-client/releases).
-- set_curl_request_timeout()
-- set_curl_ssl_verify_host()
-- set_curl_ssl_verify_peer()
-- set_debug()
-- set_is_unifi_os()
-- set_request_method()
-- set_request_timeout()
-- set_site()
 
 ## Need help or have suggestions?
 
 There is still work to be done to add functionality and further improve the usability of
 this class, so all suggestions/comments are welcome. Please use the GitHub
-[issue list](https://github.com/Art-of-WiFi/UniFi-API-client/issues) or the Ubiquiti
+[Issues section](https://github.com/Art-of-WiFi/UniFi-API-client/issues) or the Ubiquiti
 Community forums (https://community.ubnt.com/t5/UniFi-Wireless/PHP-class-to-access-the-UniFi-controller-API-updates-and/td-p/1512870)
 to share your suggestions and questions.
 
-## Contribute
 
-If you would like to contribute code (improvements), please open an issue and include
+#### IMPORTANT NOTE:
-your code there or else create a pull request.
+When encountering issues with the UniFi API using other libraries, cURL or Postman, please do **not** open an Issue. Such issues will be closed immediately.
+Please use the [Discussions](https://github.com/Art-of-WiFi/UniFi-API-client/discussions) section instead.
+
 
 ## Credits
 
@@ -358,7 +292,17 @@ This class is based on the initial work by the following developers:
 
 and the API as published by Ubiquiti:
 
-- https://dl.ui.com/unifi/7.0.25/unifi_sh_api
+- 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
 

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",
@@ -20,7 +21,7 @@
         }
     ],
     "require": {
-        "php": ">=5.5.0",
+        "php": ">=7.4.0",
         "ext-curl": "*",
         "ext-json": "*"
     },

examples/list_alarms.php

@@ -3,8 +3,17 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description:    example basic PHP script to pull current alarms from the UniFi controller and output in json format
+ * 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;
+use UniFi_API\Exceptions\InvalidBaseUrlException;
+use UniFi_API\Exceptions\InvalidSiteNameException;
+use UniFi_API\Exceptions\JsonDecodeException;
+use UniFi_API\Exceptions\LoginFailedException;
+use UniFi_API\Exceptions\LoginRequiredException;
 
 /**
  * using the composer autoloader
@@ -12,8 +21,14 @@
 require_once 'vendor/autoload.php';
 
 /**
- * include the config file (place your credentials etc. there if not already present)
+ * Include the config file (place your credentials etc. there if not already present), see the config.template.php
- * see the config.template.php file for an example
+ * file for an example.
+ *
+ * @var array $controlleruser
+ * @var array $controllerpassword
+ * @var array $controllerurl
+ * @var array $controllerversion
+ * @var array $debug
  */
 require_once 'config.php';
 
@@ -25,19 +40,40 @@ $site_id = '<enter your site id here>';
 /**
  * initialize the UniFi API connection class and log in to the controller and do our thing
  */
-$unifi_connection = new UniFi_API\Client(
+try {
-    $controlleruser,
+    $unifi_connection = new UniFi_API\Client(
-    $controllerpassword,
+        $controlleruser,
-    $controllerurl,
+        $controllerpassword,
-    $site_id,
+        $controllerurl,
-    $controllerversion
+        $site_id,
-);
+        $controllerversion
+    );
 
-$set_debug_mode   = $unifi_connection->set_debug($debug);
+    $set_debug_mode = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
+    $login_results  = $unifi_connection->login();
-$data             = $unifi_connection->list_alarms();
+    $data           = $unifi_connection->list_alarms();
 
-/**
+    /**
- * provide feedback in json format
+     * echo the results in JSON format
- */
+     */
-echo json_encode($data, JSON_PRETTY_PRINT);
+    echo json_encode($data, JSON_PRETTY_PRINT);
+} catch (CurlExtensionNotLoadedException $e) {
+    echo 'CurlExtensionNotLoadedException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidBaseUrlException $e) {
+    echo 'InvalidBaseUrlException: ' . $e->getMessage(). PHP_EOL;
+} catch (InvalidSiteNameException $e) {
+    echo 'InvalidSiteNameException: ' . $e->getMessage(). PHP_EOL;
+} catch (JsonDecodeException $e) {
+    echo 'JsonDecodeException: ' . $e->getMessage(). PHP_EOL;
+} catch (LoginRequiredException $e) {
+    echo 'LoginRequiredException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlGeneralErrorException $e) {
+    echo 'CurlGeneralErrorException: ' . $e->getMessage(). PHP_EOL;
+} catch (CurlTimeoutException $e) {
+    echo 'CurlTimeoutException: ' . $e->getMessage(). PHP_EOL;
+} 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;
+}

examples/toggle_auto_update_settings.php

@@ -0,0 +1,69 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example to toggle the site-wide auto upgrade setting on a UniFi controller
+ */
+
+/**
+ * using the composer autoloader
+ */
+require_once('vendor/autoload.php');
+
+/**
+ * include the config file (place your credentials etc. there if not already present)
+ * see the config.template.php file for an example
+ *
+ * @var string $controlleruser the user name for access to the UniFi Controller
+ * @var string $controllerpassword the password for access to the UniFi Controller
+ * @var string $controllerurl full url to the UniFi Controller, eg. 'https://
+ * @var string $controllerversion the version of the Controller software, eg. '4.6.6' (must be at least 4.0.0)
+ * @var bool $debug set to true (without quotes) to enable debug output to the browser and the PHP error log
+ */
+require_once('config.php');
+
+/**
+ * site id for the site where settings are to be updated
+ */
+$site_id = 'zzzzz';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller to do our thing
+ */
+$unifi_connection = new UniFi_API\Client(
+    $controlleruser,
+    $controllerpassword,
+    $controllerurl,
+    $site_id,
+    $controllerversion
+);
+
+$login_results = $unifi_connection->login();
+
+if ($login_results) {
+    /**
+     * we get the current site mgmt settings
+     */
+    $current_site_settings = $unifi_connection->list_settings();
+
+    $mgmt_settings = [];
+    foreach ($current_site_settings as $section) {
+        if ($section->key == 'mgmt') {
+            $mgmt_settings = $section;
+        }
+    }
+
+    /**
+     * toggle the auto upgrade setting and set the auto upgrade hour to 3
+     */
+    $mgmt_settings->auto_upgrade      = !$mgmt_settings->auto_upgrade;
+    $mgmt_settings->auto_upgrade_hour = 3;
+    $mgmt_id                          = $mgmt_settings->_id;
+    $set_result                       = $unifi_connection->set_site_mgmt($mgmt_id, $mgmt_settings);
+
+    echo 'done' . PHP_EOL;
+    exit();
+}
+
+echo 'login failed' . PHP_EOL;

src/Exceptions/CurlExtensionNotLoadedException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+
+class CurlExtensionNotLoadedException extends Exception
+{
+    public function __construct()
+    {
+        parent::__construct('The PHP curl extension is not loaded. Please correct this before proceeding!');
+    }
+}

src/Exceptions/CurlGeneralErrorException.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+
+class CurlGeneralErrorException extends Exception
+{
+    /** @var mixed $_http_response_code */
+    private $_http_response_code;
+
+    /** @var mixed $_curl_getinfo_results */
+    private $_curl_getinfo_results;
+
+    public function __construct(string $message, $http_response_code, $_curl_getinfo_results)
+    {
+        $this->_http_response_code   = $http_response_code;
+        $this->_curl_getinfo_results = $_curl_getinfo_results;
+
+        parent::__construct($message);
+    }
+
+    /**
+     * Get the HTTP response code.
+     *
+     * @return mixed
+     */
+    public function getHttpResponseCode()
+    {
+        return $this->_http_response_code;
+    }
+
+    /**
+     * Get the cURL curl_getinfo results.
+     *
+     * @return mixed
+     */
+    public function getCurlGetinfoResults()
+    {
+        return $this->_curl_getinfo_results;
+    }
+}

src/Exceptions/CurlTimeoutException.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+
+class CurlTimeoutException extends Exception
+{
+    /** @var mixed $_http_response_code */
+    private $_http_response_code;
+
+    /** @var mixed $_curl_getinfo_results */
+    private $_curl_getinfo_results;
+
+    public function __construct(string $message, $http_response_code, $curl_getinfo_results)
+    {
+        $this->_http_response_code   = $http_response_code;
+        $this->_curl_getinfo_results = $curl_getinfo_results;
+
+        parent::__construct($message);
+    }
+
+    /**
+     * Get the HTTP response code.
+     *
+     * @return mixed
+     */
+    public function getHttpResponseCode()
+    {
+        return $this->_http_response_code;
+    }
+
+    /**
+     * Get the cURL curl_getinfo results.
+     *
+     * @return mixed
+     */
+    public function getCurlGetinfoResults()
+    {
+        return $this->_curl_getinfo_results;
+    }
+}

src/Exceptions/EmailInvalidException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+
+class EmailInvalidException extends Exception
+{
+    public function __construct()
+    {
+        parent::__construct('Invalid email address provided.');
+    }
+}

src/Exceptions/InvalidBaseUrlException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+
+class InvalidBaseUrlException extends Exception
+{
+    public function __construct()
+    {
+        parent::__construct('The base URL provided is invalid.');
+    }
+}

src/Exceptions/InvalidCurlMethodException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+
+class InvalidCurlMethodException extends Exception
+{
+    public function __construct()
+    {
+        parent::__construct('Invalid cURL method provided.');
+    }
+}

src/Exceptions/InvalidSiteNameException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+
+class InvalidSiteNameException extends Exception
+{
+    public function __construct()
+    {
+        parent::__construct('Invalid site name provided.');
+    }
+}

src/Exceptions/JsonDecodeException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+
+class JsonDecodeException extends Exception
+{
+    //
+}

src/Exceptions/LoginFailedException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+
+class LoginFailedException extends Exception
+{
+    //
+}

src/Exceptions/LoginRequiredException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+
+class LoginRequiredException extends Exception
+{
+    public function __construct()
+    {
+        parent::__construct('This method requires the API client to be logged in first.');
+    }
+}

src/Exceptions/MethodDeprecatedException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+
+class MethodDeprecatedException extends Exception
+{
+    //
+}