README

A ReactPHP-based client library for the Ubiquiti UISP (formerly UNMS) API.

Installation

composer require skydiablo/reactphp-uisp-api-client

Features

• Asynchronous API client built on ReactPHP v3
• Domain-driven design approach with Dependency Injection support
• Support for various UISP API domains:
  • Devices
  • Networks
  • Clients
  • Billing
  • Sites
• Type-safe API parameters using PHP Enums
• Comprehensive test suite with PHPUnit

Basic Usage

<?php

require 'vendor/autoload.php';

use React\Http\Browser;
use SkyDiablo\UispApiClient\Client\UispClient;
use SkyDiablo\UispApiClient\Services\Devices\DevicesService;
use SkyDiablo\UispApiClient\Services\Devices\Parameters\ListDevicesParameters;
use SkyDiablo\UispApiClient\Services\Devices\Parameters\DeviceType;
use SkyDiablo\UispApiClient\Services\Devices\Parameters\DeviceRole;
use SkyDiablo\UispApiClient\Services\Sites\Parameters\ListSitesParameters;
use SkyDiablo\UispApiClient\Services\Sites\SitesService;

// Method 1: Manual creation (for Dependency Injection)
$browser = new Browser(); // Optional
$client = new UispClient(
    'https://your-uisp-instance.example.com',
    'your-api-key',
    $browser // Optional: You can omit this parameter
);

// Create domain services
$devicesService = new DevicesService($client);
$sitesService = new SitesService($client);

// Method 2: Using the factory method (for simpler usage)
// $client = UispClient::create(
//     'https://your-uisp-instance.example.com',
//     'your-api-key'
// );
// $devicesService = new DevicesService($client);
// $sitesService = new SitesService($client);

// Example: Get all devices
$devicesService->list()->then(
    function ($devices) {
        // Handle devices
        var_dump($devices);
    },
    function ($error) {
        // Handle error
        echo "Error: " . $error->getMessage() . PHP_EOL;
    }
);

// Example: Filter devices by type and role
$deviceParams = new ListDevicesParameters();
$deviceParams->setType([DeviceType::ROUTER, DeviceType::WIRELESS])
             ->setRole([DeviceRole::CPE]);

$devicesService->list($deviceParams)->then(
    function ($devices) {
        echo "Found " . count($devices) . " devices matching the criteria" . PHP_EOL;
    }
);

// Example: List sites with parameter filtering

// Get all sites
$sitesService->list()->then(
    function ($sites) {
        echo "Total sites: " . count($sites) . PHP_EOL;
    }
);

// Filter sites by type
$siteParams = new ListSitesParameters();
$siteParams->setType('customer')
           ->setUcrmDetails(true);

$sitesService->list($siteParams)->then(
    function ($sites) {
        echo "Customer sites with CRM details: " . count($sites) . PHP_EOL;
    }
);

// Run the event loop (ReactPHP will automatically use the global Loop instance)
\React\EventLoop\Loop::run();

Tests

Unit Tests

Run the unit tests:

./vendor/bin/phpunit

Integration Tests

The integration tests require a running UISP instance and valid API credentials. Before running the integration tests:

1. Copy phpunit.integration.xml.dist to phpunit.integration.xml
2. Update the environment variables in phpunit.integration.xml with your UISP API credentials:
   • UISP_API_URL: The URL of your UISP instance
   • UISP_API_TOKEN: Your UISP API token

Then run the integration tests:

./vendor/bin/phpunit -c phpunit.integration.xml

Documentation

• API Reference - Detailed documentation of classes and methods
• Usage Guide - Examples and usage patterns
• Error Handling - Guide to handling errors and exceptions
• Dependency Injection - Using the library with DI frameworks
• Logging - Configuring and using logging
• Framework Integration - Integrating with Laravel, Symfony, and Slim
• ReactPHP Usage - Advanced usage with ReactPHP
• Contributing Guide - Guidelines for contributing to the project
• UISP API-Docs - Official UISP API documentation and reference

License

MIT