README

Description

This UISP plugin is a lightweight PHP HTTP client specifically for Ubiquiti's UISP server.

It is designed so you don't have to worry about setting up or paying attention to any of the HTTP mechanism. All you need is to provide the endpoint, the method, and the data.

Requirements

• PHP >= 8.3
• guzzlehttp/guzzle ^7.10
• ocolin/globaltypes ^2.0

Installation

composer require ocolin/uisp

Configuration

Environment Variable Configuration

This plugin was designed to use environment variables for ease of use. You can use .env.example as a template for the variable names:

Instantiation Configuration

The Client constructor can also take an array of optional information including the server URI and authentication token. Here are the optional configuration settings that can be used:

Usage

Concepts

Here are the arguments you need when making an API call:

• endpoint - Copy/paste the end point from your API docs. Any variables in the endpoint will be replaced with variables of the same name in your parameters.
• method - You specify an HTTP methods. This is either done by choosing the method function name, or specifying the method name depending on which function call is used.
• params - These are the variables that are used in the endpoint path and the HTTP body. Any parameters in the path will be removed from the body and used in the endpoint path.
• query - Some HTTP methods like POST/PUT/PATCH may require HTTP query parameters in addition to the HTTP body. You can specify those query parameters with this argument.

Below you can find examples for each scenario.

Output

Most methods will output an object with 4 properties:

The exception to this is the data() function which returns ONLY the HTTP body (See example below).

Instantiation

Using Environment Variables

// Manually creating for demonstration
$_ENV['UISP_API_TOKEN'] = 'myauthtoken';
$_ENV['UISP_API_URL']   = 'https://myserver.com/nms/api/v2.1/';

$client = new Ocolin\UISP\Client();

Setting Options parameters

$options = [
    'base_uri' => 'https://myserver.com/nms/api/v2.1/',
    'token'    => 'myauthtoken',
    'timeout'  => 60
];

$client = new Ocolin\UISP\Client( options: $options );

Method Calls

GET

Get data.

$output = $client->get(
    endpoint: '/devices/{id}',
      params: [ 'id' => 'mydeviceidgoeshere-andreplacespathid']
);

POST

Create data.

$output = $client->post(
    endpoint: '/sites',
      params: [ 'name' => 'My New Site' ]
);

PUT

Update data.

$output = $client->put(
    endpoint: '/sites/{id}',
      params: $site_object, // Object of a site from UISP
       query: [ 'isComposeRequest' => 'true' ]
);

PATCH

Update data.

$output = $client->patch(
    endpoint: '/sites/{id}',
      params: $site_object, // Object of a site from UISP
       query: [ 'isComposeRequest' => 'true' ]
);

DELETE

Delete data.

$output = $client->delete(
    endpoint: '/devices/{id}',
      params: [ 'id' => 'mydeviceidgoeshere-andreplacespathid']
);

REQUEST

Request is a more generic function where you specify the method rather than calling the specific method function.

$output = $client->request(
    endpoint: '/devices/{id}',
      params: [ 'id' => 'mydeviceidgoeshere-andreplacespathid'],
      method: 'GET'
);

DATA

Data is much like the request() function, but it only returns the data. This is for situations where you don't need any of the other data and can assume problems based solely on the response body.

// Output is mixed data type
$output = $client->data(
    endpoint: '/devices/{id}',
      params: [ 'id' => 'mydeviceidgoeshere-andreplacespathid'],
      method: 'GET'
);