davidl/UniFi-API-client
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated docblocks for improved IDE hints

Browse Source 
updated README with supported versions
updated README wording to improve readability
This commit is contained in:
malle-pietje
2025-11-19 10:41:58 +01:00
parent 05cb58b9f1
commit fe4c18c53e
8 changed files with 37 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
README.md
View File

@@ -18,8 +18,8 @@ easy inclusion in your projects. See the [installation instructions](#Installati
| Software | Versions | | Software | Versions |
|--------------------------------------|-----------------------------------------------------------| |--------------------------------------|-----------------------------------------------------------|
| UniFi Network Application/controller | 5.x, 6.x, 7.x, 8.x, 9.x, 10.x (**10.0.140 is confirmed**) | | 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.4 is confirmed**) | | UniFi OS | 3.x, 4.x, 5.x (**5.0.5 is confirmed**) |
## Requirements ## Requirements
@@ -27,11 +27,12 @@ easy inclusion in your projects. See the [installation instructions](#Installati
- a server with: - 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) - 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) for PHP 7.3.x and lower)
- PHP json and PHP cURL modules enabled - PHP cURL (`php-curl`) module enabled
- direct network connectivity between this server and the host and port (usually TCP port 8443, port 11443 for UniFi OS - direct network connectivity between this server and the host and port (usually TCP port 8443, port 11443 for UniFi OS
Server, or port 443 for UniFi OS consoles) where the UniFi Network Application is running Server, or port 443 for UniFi OS consoles) where the UniFi Network Application is running
- you **must** use an admin **account with local access permissions** to access the API through this class as explained - 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 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 - do **not** use UniFi Cloud accounts and do not enable MFA/2FA for the accounts that you use with this class
@@ -58,19 +59,18 @@ These applications/devices/services have been verified to work:
The class automatically detects UniFi OS consoles/servers and adjusts the URLs and several functions/methods The class automatically detects UniFi OS consoles/servers and adjusts the URLs and several functions/methods
accordingly. accordingly.
UniFi OS-based consoles require you to connect using port **443** instead of **8443** which is used for UniFi OS-based consoles require you to connect using port **443** while **8443** which is used for
the classic "software-based" controllers. When using **UniFi OS Server**, you are required to use port **11443**. the self-hosted/software-based controllers. When connecting to **UniFi OS Server**, you are required to use port
**11443**.
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, with port 443 or port 11443 when working with a UniFi OS-based controller.
### Remote API access to UniFi OS-based controllers ### 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 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 more details when using the **"Classic"** firewall:
https://artofwifi.net/blog/how-to-access-the-unifi-controller-by-wan-ip-or-hostname-on-a-udm-pro 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 ## Upgrading from previous versions
@@ -133,6 +133,9 @@ $login = $unifi_connection->login();
$results = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects $results = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects
``` ```
More examples are available in the `examples/` directory.
#### IMPORTANT NOTES: #### 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 1. In the above example, `$site_id` is the short site "name" (usually 8 characters long) that is visible in the URL when
@@ -218,7 +221,7 @@ try {
``` ```
Although the PHP DocBlocks for most public methods/functions contain `@throws Exception`, it is recommended to catch 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. 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 In most cases, the class will let Exceptions bubble up to the calling code, but in some cases it will catch them and

6
src/Client.php
View File

@@ -3917,6 +3917,7 @@ class Client
****************************************************************/ ****************************************************************/
/** /**
* @deprecated Use list_devices() instead
* @throws MethodDeprecatedException * @throws MethodDeprecatedException
*/ */
public function list_aps() public function list_aps()
@@ -3925,6 +3926,7 @@ class Client
} }
/** /**
* @deprecated Use locate_ap() instead
* @throws MethodDeprecatedException * @throws MethodDeprecatedException
*/ */
public function set_locate_ap() public function set_locate_ap()
@@ -3933,6 +3935,7 @@ class Client
} }
/** /**
* @deprecated Use locate_ap() instead
* @throws MethodDeprecatedException * @throws MethodDeprecatedException
*/ */
public function unset_locate_ap(): bool public function unset_locate_ap(): bool
@@ -3941,6 +3944,7 @@ class Client
} }
/** /**
* @deprecated Use site_leds() instead
* @throws MethodDeprecatedException * @throws MethodDeprecatedException
*/ */
public function site_ledson(): bool public function site_ledson(): bool
@@ -3949,6 +3953,7 @@ class Client
} }
/** /**
* @deprecated Use site_leds() instead
* @throws MethodDeprecatedException * @throws MethodDeprecatedException
*/ */
public function site_ledsoff(): bool public function site_ledsoff(): bool
@@ -3957,6 +3962,7 @@ class Client
} }
/** /**
* @deprecated Use restart_device() instead
* @throws MethodDeprecatedException * @throws MethodDeprecatedException
*/ */
public function restart_ap(): bool public function restart_ap(): bool

