Art-of-WiFi UniFi-API-client for PHP Controller Integration

The PHP integration gap addressed by UniFi-API-client

Art-of-WiFi/UniFi-API-client targets applications that must administer or inspect UniFi Network Application deployments from PHP. Without this package, an application would need to construct controller URLs, handle controller-specific authentication, submit HTTP requests through cURL, parse JSON responses, and interpret API errors itself. The package places those responsibilities in a reusable class and exposes dedicated methods for many controller operations.

The intended users are PHP developers integrating reporting, inventory, access-control, monitoring, configuration, and administrative workflows. The repository includes examples for listing sites and alarms, changing WLAN settings, creating vouchers and sites, disabling devices or switch ports, upgrading access-point firmware, and issuing custom API requests. Those examples indicate that the class is intended both for read-oriented integrations and for administrative automation.

The README presents this as a third-party client rather than an official Ubiquiti SDK. It also says the package exposes many controller endpoints not yet available through official APIs. That distinction matters when an adoption depends on stable contracts: controller responses and supported versions must be checked against the deployed UniFi environment rather than inferred from the package name alone.

cURL requests, controller paths, and JSON responses

The documented runtime model is a PHP class backed by PHP cURL and JSON. The client communicates with the UniFi controller or UniFi OS device over TLS, can validate the SSL certificate, and exposes `custom_api_request()` for endpoints that do not have a dedicated wrapper. This makes the package useful when an integration starts with a stable controller operation and later needs an endpoint that the class does not explicitly name.

UniFi OS detection is part of the routing logic. According to the README, the client automatically recognizes UniFi OS consoles and servers, then adjusts URLs and the behavior of several functions. Traditional software-based controllers normally use TCP port 8443. UniFi OS consoles use port 443, while UniFi OS Server requires port 11443. This is more than a cosmetic URL change: supplying the wrong port can prevent the PHP process from reaching the management interface even when credentials are correct.

The repository layout separates the package source under `src/`, API documentation in `API_REFERENCE.md`, and executable examples under `examples/`. The package is not presented as a self-contained single-file class in the current version. That change matters for applications upgrading from a version before 2.0.0, because those installations are directed to use Composer rather than retain the earlier single-file arrangement.

Choosing API key, local account, or Site Manager proxy authentication

The client offers three documented authentication paths. For a UniFi OS environment, an API key generated in the console or UniFi OS Server is the preferred option described by the README. Direct access to the controller process also accepts a local administration account with local API access. That account must have local access permissions, and the documentation explicitly says not to use a UniFi Cloud account or enable MFA/2FA for it.

The third path uses a Site Manager API key and routes requests through Ubiquiti's cloud proxy. This option matters for PHP applications that cannot maintain direct network connectivity to the controller. It should not be confused with using a cloud login against the controller. The project distinguishes those mechanisms, and their deployment prerequisites differ.

Authentication choice also affects the network design. The PHP host needs direct connectivity for local controller requests. A Site Manager configuration adds a dependency on the cloud proxy and the permissions attached to that key. The README does not document token rotation schedules, revocation procedures, or a recovery process for a compromised key, so those operational details must be established elsewhere before relying on unattended API access.

Security-conscious integrations should prefer narrowly scoped credentials and read-only operations while the integration is being established. That is not a documented feature of the class, but it follows from the separation between authentication methods and controller permissions. The project does not claim that the client can bypass controller authorization.

Composer installation and first controller operation

The preferred installation path is Composer. Run the following command in the PHP project's directory. It adds the package declared for `art-of-wifi/unifi-api-client` to the project's Composer dependencies.

composer require art-of-wifi/unifi-api-client

The environment must provide PHP 7.4.0 or later with the cURL and JSON modules enabled. The README links version 1.1.83 for PHP 7.3.x and lower, but that is a separate compatibility route and should not be mixed casually with an application configured for the current package line. The host must also be able to reach the controller's management port.

For a first use, start with the repository's API-key example rather than a device-changing operation. The relevant file is `examples/api_key_auth.php`, and companion configuration begins at `examples/config.template.php`. A successful process should authenticate, connect to the selected site, and return a parsed controller response without a named client exception. Listing sites is a more conservative initial read operation than disabling a device or changing a WLAN password.

The README does not include the contents of those example files, including the constructor arguments and exception sequence. This article therefore does not invent a configuration file or PHP snippet. Manual installation is also mentioned, but the installation section ends before its full instructions, so Composer is the documented method that can be reproduced here without guessing.

