Art-of-WiFi/UniFi-API-client v2.3.0

API client class v2.3.0

on GitHub

The release notes are a bit more more elaborate this time due to the important changes/improvements to the Exception handling logic 😉

Typed exceptions for controller errors and argument validation

This release replaces the last remaining plain \Exception and SPL \InvalidArgumentException throws with typed exceptions, so every error raised by the client can be caught through a single interface and controller error codes can be inspected directly.

New

• ControllerErrorException is thrown when the controller accepts a request but returns an error in its response body. This covers the classic API (meta.rc = 'error'), v2 API endpoints (errorCode) and UniFi OS endpoints (code). It extends UnifiApiException and exposes:
  • getApiErrorCode() returns the controller's error code, e.g. api.err.UnknownDevice
  • getResponse() returns the full decoded response object
• UnifiApiExceptionInterface is a marker interface implemented by every exception the client throws. Catch it to handle all client errors uniformly.
• UniFi_API\Exceptions\InvalidArgumentException extends PHP's \InvalidArgumentException and implements the interface. It is thrown by set_api_key(), enable_site_manager_proxy(), connect_via_site_manager() and create_dns_record(). Existing catch (\InvalidArgumentException $e) blocks continue to work.
• getHttpResponseCode() is now available on the UnifiApiException base class. It returns the HTTP status code for cURL and login errors and 0 otherwise.

Improved

• Around 200 @throws Exception DocBlocks now read @throws UnifiApiException, which improves IDE and static analysis support.
• The UniFi OS console methods and fetch_results() now document the specific exceptions they can raise.
• README.md and API_REFERENCE.md gained a full table of all exceptions and when each is thrown.
• The list_alarms.php, api_key_auth.php and site_manager_proxy_stats.php examples show the new catch patterns.

Behaviour change

Controller-side errors were previously thrown as a plain \Exception. They are now a ControllerErrorException, which is a subclass of both UnifiApiException and \Exception.

• Code that catches \Exception or \Throwable is not affected.
• Code that catches UnifiApiException first and relies on controller errors falling through to a later catch (\Exception $e) block will now see them in the UnifiApiException block.
• Exception messages are unchanged.

See the Upgrading from previous versions and Exception handling sections of the README for details.

Testing

Verified against a classic controller (10.x on port 8443) and a UniFi OS console (UDM-PRO) reached through the Site Manager proxy.