4
src/Exceptions/CurlExtensionNotLoadedException.php
View File

@@ -5,8 +5,8 @@ namespace UniFi_API\Exceptions;
/** /**
* Thrown when the required PHP cURL extension is not loaded in the runtime. * Thrown when the required PHP cURL extension is not loaded in the runtime.
* *
* Consumers can catch this to provide an installation hint or to disable any * @note Consumers can catch this to provide an installation hint or to disable any
* functionality that requires cURL. * functionality that requires cURL.
* *
* @package UniFi_Controller_API_Client_Class * @package UniFi_Controller_API_Client_Class
*/ */

2
src/Exceptions/EmailInvalidException.php
View File

@@ -5,7 +5,7 @@ namespace UniFi_API\Exceptions;
/** /**
* Thrown when an invalid email address is provided to the client. * Thrown when an invalid email address is provided to the client.
* *
* This is used for input validation where a properly formatted email is required. * @note This Exception is used for input validation where a properly formatted email is required.
* *
* @package UniFi_Controller_API_Client_Class * @package UniFi_Controller_API_Client_Class
*/ */

6
src/Exceptions/InvalidSiteNameException.php
View File

@@ -3,10 +3,10 @@
namespace UniFi_API\Exceptions; namespace UniFi_API\Exceptions;
/** /**
* Thrown when a provided site name is invalid or cannot be used by the client. * Thrown when a provided short site name is invalid or cannot be used by the client.
* *
* This can be raised when the site name contains illegal characters or when * @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. * the name does not correspond to any known site on the controller.
* *
* @package UniFi_Controller_API_Client_Class * @package UniFi_Controller_API_Client_Class
*/ */

4
src/Exceptions/LoginFailedException.php
View File

@@ -5,8 +5,8 @@ namespace UniFi_API\Exceptions;
/** /**
* Thrown when the client fails to authenticate with the UniFi controller. * Thrown when the client fails to authenticate with the UniFi controller.
* *
* This can indicate invalid credentials, connectivity problems, or a change * @note This can indicate invalid credentials, connectivity problems, or a change
* in the controller's authentication mechanism (e.g., MFA). * in the controller's authentication mechanism (e.g., MFA).
* *
* @property-read mixed $httpResponseCode HTTP response code if available * @property-read mixed $httpResponseCode HTTP response code if available
* *

5
src/Exceptions/MethodDeprecatedException.php
View File

@@ -4,8 +4,9 @@ namespace UniFi_API\Exceptions;
/** /**
* Thrown when a library method or API endpoint has been deprecated and should * Thrown when a library method or API endpoint has been deprecated and should
* no longer be used. Consumers can catch this to provide migration guidance * no longer be used.
* or suppress warnings for legacy callers. *
* @note Consumers can catch this to provide migration guidance or suppress warnings for legacy callers.
* *
* @package UniFi_Controller_API_Client_Class * @package UniFi_Controller_API_Client_Class
*/ */

6
src/Exceptions/UnifiApiException.php
View File

@@ -8,9 +8,9 @@ use Throwable;
/** /**
* Base exception for the UniFi API client. * Base exception for the UniFi API client.
* *
* All custom exceptions in this library extend this class so consumers can * @note All custom exceptions in this library extend this class so consumers can
* catch a single type (\UniFi_API\Exceptions\UnifiApiException) when they * catch a single type (\UniFi_API\Exceptions\UnifiApiException) when they
* want to handle all client errors uniformly. * want to handle all client errors uniformly.
* *
* @package UniFi_Controller_API_Client_Class * @package UniFi_Controller_API_Client_Class
*/ */