Exception changes and upgrade work in 2.3.x

Version 2.3.0 changed the exception type for controller errors. Errors such as `api.err.NoSiteContext` are now thrown as `UniFi_API\Exceptions\ControllerErrorException` instead of a plain `\Exception`. Existing code that catches `\Exception` continues to match, but catch ordering can change behavior. Code that catches `UnifiApiException` before a general `\Exception` block may now consume controller errors in the earlier block.

The same release makes `set_api_key()`, `enable_site_manager_proxy()`, `connect_via_site_manager()`, and `create_dns_record()` throw `UniFi_API\Exceptions\InvalidArgumentException`. This class extends PHP's `\InvalidArgumentException`, preserving compatibility for code that already catches the standard exception. Integrations should still inspect whether any earlier, more specific catch block changes which handler executes.

Upgrading from a version before 2.0.0 requires more work. The README says to adopt the package's new Exceptions, test for breaking changes, and install through Composer because the class is no longer delivered as one file. No migration command, automated test suite, or compatibility table for every PHP framework is documented. An upgrade review should therefore include the application's exception hierarchy and all custom endpoint calls.

The repository is not archived, and its last push was on 2026-10-06. Release v2.3.1 was also published on 2026-10-06, after v2.3.0 on 2026-10-02 and v2.2.1 on 2026-07-27. This is current release activity, although the maintenance assessment should be separated from Ubiquiti's own product support lifecycle.

Supported controllers, network boundaries, and failure cases

The compatibility table covers UniFi Network Application and controller versions 5.x through 10.x, with 10.5.62 identified as confirmed. UniFi OS 3.x through 5.x are listed, with 5.1.26 identified as confirmed. The repository also names several UniFi OS consoles, gateways, hosting options, and controller applications that the README says have been verified.

A version listed as compatible does not remove deployment constraints. The PHP process still needs direct network connectivity for direct authentication. A UniFi OS gateway reached through its WAN interface requires a specific firewall rule. The README links separate instructions for Classic and Zone-Based firewall configurations, which indicates that remote access is not merely a matter of opening a port.

The package is the wrong tool when MFA/2FA is mandatory for the only available account, when a UniFi Cloud login is the sole credential available for direct API use, or when the PHP host cannot reach the required controller port and Site Manager proxying is unsuitable. It is also a poor fit for developers seeking a fully independent Ubiquiti implementation or for management environments that require an official support contract from Ubiquiti.

No documented rollback command appears in the README. Administrative examples include destructive or disruptive operations such as deleting a site, changing passwords, disabling devices, and upgrading firmware. The client can issue these requests, but it does not automatically prove that a completed operation can be reversed. Read endpoints should validate the integration before write operations are enabled.

Direct PHP access versus the Site Manager proxy path

The main practical alternative is to make direct HTTP requests to the UniFi API without using this package. That approach can work when the application already owns controller URL construction, cURL sessions, authentication, JSON decoding, site selection, and error translation. It also avoids taking a dependency on the package's method surface, but it does not remove the need to understand UniFi authentication and controller routing.

The package takes responsibility for a substantial part of that plumbing. It supports the different controller and UniFi OS port conventions, detects UniFi OS systems, exposes many endpoint-specific methods, provides `custom_api_request()` for additional endpoints, and translates failures into named Exceptions. The Site Manager route also provides an option for deployments where the PHP host cannot connect directly to the controller.

The trade-off is a moving compatibility surface between the package and multiple UniFi generations. The README claims broad endpoint coverage, yet it does not enumerate every method or guarantee that every controller release has identical behavior. Direct HTTP code offers maximum control but creates more repeated integration code. This package offers a smaller application-level API but requires upgrades and controller-version verification when controller behavior changes.

Editorial conclusion

Adopt this package when a PHP application needs programmable access to a UniFi Network Application and direct connectivity or Site Manager proxying fits the deployment. Do not choose it for a cloud-only account protected by MFA, a controller exposed solely through an unsupported remote-access arrangement, or code that requires documented rollback procedures. Verify the exact PHP version, controller release, authentication method, controller port, exception handling, and one read operation before enabling device-changing requests. On the stated compatibility boundary, Art-of-WiFi/UniFi-API-client is a practical PHP integration layer for UniFi Network Application 5.x through 10.x, including UniFi OS-based deployments.

Frequently asked questions

Official sources

1. Art-of-WiFi/UniFi-API-client on GitHub
2. Issues
3. License: MIT
4. README
5. Releases