Add reboot_os_console method (#286)

- merged PR #284, contributed by @Jacobtims

.gitignore

@@ -14,3 +14,9 @@
 
 # ignore PHPStorm files
 .idea/*
+
+# ignore the TODO list
+TODO.md
+
+# ignore Claude Code files
+CLAUDE*.md

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,89 +1,117 @@
 ## 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.
 
-UniFi Network Application software versions 5.X.X, 6.X.X, 7.X.X, and 8.X.X (version **8.1.104** has been confirmed to work)
-are supported as well as Network Applications on **UniFi OS-based consoles** (UniFi OS **3.2.12** 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 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.
+
+
+## Why use this API client?
+
+- Easy to use: clear docs, comprehensive method coverage, and helpful examples.
+- Broad coverage: exposes many UniFi endpoints not (yet) available in the official APIs.
+- Composer-friendly: installable via [Composer](https://getcomposer.org) and works with modern PHP projects.
+- Lightweight and dependency-free: no external libraries required; uses cURL.
+- Secure: communicates over TLS and supports optional SSL certificate validation.
+- Flexible and extensible: includes `custom_api_request()` for calling any API endpoint.
+- Robust error handling: throws named Exceptions for precise try/catch handling.
+- Actively maintained: regular updates and compatibility with recent UniFi versions.
+
+
+## Supported Versions
+
+| Software                             | Versions                                                  |
+|--------------------------------------|-----------------------------------------------------------|
+| UniFi Network Application/controller | 5.x, 6.x, 7.x, 8.x, 9.x, 10.x (**10.0.154 is confirmed**) |
+| UniFi OS                             | 3.x, 4.x, 5.x (**5.0.5 is confirmed**)                    |
 
 
 ## Requirements
 
-- 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.2.12 and cURL 7.81.0
-- 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 permissions** to access the UniFi Controller API through this class
-- do not use UniFi Cloud accounts and do not enable 2FA for the accounts that you use with this class
+- a server or desktop 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 cURL (`php-curl`) module enabled
+  - direct network connectivity between this server/desktop and the host and port where the UniFi Network Application is
+    running (usually TCP port 8443, port 11443 for UniFi OS Server, or port 443 for UniFi OS consoles)
+- you **must** use an admin **account with local access permissions** to access the API through this class as explained
+  here:  
+  https://artofwifi.net/blog/use-local-admin-account-unifi-api-captive-portal
+- do **not** use UniFi Cloud accounts and do not enable MFA/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. These devices have been verified to work:
+Starting from version **1.1.47**, this API client also supports UniFi OS-based controllers. These
+applications/devices/services have been verified to work:
+- UniFi OS Server, announcement [here](https://blog.ui.com/article/introducing-unifi-os-server)
 - 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)
+- HostiFi UniFi Cloud Hosting, details [here](https://hostifi.com/unifi)
 
-The class automatically detects UniFi OS consoles and adjusts the URLs and several functions/methods accordingly.
+The class automatically detects UniFi OS consoles/servers and adjusts URLs and several functions/methods accordingly.
 
-UniFi OS consoles require you to connect using port **443** instead of **8443** which is used for "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.
+UniFi OS-based consoles require you to connect using port **443** while **8443** which is used for
+the self-hosted/software-based controllers. When connecting to **UniFi OS Server**, you are required to use port
+**11443**.
 
 
-### Remote API access to UniFi OS-based controllers
-When connecting to a UniFi OS 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:
+### Remote API access to UniFi OS-based gateways
+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 detailed instructions when using the **"Classic"**
+firewall:  
 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.
+See this blog post when using the **Zone-Based firewall** (ZBF):  
+https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a-udm-pro-using-zbf
 
 
-## Upgrading from a previous version
+## Upgrading from previous versions
 
-When upgrading from a version before **1.1.84**, please:
-- make sure you are using PHP **7.4** or higher
-- test the client with your code for any breaking changes; the class methods now have strict parameter type hints and 
-  response types which can break your code in certain cases where the wrong type is passed or a different response type
-  is expected back
+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
+- see the note [here](#looking-for-version-1xx) regarding the single file version (1.x.x) of the API client
 
 
 ## Installation
 
-Use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) 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
 {
     "require": {
-        "art-of-wifi/unifi-api-client": "^1.1"
+        "art-of-wifi/unifi-api-client": "^2.0"
     }
 }
 ```
@@ -97,42 +125,9 @@ Finally, be sure to include the composer autoloader in your code if your framewo
 require_once 'vendor/autoload.php';
 ```
 
-
-### Git
-
-Execute the following `git` command from the shell in your project directory:
-
-```sh
-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
-/**
- * load the class directly instead of using the composer autoloader
- */
-require_once 'path/to/src/Client.php';
-```
-
-
-### 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
-/**
- * load the class directly instead of using the composer autoloader
- */
-require_once 'path/to/src/Client.php';
-```
-
-
 ## Example usage
 
-A basic example how to use the class:
+A quick and basic example of how to use the class:
 
 ```php
 /**
@@ -149,21 +144,18 @@ $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.
 
@@ -173,192 +165,95 @@ 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.
 
+### Code Examples:
+
+More code examples are available in the [`examples/`](examples/) directory.
+
+## 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.
+
+You can also choose to catch the `UniFi_API\Exceptions\UnifiApiException` Exception to catch all Exceptions that
+might be thrown by the API Client class.
+
+Here is an example of how to catch each of the Exceptions individually:
+```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
+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 access the UniFi Controller API. This list is sorted
-alphabetically. Please refer to the comments in the source code for more details on each of the functions/methods,
+The class currently supports a large and growing number of functions/methods to access the UniFi Controller API. 
+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.
 
-- adopt_device()
-- advanced_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()
-- create_dynamicdns()
-- create_firewallgroup()
-- create_hotspotop()
-- create_network()
-- create_radius_account()
-- create_user()
-- create_usergroup()
-- create_voucher()
-- create_wlan()
-- custom_api_request()
-- delete_apgroup()
-- delete_device()
-- delete_firewallgroup()
-- delete_network()
-- delete_radius_account()
-- delete_site()
-- delete_usergroup()
-- delete_wlan()
-- disable_ap()
-- disable_wlan()
-- edit_apgroup()
-- edit_client_fixedip()
-- edit_client_name()
-- edit_firewallgroup()
-- edit_usergroup()
-- extend_guest_validity()
-- forget_sta()
-- generate_backup()
-- generate_backup_site()
-- get_class_version()
-- get_cookie()
-- get_cookies()
-- get_curl_connection_timeout()
-- get_curl_http_version()
-- get_curl_method()
-- get_curl_request_timeout()
-- get_curl_request_timeout()
-- get_curl_ssl_verify_host()
-- get_curl_ssl_verify_peer()
-- get_debug()
-- get_is_unifi_os()
-- get_last_error_message()
-- get_last_results_raw()
-- get_site()
-- invite_admin()
-- led_override()
-- list_admins()
-- list_all_admins()
-- list_alarms()
-- list_aps()
-- list_backups()
-- list_clients()
-- list_country_codes()
-- list_current_channels()
-- list_dashboard()
-- list_device_name_mappings()
-- list_device_states()
-- list_devices()
-- list_devices_basic()
-- 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()
-- list_radius_profiles()
-- list_self()
-- list_settings()
-- list_sites()
-- list_tags()
-- list_users()
-- list_wlan_groups()
-- list_wlanconf()
-- locate_ap()
-- login()
-- logout()
-- move_device()
-- power_cycle_switch_port()
-- reboot_cloudkey()
-- rename_ap()
-- revoke_admin()
-- revoke_voucher()
-- set_ap_radiosettings()
-- set_ap_wlangroup()
-- set_connection_timeout()
-- set_cookies()
-- set_curl_http_version()
-- set_curl_request_timeout()
-- set_curl_ssl_verify_host()
-- set_curl_ssl_verify_peer()
-- set_debug()
-- set_device_settings_base()
-- set_dynamicdns()
-- set_element_adoption()
-- set_guestlogin_settings()
-- set_guestlogin_settings_base()
-- set_ips_settings_base()
-- set_is_unifi_os()
-- set_locate_ap() (deprecated but still available as alias)
-- set_networksettings_base()
-- set_radius_account_base()
-- set_request_method()
-- set_request_timeout()
-- set_site()
-- 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()
-- spectrum_scan()
-- spectrum_scan_state()
-- start_rolling_upgrade()
-- stat_5minutes_aps()
-- stat_5minutes_gateway()
-- stat_5minutes_site()
-- stat_5minutes_user()
-- stat_allusers()
-- stat_auths()
-- stat_client()
-- stat_daily_aps()
-- stat_daily_gateway()
-- stat_daily_site()
-- stat_daily_user()
-- stat_full_status()
-- stat_hourly_aps()
-- stat_hourly_gateway()
-- stat_hourly_site()
-- stat_hourly_user()
-- stat_ips_events()
-- 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()
+If you are using an advanced IDE such as PHPStorm or VS Code, you can use its code completion and other
+features to explore the available functions/methods thanks to the extensive PHP DocBlocks throughout the code.
+
+For a quick overview of the available functions/methods, you can also check the API Reference here:  
+[API Reference](API_REFERENCE.md)
 
 
 ## Need help or have suggestions?
@@ -366,19 +261,36 @@ their purpose, and their respective parameters.
 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
 [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)
+Community forums (https://community.ui.com/questions/PHP-client-class-to-access-the-UniFi-controller-API-updates-and-discussion-part-2/a793904e-6023-4a7f-bcae-340db2a03fc1)
 to share your suggestions and questions.
 
 
 #### IMPORTANT NOTE:
-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.
+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.
 
 
-## Contribute
+## Looking for version 1.x.x?
 
-If you would like to contribute code (improvements), please open an issue and include
-your code there or else create a pull request.
+With versions 1.x.x of the API client, the entire client was contained within a single file which can be useful in
+specific cases.
+This has changed with version 2.0.0 where the code is now split across multiple files and inclusion in your project is
+managed using composer.
+
+If you are looking for the version 1.x.x code, you can tell composer to install that version by using the following
+syntax in your `composer.json` file:
+
+```javascript
+{
+    "require": {
+        "art-of-wifi/unifi-api-client": "^1.1"
+    }
+}
+```
+
+Alternatively, you can download the latest 1.x.x code from the [releases page](https://github.com/Art-of-WiFi/UniFi-API-client/releases).
+
+Whenever necessary, we will make sure to update the **version_1** branch with the latest 1.x.x code.
 
 
 ## Credits
@@ -390,7 +302,26 @@ This class is based on the initial work by the following developers:
 
 and the API as published by Ubiquiti:
 
-- https://dl.ui.com/unifi/8.0.26/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.
+
+
+## About Art of WiFi
+
+Art of WiFi develops software and tools that enhance the capabilities of UniFi networks. From captive portals and
+reporting solutions to device search utilities, our goal is to make UniFi deployments more powerful and easier to
+manage.
+
+If you're looking for a specific solution or just want to see what else we offer, feel free to explore our web site:
+- https://www.artofwifi.net
 
 
 ## 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",

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)
- * see the config.template.php file for an example
+ * Include the config file (place your credentials etc. there if not already present), see the config.template.php
+ * file for an example.
+ *
+ * @var array $controlleruser
+ * @var array $controllerpassword
+ * @var array $controllerurl
+ * @var array $controllerversion
+ * @var array $debug
  */
 require_once 'config.php';
 
@@ -25,6 +40,7 @@ $site_id = '<enter your site id here>';
 /**
  * initialize the UniFi API connection class and log in to the controller and do our thing
  */
+try {
     $unifi_connection = new UniFi_API\Client(
         $controlleruser,
         $controllerpassword,
@@ -34,10 +50,30 @@ $unifi_connection = new UniFi_API\Client(
     );
 
     $set_debug_mode = $unifi_connection->set_debug($debug);
-$loginresults     = $unifi_connection->login();
+    $login_results  = $unifi_connection->login();
     $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) {
+    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/ppsks_examples/create_ppsk.php

@@ -0,0 +1,131 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to create a new PPSK for a WLAN on the UniFi controller
+ */
+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;
+
+require 'vendor/autoload.php';
+
+/**
+ * Record start time.
+ */
+$start_time = microtime(true);
+
+/**
+ * Include the config file (place your credentials etc. there if not already present),
+ * see the config.template.php file for an example.
+ *
+ * @var array $controller_user
+ * @var array $controller_password
+ * @var array $controller_url
+ * @var array $controller_version
+ * @var array $debug
+ */
+require_once 'config.php';
+
+/**
+ * The id of the site to use.
+ */
+$site_id = 'default';
+
+/**
+ * The new PPSK details.
+ */
+$new_ppsk_password   = 'mysecretppsk'; // the password for the new PPSK, this password must be unique for the SSID, between 8-63 characters
+$new_ppsk_network_id = 'zzzzzzzzzzzzzzzzzzzzz'; // id for the required VLAN, taken from the output of list_networkconf()
+$new_ppsk_wlan_id    = 'xxxxxxxxxxxxxxxxxxxxx'; // id for the required WLAN, taken from the output of list_wlanconf()
+
+try {
+    /**
+     * initialize the UniFi API connection class and log in to the controller and do our thing
+     */
+    $unifi_connection = new UniFi_API\Client(
+        $controller_user,
+        $controller_password,
+        $controller_url,
+        $site_id,
+        $controller_version
+    );
+
+    $request_start_time = microtime(true);
+
+    $set_debug_mode = $unifi_connection->set_debug($debug);
+    $login_results  = $unifi_connection->login();
+    $wlan_conf      = $unifi_connection->list_wlanconf();
+
+    /**
+     * Get the details for the WLAN the PPSK will be created for.
+     */
+    $wlan_details = [];
+
+    foreach ($wlan_conf as $wlan) {
+        if ($wlan->_id === $new_ppsk_wlan_id) {
+            $wlan_details = $wlan;
+
+            break;
+        }
+    }
+
+    if (empty($wlan_details)) {
+        echo 'WLAN not found, exiting... Please check the $new_ppsk_wlan_id value 🤨' . PHP_EOL;
+
+        exit;
+    }
+
+    /**
+     * Create the new PPSK, then append it to the existing PPSKs array.
+     */
+    $new_ppsk = [
+        'password'       => $new_ppsk_password,
+        'networkconf_id' => $new_ppsk_network_id,
+    ];
+
+    $wlan_details->private_preshared_keys[] = $new_ppsk;
+
+    $unifi_connection->set_wlansettings_base($new_ppsk_wlan_id, $wlan_details);
+
+    $request_end_time = microtime(true);
+
+    /**
+     * Record end time.
+     */
+    $end_time = microtime(true);
+
+    /**
+     * Calculate and display the execution time.
+     */
+    $execution_time = $end_time - $start_time;
+
+    echo 'The PPSK has been created successfully!👍' . PHP_EOL;
+
+    echo 'Full execution time: ' . $execution_time . ' seconds' . PHP_EOL;
+    echo 'Time to fetch, process and push data back: ' . ($request_end_time - $request_start_time) . ' seconds' . PHP_EOL;
+} 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) {
+    echo 'General Exception: ' . $e->getMessage(). PHP_EOL;
+}

examples/ppsks_examples/list_ppsks.php

@@ -0,0 +1,108 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to list all PPSKs for all WLANs in a specific UniFi site
+ */
+
+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;
+
+require 'vendor/autoload.php';
+
+/**
+ * Record start time.
+ */
+$start_time = microtime(true);
+
+/**
+ * Include the config file (place your credentials etc. there if not already present),
+ * see the config.template.php file for an example.
+ *
+ * @var array $controller_user
+ * @var array $controller_password
+ * @var array $controller_url
+ * @var array $controller_version
+ * @var array $debug
+ */
+require_once 'config.php';
+
+/**
+ * The id of the site to use.
+ */
+$site_id = 'default';
+
+try {
+    /**
+     * initialize the UniFi API connection class and log in to the controller and do our thing
+     */
+    $unifi_connection = new UniFi_API\Client(
+        $controller_user,
+        $controller_password,
+        $controller_url,
+        $site_id,
+        $controller_version
+    );
+
+    $request_start_time = microtime(true);
+
+    $set_debug_mode = $unifi_connection->set_debug($debug);
+    $login_results  = $unifi_connection->login();
+    $wlan_conf      = $unifi_connection->list_wlanconf();
+
+    /**
+     * Get the details for the WLAN the PPSK will be created for.
+     */
+    $wlan_details = [];
+
+    foreach ($wlan_conf as $wlan) {
+        /**
+         * Skip this SSID if private_pre_shared_keys is not set or empty.
+         */
+        if (empty($wlan->private_preshared_keys)) {
+            continue;
+        }
+
+        echo json_encode($wlan->private_preshared_keys, JSON_PRETTY_PRINT) . PHP_EOL;
+    }
+
+    $request_end_time = microtime(true);
+
+    /**
+     * Record end time.
+     */
+    $end_time = microtime(true);
+
+    /**
+     * Calculate and display the execution time.
+     */
+    $execution_time = $end_time - $start_time;
+
+    echo 'Full execution time: ' . $execution_time . ' seconds' . PHP_EOL;
+    echo 'Time to fetch, process and push data back: ' . ($request_end_time - $request_start_time) . ' seconds' . PHP_EOL;
+} 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) {
+    echo 'General Exception: ' . $e->getMessage(). PHP_EOL;
+}

examples/ppsks_examples/remove_ppsk.php

@@ -0,0 +1,141 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to remove a PPSK from a specific UniFi site
+ */
+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;
+
+require 'vendor/autoload.php';
+
+/**
+ * Record start time.
+ */
+$start_time = microtime(true);
+
+$total_removals = 0;
+
+/**
+ * Include the config file (place your credentials etc. there if not already present),
+ * see the config.template.php file for an example.
+ *
+ * @var array $controller_user
+ * @var array $controller_password
+ * @var array $controller_url
+ * @var array $controller_version
+ * @var array $debug
+ */
+require_once 'config.php';
+
+/**
+ * The id of the site to use.
+ */
+$site_id = 'default';
+
+/**
+ * The password value of the PPSK to remove.
+ */
+$ppsk_to_remove = 'mysecretppsk';
+
+try {
+    /**
+     * Initialize the UniFi API connection class and log in to the controller and do our thing.
+     */
+    $unifi_connection = new UniFi_API\Client(
+        $controller_user,
+        $controller_password,
+        $controller_url,
+        $site_id,
+        $controller_version
+    );
+
+    $request_start_time = microtime(true);
+
+    $set_debug_mode = $unifi_connection->set_debug($debug);
+    $login_results  = $unifi_connection->login();
+    $wlan_conf      = $unifi_connection->list_wlanconf();
+
+    foreach ($wlan_conf as $wlan) {
+        /**
+         * Skip this SSID if the private_pre_shared_keys array is not set or empty.
+         */
+        if (empty($wlan->private_preshared_keys)) {
+            continue;
+        }
+
+        $removals = 0;
+
+        foreach ($wlan->private_preshared_keys as $ppsk) {
+            if ($ppsk->password === $ppsk_to_remove) {
+                echo 'Removing PPSK with password: "' . $ppsk_to_remove . '"' . PHP_EOL;
+
+                /**
+                 * Remove the PPSK from the private_preshared_keys array.
+                 */
+                $wlan->private_preshared_keys = array_values(array_filter($wlan->private_preshared_keys, function ($value) use ($ppsk_to_remove) {
+                    return $value->password !== $ppsk_to_remove;
+                }));
+
+                $removals++;
+            }
+        }
+
+        /**
+         * Push the updated WLAN configuration back to the controller if we removed one or more PPSKs.
+         */
+        if ($removals > 0) {
+            echo 'Pushing updated WLAN configuration back to the controller...' . PHP_EOL;
+            $unifi_connection->set_wlansettings_base($wlan->_id, $wlan);
+            $total_removals += $removals;
+        }
+    }
+
+    $request_end_time = microtime(true);
+
+    /**
+     * Record end time.
+     */
+    $end_time = microtime(true);
+
+    /**
+     * Calculate the execution time.
+     */
+    $execution_time = $end_time - $start_time;
+
+    if ($total_removals === 0) {
+        echo 'No PPSKs were removed, exiting...' . PHP_EOL;
+
+        exit;
+    }
+
+    echo 'Total PPSKs removed: ' . $total_removals . PHP_EOL;
+
+    echo 'Full execution time: ' . $execution_time . ' seconds' . PHP_EOL;
+    echo 'Time to fetch, process and push data back: ' . ($request_end_time - $request_start_time) . ' seconds' . PHP_EOL;
+} 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) {
+    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,19 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when the required PHP cURL extension is not loaded in the runtime.
+ *
+ * @note Consumers can catch this to provide an installation hint or to disable any
+ *       functionality that requires cURL.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class CurlExtensionNotLoadedException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('The PHP curl extension is not loaded. Please correct this before proceeding!');
+    }
+}

