will/unifi-api-client
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Initial release of the Unifi API Client

Browse Source
This commit is contained in:
Joris van de Sande 2015-08-09 21:06:47 +02:00
commit 8ce264b2a0
11 changed files with 494 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored Normal file
View File

@ -0,0 +1,4 @@
.idea
/examples/config.php
/composer.lock
/vendor

19
LICENSE Normal file
View File

@ -0,0 +1,19 @@
Copyright (c) 2015 Joris van de Sande, https://github.com/jorisvandesande
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

54
README.md Normal file
View File

@ -0,0 +1,54 @@
Unifi API Client
================
Unifi API Client can be used to connect to the API of your [Ubiquiti Unifi Controller](https://www.ubnt.com/enterprise/software/).
This client is build on top of [Guzzle](http://guzzlephp.org/).
The code is tested against Unifi Controller version 4.6.6.
Installation
------------
The API client can be installed with [Composer](https://getcomposer.org/):
composer require jorisvandesande/unifi-api-client
Or you can download the latest release at:
https://github.com/jorisvandesande/unifi-api-client/releases
Usage
-----
```php
use JVDS\UnifiApiClient\Client;
use GuzzleHttp\Client as HttpClient;
$apiClient = new Client(new HttpClient(['base_uri' => 'https://127.0.0.1:8443']));
$apiClient->login('your_username', 'your_password');
// call supported methods via methods on the client
$apiClient->statistics('default');
// or call any API url via the get and post methods:
$apiClient->get('/api/self');
$apiClient->post('/api/s/default/cmd/stamgr', ['cmd' => 'block-sta', 'mac':'01:01:01:01:01:01'])
// logout
$apiClient->login('your_username', 'your_password');
```
Examples can be found in the [examples](examples) directory. To run the examples, you must
copy the config.example.php file to config.php and change the configuration to your needs.
Supported API calls
-------------------
At the moment only a few API methods are implemented in the Client. Altough it is possible to use
the ```get()``` and ```post()``` methods of the Client to call any API url, the goal is to
support more methods.
License
-------
MIT Licensed, see the [LICENSE](LICENSE) file.

32
composer.json Normal file
View File

@ -0,0 +1,32 @@
{
"name": "jorisvandesande/unifi-api-client",
"type": "library",
"description": "Unifi API Client can be used to connect to the API of your Ubiquiti Unifi Controller",
"keywords": ["unifi", "ubiquiti", "api client", "api", "unifi controller", "client"],
"homepage": "https://github.com/jorisvandesande/unifi-api-client",
"license": "MIT",
"authors": [
{
"name": "Joris van de Sande",
"email": "joris@vandesande.link",
"homepage": "https://github.com/jorisvandesande"
}
],
"require": {
"php": ">=5.5.0",
"guzzlehttp/guzzle": "~6.0"
},
"autoload": {
"psr-4": {
"JVDS\\UnifiApiClient\\": "src/"
}
},
"extra": {
"branch-alias": {
"dev-master": "1.0-dev"
}
},
"archive": {
"exclude": ["/examples"]
}
}

28
examples/README.md Normal file
View File

@ -0,0 +1,28 @@
Examples
========
To run the examples, you must copy the config.example.php file to config.php
and change the configuration to your needs.
statistics.php
--------------
Fetches the client statistics for a given site.
php statistics.php
authorize-guest.php
-------------------
Authorizes a guest (mac address) for x minutes.
You need to login with a user that has full access to the Unifi controller.
php authorize-guest.php
unauthorize-guest.php
---------------------
Unauthorize a guest (mac address).
You need to login with a user that has full access to the Unifi controller.
php unauthorize-guest.php

35
examples/authorize-guest.php Normal file
View File

@ -0,0 +1,35 @@
<?php
require __DIR__ . '/../vendor/autoload.php';
$config = require 'config.php';
use JVDS\UnifiApiClient\Client;
use GuzzleHttp\Client as HttpClient;
use GuzzleHttp\Exception\RequestException;
$apiClient = new Client(new HttpClient(['base_uri' => $config['base_uri']]));
try {
// login to the unifi controller API
$apiClient->login($config['username'], $config['password']);
// Authorize guest with mac address 01:01:01:01:01:01 for 60 minutes
// You need a user with full access to the unifi controller for this call!
$responseBody = $apiClient->authorizeGuest($config['site'], '01:01:01:01:01:01', 60);
print_r(json_decode($responseBody));
$apiClient->logout();
} catch (RequestException $e) {
echo $e->getMessage() . PHP_EOL;
echo '----- Request ------' . PHP_EOL;
echo $e->getRequest()->getBody()->getContents();
echo PHP_EOL;
echo '----- Response ------' . PHP_EOL;
echo $e->hasResponse() ? $e->getResponse()->getBody()->getContents() : '- no response -';
echo PHP_EOL;
}

11
examples/config.example.php Normal file
View File

@ -0,0 +1,11 @@
<?php
return [
// The base uri of your Unifi controller
'base_uri' => 'https://127.0.0.1:8443',
// Your username (You should create a user with read only access to the Unifi controller)
'username' => '',
// Your password
'password' => '',
// The site name to run the examples against
'site' => 'default'
];

37
examples/device-statistics.php Normal file
View File

@ -0,0 +1,37 @@
<?php
require __DIR__ . '/../vendor/autoload.php';
$config = require 'config.php';
use JVDS\UnifiApiClient\Client;
use GuzzleHttp\Client as HttpClient;
use GuzzleHttp\Exception\RequestException;
$apiClient = new Client(new HttpClient(['base_uri' => $config['base_uri']]));
try {
// login to the unifi controller API
$apiClient->login($config['username'], $config['password']);
// Fetch device statistics for the given site
$responseBody = $apiClient
->deviceStatistics($config['site'])
->getBody()
->getContents();
print_r(json_decode($responseBody, true));
$apiClient->logout();
} catch (RequestException $e) {
echo $e->getMessage() . PHP_EOL;
echo '----- Request ------' . PHP_EOL;
echo $e->getRequest()->getBody()->getContents();
echo PHP_EOL;
echo '----- Response ------' . PHP_EOL;
echo $e->hasResponse() ? $e->getResponse()->getBody()->getContents() : '- no response -';
echo PHP_EOL;
}

37
examples/statistics.php Normal file
View File

@ -0,0 +1,37 @@
<?php
require __DIR__ . '/../vendor/autoload.php';
$config = require 'config.php';
use JVDS\UnifiApiClient\Client;
use GuzzleHttp\Client as HttpClient;
use GuzzleHttp\Exception\RequestException;
$apiClient = new Client(new HttpClient(['base_uri' => $config['base_uri']]));
try {
// login to the unifi controller API
$apiClient->login($config['username'], $config['password']);
// Fetch statistics for the given site
$responseBody = $apiClient
->statistics($config['site'])
->getBody()
->getContents();
print_r(json_decode($responseBody));
$apiClient->logout();
} catch (RequestException $e) {
echo $e->getMessage() . PHP_EOL;
echo '----- Request ------' . PHP_EOL;
echo $e->getRequest()->getBody()->getContents();
echo PHP_EOL;
echo '----- Response ------' . PHP_EOL;
echo $e->hasResponse() ? $e->getResponse()->getBody()->getContents() : '- no response -';
echo PHP_EOL;
}

35
examples/unauthorize-guest.php Normal file
View File

@ -0,0 +1,35 @@
<?php
require __DIR__ . '/../vendor/autoload.php';
$config = require 'config.php';
use JVDS\UnifiApiClient\Client;
use GuzzleHttp\Client as HttpClient;
use GuzzleHttp\Exception\RequestException;
$apiClient = new Client(new HttpClient(['base_uri' => $config['base_uri']]));
try {
// login to the unifi controller API
$apiClient->login($config['username'], $config['password']);
// Revoke authorization for guest with mac address 01:01:01:01:01:01
// You need a user with full access to the unifi controller for this call!
$responseBody = $apiClient->unauthorizeGuest($config['site'], '01:01:01:01:01:01');
print_r(json_decode($responseBody));
$apiClient->logout();
} catch (RequestException $e) {
echo $e->getMessage() . PHP_EOL;
echo '----- Request ------' . PHP_EOL;
echo $e->getRequest()->getBody()->getContents();
echo PHP_EOL;
echo '----- Response ------' . PHP_EOL;
echo $e->hasResponse() ? $e->getResponse()->getBody()->getContents() : '- no response -';
echo PHP_EOL;
}

202
src/Client.php Normal file
View File

@ -0,0 +1,202 @@
<?php
namespace JVDS\UnifiApiClient;
use GuzzleHttp\ClientInterface;
use GuzzleHttp\Cookie\CookieJar;
use GuzzleHttp\Exception\GuzzleException;
use Psr\Http\Message\ResponseInterface;
/**
* Unifi controller API client.
*
* Example usage:
* <code>
* use JVDS\UnifiApiClient\Client;
* use GuzzleHttp\Client as HttpClient;
*
* $apiClient = new Client(new HttpClient(['base_uri' => 'https://127.0.0.1:8443']));
* $apiClient->login('your_username', 'your_password');
* $apiClient->statistics('default'); // fetch statistics for default site
* </code>
*
* Unifi controllers come with a self signed certificate by default.
* To verify that you're connecting to your own unifi controller,
* you should download your controller's certificate.
* And the verify option should be set to the path of the downloaded certificate:
*
* <code>
* use JVDS\UnifiApiClient\Client;
* use GuzzleHttp\Client as HttpClient;
*
* $apiClient = new Client(
* new HttpClient(['base_uri' => 'https://127.0.0.1:8443']),
* ['verify' => '/your/unifi/cert.pem']
* );
* $apiClient->login('your_username', 'your_password');
* </code>
*
* It is also possible to use your own certificate in the unifi controller.
* More information about this is available at: http://wiki.ubnt.com/UniFi_FAQ#Custom_SSL_certificate
*
* @author Joris van de Sande
*/
class Client
{
/**
* @var ClientInterface|null
*/
private $client;
/**
* @var array
*/
private $requestOptions;
/**
* @param ClientInterface $client
* @param array $requestOptions Guzzle request options that will be sent with every request
*
* @link http://docs.guzzlephp.org/en/latest/request-options.html
*/
public function __construct(ClientInterface $client, array $requestOptions = [])
{
$this->client = $client;
$this->requestOptions = $this->getRequestOptions($requestOptions);
}
/**
* Login to the Unifi controller.
* You need to login before you can make other api requests.
*
* @param string $username username
* @param string $password password
*
* @throws GuzzleException in case of a login failure.
*/
public function login($username, $password)
{
$this->post(
'/api/login',
['username' => $username, 'password' => $password, 'strict' => true]
);
}
/**
* @throws GuzzleException in case of a failure.
*/
public function logout()
{
$this->client->request('get', '/logout', ['allow_redirects' => false] + $this->requestOptions);
}
/**
* @param string $site
*
* @return ResponseInterface
* @throws GuzzleException
*/
public function statistics($site)
{
return $this->get('/api/s/' . $site . '/stat/sta');
}
/**
* @param string $site
*
* @return ResponseInterface
* @throws GuzzleException
*/
public function deviceStatistics($site)
{
return $this->get('/api/s/' . $site. '/stat/device');
}
/**
* Authorize a guest by mac address.
*
* @param string $site
* @param string $mac the mac address of the guest to authorize.
* @param int $minutes number of minutes to authorize guest.
* @param array $data associative array with extra data, i.e. up (kbps), down (kbps), bytes (MB)
*
* @return ResponseInterface
* @throws GuzzleException
*/
public function authorizeGuest($site, $mac, $minutes, array $data = [])
{
return $this->post(
'/api/s/' . $site . '/cmd/stamgr',
[
'cmd' => 'authorize-guest',
'mac' => $mac,
'minutes' => $minutes
] + $data
);
}
/**
* Unauthorize a guest by mac address.
*
* @param string $site
* @param string $mac
*
* @return ResponseInterface
*/
public function unauthorizeGuest($site, $mac)
{
return $this->post(
'/api/s/' . $site . '/cmd/stamgr',
[
'cmd' => 'unauthorize-guest',
'mac' => $mac
]
);
}
/**
* @param string $url (relative) url to the api endpoint
* @param array $data data to be sent with the request.
*
* @return ResponseInterface
* @throws GuzzleException
*/
public function post($url, array $data = [])
{
return $this->client->request(
'post',
$url,
['json' => $data] + $this->requestOptions
);
}
/**
* @param string $url
* @param array $data
*
* @return ResponseInterface
* @throws GuzzleException
*/
public function get($url, array $data = [])
{
$requestOptions = $this->requestOptions;
if ($data) {
$requestOptions['query'] = $data;
}
return $this->client->request('get', $url, $requestOptions);
}
private function getRequestOptions(array $defaultRequestOptions)
{
return array_merge(
[
'cookies' => new CookieJar(),
'verify' => false
],
$defaultRequestOptions
);
}
}