Add reboot_os_console method (#286)

- merged PR #284, contributed by @Jacobtims

.gitignore

@@ -13,4 +13,10 @@
 *.xml
 
 # ignore PHPStorm files
-.idea/*
+.idea/*
+
+# ignore the TODO list
+TODO.md
+
+# ignore Claude Code files
+CLAUDE*.md

README.md

@@ -14,32 +14,46 @@ 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. 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.0.x (**9.0.101 is confirmed**) |
-| UniFi OS                             | 3.x, 4.1.x (**4.1.9 is confirmed**)                  |
+| 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:
+- 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 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
-- do not use UniFi Cloud accounts and do not enable 2FA for the accounts that you use with this class
+  - 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
 
-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:
+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)
@@ -51,21 +65,23 @@ These devices/services have been verified to work:
 - 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-based controllers 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
+### 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 more details:
+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 previous versions
@@ -73,16 +89,13 @@ The "custom firewall rule" approach described there is the recommended method.
 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
+- 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) 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
 installed already.
@@ -112,26 +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';
-```
-
 ## Example usage
 
-A basic example of how to use the class:
+A quick and basic example of how to use the class:
 
 ```php
 /**
@@ -148,6 +144,7 @@ $login            = $unifi_connection->login();
 $results          = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects
 ```
 
+
 #### 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
@@ -168,13 +165,19 @@ $results          = $unifi_connection->list_alarms(); // returns a PHP array con
    [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.
 
-Here is an example of how to catch these Exceptions:
+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
 /**
@@ -230,7 +233,7 @@ try {
 ```
 
 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
+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
@@ -249,12 +252,30 @@ 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
 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?
+
+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.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.
+
 
 ## Looking for version 1.x.x?
 
-With versions 1.x.x of the API client, the code 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 into multiple files and is managed using composer.
+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:
@@ -269,18 +290,7 @@ syntax in your `composer.json` file:
 
 Alternatively, you can download the latest 1.x.x code from the [releases page](https://github.com/Art-of-WiFi/UniFi-API-client/releases).
 
-## 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
-[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.
-
-
-#### 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.
+Whenever necessary, we will make sure to update the **version_1** branch with the latest 1.x.x code.
 
 
 ## Credits
@@ -304,6 +314,16 @@ If you would like to contribute to this project, please open an issue and includ
 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
 
 Many of the functions in this API client class are not officially supported by Ubiquiti

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;
+}

src/Exceptions/CurlExtensionNotLoadedException.php

@@ -2,9 +2,15 @@
 
 namespace UniFi_API\Exceptions;
 
-use Exception;
-
-class CurlExtensionNotLoadedException extends Exception
+/**
+ * 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()
     {

src/Exceptions/CurlGeneralErrorException.php

@@ -2,9 +2,15 @@
 
 namespace UniFi_API\Exceptions;
 
-use Exception;
-
-class CurlGeneralErrorException extends Exception
+/**
+ * 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;
@@ -17,7 +23,7 @@ class CurlGeneralErrorException extends Exception
         $this->_http_response_code   = $http_response_code;
         $this->_curl_getinfo_results = $_curl_getinfo_results;
 
-        parent::__construct($message);
+        parent::__construct($message, $http_response_code);
     }
 
     /**

src/Exceptions/CurlTimeoutException.php

@@ -2,9 +2,15 @@
 
 namespace UniFi_API\Exceptions;
 
-use Exception;
-
-class CurlTimeoutException extends Exception
+/**
+ * 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;
@@ -17,7 +23,7 @@ class CurlTimeoutException extends Exception
         $this->_http_response_code   = $http_response_code;
         $this->_curl_getinfo_results = $curl_getinfo_results;
 
-        parent::__construct($message);
+        parent::__construct($message, $http_response_code);
     }
 
     /**

src/Exceptions/EmailInvalidException.php

@@ -2,9 +2,14 @@
 
 namespace UniFi_API\Exceptions;
 
-use Exception;
-
-class EmailInvalidException extends Exception
+/**
+ * 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()
     {

src/Exceptions/InvalidBaseUrlException.php

@@ -2,9 +2,12 @@
 
 namespace UniFi_API\Exceptions;
 
-use Exception;
-
-class InvalidBaseUrlException extends Exception
+/**
+ * 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()
     {

src/Exceptions/InvalidCurlMethodException.php

@@ -2,9 +2,12 @@
 
 namespace UniFi_API\Exceptions;
 
-use Exception;
-
-class InvalidCurlMethodException extends Exception
+/**
+ * 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()
     {

src/Exceptions/InvalidSiteNameException.php

@@ -2,9 +2,15 @@
 
 namespace UniFi_API\Exceptions;
 
-use Exception;
-
-class InvalidSiteNameException extends Exception
+/**
+ * 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()
     {

src/Exceptions/JsonDecodeException.php

@@ -2,9 +2,12 @@
 
 namespace UniFi_API\Exceptions;
 
-use Exception;
-
-class JsonDecodeException extends Exception
+/**
+ * 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

@@ -2,9 +2,35 @@
 
 namespace UniFi_API\Exceptions;
 
-use Exception;
-
-class LoginFailedException extends Exception
+/**
+ * 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

@@ -2,9 +2,12 @@
 
 namespace UniFi_API\Exceptions;
 
-use Exception;
-
-class LoginRequiredException extends Exception
+/**
+ * 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()
     {

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

@@ -2,9 +2,15 @@
 
 namespace UniFi_API\Exceptions;
 
-use Exception;
-
-class MethodDeprecatedException extends Exception
+/**
+ * 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);
+    }
+}