src/Exceptions/CurlGeneralErrorException.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a general cURL error occurs while calling the UniFi API.
+ *
+ * @property-read mixed $httpResponseCode HTTP response code if available
+ * @property-read mixed $curlGetinfoResults Results from curl_getinfo() if available
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class CurlGeneralErrorException extends UnifiApiException
+{
+    /** @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, $http_response_code);
+    }
+
+    /**
+     * 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,48 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a cURL request times out.
+ *
+ * @property-read mixed $httpResponseCode HTTP response code if available
+ * @property-read mixed $curlGetinfoResults Result of curl_getinfo() when available
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class CurlTimeoutException extends UnifiApiException
+{
+    /** @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, $http_response_code);
+    }
+
+    /**
+     * 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,18 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when an invalid email address is provided to the client.
+ *
+ * @note This Exception is used for input validation where a properly formatted email is required.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class EmailInvalidException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('Invalid email address provided.');
+    }
+}

src/Exceptions/InvalidBaseUrlException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when the provided base URL for the UniFi controller is invalid.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class InvalidBaseUrlException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('The base URL provided is invalid.');
+    }
+}

src/Exceptions/InvalidCurlMethodException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when an unsupported or invalid cURL method is requested by the client.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class InvalidCurlMethodException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('Invalid cURL method provided.');
+    }
+}

src/Exceptions/InvalidSiteNameException.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a provided short site name is invalid or cannot be used by the client.
+ *
+ * @note This Exception is thrown when the short site name contains illegal characters or when
+ *       the name does not correspond to any known site on the controller.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class InvalidSiteNameException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('Invalid site name provided.');
+    }
+}

src/Exceptions/JsonDecodeException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when the library fails to decode JSON returned by the controller.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class JsonDecodeException extends UnifiApiException
+{
+    // Intentionally empty - represents JSON decoding failures.
+}

src/Exceptions/LoginFailedException.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when the client fails to authenticate with the UniFi controller.
+ *
+ * @note This can indicate invalid credentials, connectivity problems, or a change
+ *       in the controller's authentication mechanism (e.g., MFA).
+ *
+ * @property-read mixed $httpResponseCode HTTP response code if available
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class LoginFailedException extends UnifiApiException
+{
+    /** @var mixed $_http_response_code */
+    private $_http_response_code;
+
+    public function __construct(string $message, $http_response_code)
+    {
+        $this->_http_response_code   = $http_response_code;
+
+        parent::__construct($message, $http_response_code);
+    }
+
+    /**
+     * Get the HTTP response code.
+     *
+     * @return mixed
+     */
+    public function getHttpResponseCode()
+    {
+        return $this->_http_response_code;
+    }
+}

src/Exceptions/LoginRequiredException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a method that requires authentication is called before logging in.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class LoginRequiredException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('This method requires the API client to be logged in first.');
+    }
+}

src/Exceptions/MacAddressEmptyException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a MAC address was expected, but none was provided (empty/null).
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class MacAddressEmptyException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('MAC address is empty.');
+    }
+}

src/Exceptions/MacAddressInvalidException.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a provided MAC address does not match expected formatting or
+ * validation rules.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class MacAddressInvalidException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('MAC address is invalid.');
+    }
+}

src/Exceptions/MethodDeprecatedException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when a library method or API endpoint has been deprecated and should
+ * no longer be used.
+ *
+ * @note Consumers can catch this to provide migration guidance or suppress warnings for legacy callers.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class MethodDeprecatedException extends UnifiApiException
+{
+    // Intentionally empty - serves as a distinct exception type.
+}

src/Exceptions/NotAUnifiOsConsoleException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+/**
+ * Thrown when the target host is not a UniFi OS console.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class NotAUnifiOsConsoleException extends UnifiApiException
+{
+    public function __construct()
+    {
+        parent::__construct('This is not a UniFi OS console.');
+    }
+}

src/Exceptions/UnifiApiException.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace UniFi_API\Exceptions;
+
+use Exception;
+use Throwable;
+
+/**
+ * Base exception for the UniFi API client.
+ *
+ * @note All custom exceptions in this library extend this class so consumers can
+ *       catch a single type (\UniFi_API\Exceptions\UnifiApiException) when they
+ *       want to handle all client errors uniformly.
+ *
+ * @package UniFi_Controller_API_Client_Class
+ */
+class UnifiApiException extends Exception
+{
+    /**
+     * UnifiApiException constructor.
+     *
+     * @param string         $message  Human-readable message describing the error.
+     * @param int            $code     Optional error code.
+     * @param Throwable|null $previous Optional previous exception for chaining.
+     */
+    public function __construct(string $message = 'An error occurred in the UniFi API client.', int $code = 0, ?Throwable $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+    }
+}