jeroen/unifi-php-api
1
0
Fork 0
mirror of https://github.com/Art-of-WiFi/UniFi-API-client.git synced 2024-11-21 17:49:59 +01:00
Code Issues Packages Projects Releases Wiki Activity

API client class v1.1.47

Browse Source 
- applied patches to update_switch_poe-mode.php as suggested by scrutinizer-ci.com
- code clean up and improvements in preparation of support for UniFi OS-based controllers
- added support for UniFi OS-based controllers, thanks to @Scyto for providing access
- adapt login route and method, and base URL for UniFi OS-based controllers
- automatically identify UniFi OS-based controllers, thanks to @TwitchCaptain for this and several other suggestions
- relaxed URL validation to allow UniFi OS-based controllers to pass
- changed default HTTP method to GET
- many improvements throughout the code
This commit is contained in:
malle-pietje 2020-02-06 08:52:49 +01:00
parent 961d692125
commit 17d895076f
3 changed files with 206 additions and 144 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -1,8 +1,8 @@
## UniFi Controller API client class
A PHP class which provides access to Ubiquiti's [**UniFi SDN Controller**](https://unifi-sdn.ui.com/) API, versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.12.35 has been confirmed to work). It's a standalone version of the class which is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
A PHP class that provides access to Ubiquiti's [**UniFi SDN Controller**](https://unifi-sdn.ui.com/) API, versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.12.35 has been confirmed to work) as well as UniFi OS-based controllers (version 5.12.59 has been confirmed to work). This class is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
This class can be installed manually or using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
The package can be installed manually or using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
## Requirements
@ -11,7 +11,9 @@ This class can be installed manually or using composer/[packagist](https://packa
## UniFi OS Support
Currently, UniFi OS-based controllers (UniFi Dream Machine Pro) are **not supported** due to several breaking changes to the API.
Support for UniFi OS-based controllers (UniFi Dream Machine Pro) has been added as of version 1.1.47. The class automatically detects UniFi OS devices and adjusts URLs and several functions/methods accordingly. If your own code applies strict validation of the URL that is passed to the constructor, please adapt your logic to allow URLs without a port suffix when dealing with a UniFi OS-based controller.
Please test all methods you plan on using thoroughly before using the API Client with UniFi OS devices in a production environment.
## Installation

5
examples/config.template.php
View File

@ -15,8 +15,9 @@
*/
$controlleruser = ''; // the user name for access to the UniFi Controller
$controllerpassword = ''; // the password for access to the UniFi Controller
$controllerurl = ''; // full url to the UniFi Controller, eg. 'https://22.22.11.11:8443'
$controllerversion = ''; // the version of the Controller software, eg. '4.6.6' (must be at least 4.0.0)
$controllerurl = ''; // full url to the UniFi Controller, eg. 'https://22.22.11.11:8443', for UniFi OS-based
// controllers a port suffix isn't required, no trailing slashes should be added
$controllerversion = ''; // the version of the Controller software, e.g. '4.6.6' (must be at least 4.0.0)
/**
* set to true (without quotes) to enable debug output to the browser and the PHP error log

337
src/Client.php
View File

@ -2,7 +2,7 @@
/**
* This file is part of the art-of-wifi/unifi-api-client package
*
* This UniFi API client is based on the work done by the following developers:
* This UniFi API client Class is based on the work done by the following developers:
* domwo: http://community.ubnt.com/t5/UniFi-Wireless/little-php-class-for-unifi-api/m-p/603051
* fbagnol: https://github.com/fbagnol/class.unifi.php
* and the API as published by Ubiquiti:
@ -17,41 +17,44 @@
namespace UniFi_API;
/**
* the UniFi API client class
* the UniFi API client Class
*/
class Client
{
/**
* private properties
* private and protected properties
*/
protected $baseurl = 'https://127.0.0.1:8443';
protected $user = '';
protected $password = '';
protected $site = 'default';
protected $version = '5.6.39';
protected $debug = false;
protected $is_loggedin = false;
private $cookies = '';
private $request_type = 'GET';
private $connect_timeout = 10;
private $last_results_raw = null;
private $last_error_message = null;
private $curl_ssl_verify_peer = false;
private $curl_ssl_verify_host = false;
private $is_unifi_os = false;
protected $baseurl = 'https://127.0.0.1:8443';
protected $user = '';
protected $password = '';
protected $site = 'default';
protected $version = '5.6.39';
protected $debug = false;
protected $is_loggedin = false;
protected $is_unifi_os = false;
private $cookies = '';
private $request_type = 'GET';
private $request_types_allowed = ['GET', 'POST', 'PUT', 'DELETE'];
private $connect_timeout = 10;
private $last_results_raw = null;
private $last_error_message = null;
private $curl_ssl_verify_peer = false;
private $curl_ssl_verify_host = false;
/**
* Construct an instance of the UniFi API client class
* Construct an instance of the UniFi API client Class
* ---------------------------------------------------
* return a new class instance
* required parameter <user> = string; user name to use when connecting to the UniFi controller
* required parameter <password> = string; password to use when connecting to the UniFi controller
* optional parameter <baseurl> = string; base URL of the UniFi controller, *must* include "https://" prefix and port suffix (:8443)
* optional parameter <baseurl> = string; base URL of the UniFi controller which *must* include "https://" prefix,
* a port suffix (e.g. :8443) is required for non-UniFi OS controllers,
* do not add trailing slashes
* optional parameter <site> = string; short site name to access, defaults to "default"
* optional parameter <version> = string; the version number of the controller, defaults to "5.4.16"
* optional parameter <ssl_verify> = boolean; whether to validate the controller's SSL certificate or not, a value of true is
* recommended for production environments to prevent potential MitM attacks, default value (false)
* is to not validate the controller certificate
* disables validation of the controller certificate
*/
public function __construct($user, $password, $baseurl = '', $site = '', $version = '', $ssl_verify = false)
{
@ -82,20 +85,20 @@ class Client
$this->check_base_url();
$this->check_site($this->site);
$this->update_unificookie();
/**
* if we have a JWT as our cookie we know we have a UniFi OS controller,
* saves us from requiring a login
*/
if ($this->cookies !== '' && strpos($this->cookies, 'TOKEN') !== false) {
$this->is_unifi_os = true;
}
}
/**
* This method is be called as soon as there are no other references to the Class instance
* https://www.php.net/manual/en/language.oop5.decon.php
*
* NOTES:
* to force the Class instance to log out automatically upon destruct, simply call logout() or unset
* $_SESSION['unificookie'] at the end of your code
*/
public function __destruct()
{
/**
* if user has $_SESSION['unificookie'] set, do not logout here
* if $_SESSION['unificookie'] is set, do not logout here
*/
if (isset($_SESSION['unificookie'])) {
return;
@ -110,17 +113,17 @@ class Client
}
/**
* Login to UniFi Controller
* -------------------------
* Login to the UniFi controller
* -----------------------------
* returns true upon success
*/
public function login()
{
/**
* if $_SESSION['unificookie'] is set, skip the login
* if already logged in we skip the login process
*/
if (isset($_SESSION['unificookie'])) {
return $this->is_loggedin = true;
if ($this->is_loggedin === true) {
return true;
}
/**
@ -129,7 +132,9 @@ class Client
if (!is_resource($ch = $this->get_curl_resource())) {
trigger_error('$ch as returned by get_curl_resource() is not a resource');
} else {
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_NOBODY, true);
curl_setopt($ch, CURLOPT_URL, $this->baseurl . '/');
/**
@ -145,12 +150,6 @@ class Client
if ($http_code === 200) {
$this->is_unifi_os = true;
}
}
if (!is_resource($ch = $this->get_curl_resource())) {
trigger_error('$ch as returned by get_curl_resource() is not a resource');
} else {
curl_setopt($ch, CURLOPT_HEADER, 1);
if ($this->is_unifi_os) {
curl_setopt($ch, CURLOPT_REFERER, $this->baseurl . '/login');
@ -160,6 +159,7 @@ class Client
curl_setopt($ch, CURLOPT_URL, $this->baseurl . '/api/login');
}
curl_setopt($ch, CURLOPT_NOBODY, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['username' => $this->user, 'password' => $this->password]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['content-type: application/json; charset=utf-8']);
@ -188,7 +188,7 @@ class Client
* extract the cookie from the headers
*/
if ($http_code === 400) {
trigger_error('We have received an HTTP response status: 400. Probably a controller login failure');
trigger_error('We received an HTTP response status: 400. Probably a controller login failure');
return $http_code;
}
@ -218,8 +218,8 @@ class Client
}
/**
* Logout from UniFi Controller
* ----------------------------
* Logout from the UniFi controller
* --------------------------------
* returns true upon success
*/
public function logout()
@ -228,47 +228,18 @@ class Client
return false;
}
if (!is_resource($ch = $this->get_curl_resource())) {
trigger_error('$ch as returned by get_curl_resource() is not a resource');
if ($this->is_unifi_os) {
$logout_url = '/api/auth/logout';
} else {
curl_setopt($ch, CURLOPT_HEADER, 1);
if ($this->is_unifi_os) {
curl_setopt($ch, CURLOPT_URL, $this->baseurl . '/api/auth/logout');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
} else {
curl_setopt($ch, CURLOPT_URL, $this->baseurl . '/logout');
}
/**
* execute the cURL request and get the HTTP response code
*/
$content = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch)) {
trigger_error('cURL error: ' . curl_error($ch));
}
if ($this->debug) {
print PHP_EOL . '<pre>';
print PHP_EOL . '-----------LOGOUT-------------' . PHP_EOL;
print_r(curl_getinfo($ch));
print PHP_EOL . '----------RESPONSE-----------' . PHP_EOL;
print $content;
print PHP_EOL . '-----------------------------' . PHP_EOL;
print '</pre>' . PHP_EOL;
}
$this->is_loggedin = false;
$this->cookies = '';
return true;
$logout_url = '/logout';
}
return false;
$this->exec_curl($logout_url, []);
$this->is_loggedin = false;
$this->cookies = '';
return true;
}
/****************************************************************
@ -397,7 +368,8 @@ class Client
* required parameter <macs> = array of client MAC addresses
*
* NOTE:
* only supported with controller versions 5.9.X and higher
* only supported with controller versions 5.9.X and higher, can be
* slow (up to 5 minutes) on larger controllers
*/
public function forget_sta($macs)
{
@ -428,7 +400,6 @@ class Client
return false;
}
$this->request_type = 'POST';
$new_user = ['mac' => strtolower($mac), 'usergroup_id' => $user_group_id];
if (!is_null($name)) {
$new_user['name'] = $name;
@ -1171,9 +1142,8 @@ class Client
return false;
}
$this->request_type = 'POST';
$payload = ['name' => $group_name, 'qos_rate_max_down' => intval($group_dn), 'qos_rate_max_up' => intval($group_up)];
$response = $this->exec_curl('/api/s/' . $this->site . '/rest/usergroup', $payload);
$payload = ['name' => $group_name, 'qos_rate_max_down' => intval($group_dn), 'qos_rate_max_up' => intval($group_up)];
$response = $this->exec_curl('/api/s/' . $this->site . '/rest/usergroup', $payload);
return $this->process_response($response);
}
@ -1262,7 +1232,6 @@ class Client
return false;
}
$this->request_type = 'POST';
$payload = ['name' => $group_name, 'group_type' => $group_type, 'group_members' => $group_members];
$response = $this->exec_curl('/api/s/' . $this->site . '/rest/firewallgroup', $payload);
@ -1843,12 +1812,8 @@ class Client
* restart devices, default value is false. With versions < 5.9.X this only applies
* when readonly is true.
*/
public function assign_existing_admin(
$admin_id,
$readonly = false,
$device_adopt = false,
$device_restart = false
) {
public function assign_existing_admin($admin_id, $readonly = false, $device_adopt = false, $device_restart = false)
{
if (!$this->is_loggedin) {
return false;
}
@ -2009,8 +1974,7 @@ class Client
return false;
}
$this->request_type = 'POST';
$payload = ['name' => $name, 'x_password' => $x_password];
$payload = ['name' => $name, 'x_password' => $x_password];
if (isset($note)) {
$payload['note'] = trim($note);
}
@ -2530,23 +2494,23 @@ class Client
* Assign access point to another WLAN group
* -----------------------------------------
* return true on success
* required parameter <wlantype_id> = string; WLAN type, can be either 'ng' (for WLANs 2G (11n/b/g)) or 'na' (WLANs 5G (11n/a/ac))
* required parameter <device_id> = string; _id value of the access point to be modified
* required parameter <wlangroup_id> = string; _id value of the WLAN group to assign device to
* required parameter <type_id> = string; WLAN type, can be either 'ng' (for WLANs 2G (11n/b/g)) or 'na' (WLANs 5G (11n/a/ac))
* required parameter <device_id> = string; _id value of the access point to be modified
* required parameter <group_id> = string; _id value of the WLAN group to assign device to
*/
public function set_ap_wlangroup($wlantype_id, $device_id, $wlangroup_id)
public function set_ap_wlangroup($type_id, $device_id, $group_id)
{
if (!$this->is_loggedin) {
return false;
}
if (!in_array($wlantype_id, ['ng', 'na'])) {
if (!in_array($type_id, ['ng', 'na'])) {
return false;
}
$payload = [
'wlan_overrides' => [],
'wlangroup_id_' . $wlantype_id => $wlangroup_id
'wlan_overrides' => [],
'wlangroup_id_' . $type_id => $group_id
];
$response = $this->exec_curl('/api/s/' . $this->site . '/upd/device/' . trim($device_id), $payload);
@ -2580,7 +2544,8 @@ class Client
$expire_number,
$expire_unit,
$section_id
) {
)
{
if (!$this->is_loggedin) {
return false;
}
@ -2784,8 +2749,7 @@ class Client
return false;
}
$this->request_type = 'POST';
$response = $this->exec_curl('/api/s/' . $this->site . '/rest/networkconf', $payload);
$response = $this->exec_curl('/api/s/' . $this->site . '/rest/networkconf', $payload);
return $this->process_response($response);
}
@ -2885,7 +2849,8 @@ class Client
$uapsd_enabled = false,
$schedule_enabled = false,
$schedule = []
) {
)
{
if (!$this->is_loggedin) {
return false;
}
@ -3104,8 +3069,7 @@ class Client
return false;
}
$this->request_type = 'POST';
$payload = ['cmd' => 'archive-all-alarms'];
$payload = ['cmd' => 'archive-all-alarms'];
if (!is_null($alarm_id)) {
$payload = ['_id' => $alarm_id, 'cmd' => 'archive-alarm'];
}
@ -3365,7 +3329,6 @@ class Client
return false;
}
$this->request_type = 'POST';
$payload = [
'name' => $name,
'x_password' => $x_password,
@ -3571,6 +3534,10 @@ class Client
return false;
}
if (!in_array($request_type, $this->request_types_allowed)) {
return false;
}
$this->request_type = $request_type;
$response = $this->exec_curl($path, $payload);
@ -3649,7 +3616,7 @@ class Client
* --------------------
* returns the raw results of the last method called, returns false if unavailable
* optional parameter <return_json> = boolean; true will return the results in "pretty printed" json format,
* PHP stdClass Object format is returned by default
* false returns PHP stdClass Object format (default)
*/
public function get_last_results_raw($return_json = false)
{
@ -3679,15 +3646,17 @@ class Client
}
/**
* Get Cookie from UniFi Controller
* Get Cookie from UniFi controller
* --------------------------------
* returns the UniFi controller cookie
*
* NOTES:
* - when the results from this method are stored in $_SESSION['unificookie'], the class will initially not
* - when the results from this method are stored in $_SESSION['unificookie'], the Class will initially not
* log in to the controller when a subsequent request is made using a new instance. This speeds up the
* overall request considerably. If that subsequent request fails (e.g. cookies have expired), a new login
* is executed automatically and the value of $_SESSION['unificookie'] is updated.
* overall request considerably. Only when a subsequent request fails (e.g. cookies have expired) is a new login
* executed and the value of $_SESSION['unificookie'] updated.
* - to force the Class instance to log out automatically upon destruct, simply call logout() or unset
* $_SESSION['unificookie'] at the end of your code
*/
public function get_cookie()
{
@ -3728,7 +3697,14 @@ class Client
public function set_request_type($request_type)
{
if (!in_array($request_type, $this->request_types_allowed)) {
return false;
}
$this->request_type = $request_type;
return true;
}
public function set_connection_timeout($timeout)
@ -3746,17 +3722,34 @@ class Client
$this->last_error_message = $last_error_message;
}
/**
* set the value for cURL option CURLOPT_SSL_VERIFYPEER, should be 0/false or 1/true
* https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html
*/
public function set_ssl_verify_peer($ssl_verify_peer)
{
if (!in_array($ssl_verify_peer, [0, false, 1, true])) {
return false;
}
$this->curl_ssl_verify_peer = $ssl_verify_peer;
return true;
}
/**
* set the value for cURL option CURLOPT_SSL_VERIFYHOST, should be 0/false or 2
* https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html
*/
public function set_ssl_verify_host($ssl_verify_host)
{
if (!in_array($ssl_verify_host, [0, false, 2])) {
return false;
}
$this->curl_ssl_verify_host = $ssl_verify_host;
return true;
}
/****************************************************************
@ -3841,13 +3834,13 @@ class Client
$error = 'The maximum stack depth has been exceeded';
break;
case JSON_ERROR_STATE_MISMATCH:
$error = 'Invalid or malformed JSON.';
$error = 'Invalid or malformed JSON';
break;
case JSON_ERROR_CTRL_CHAR:
$error = 'Control character error, possibly incorrectly encoded';
break;
case JSON_ERROR_SYNTAX:
$error = 'Syntax error, malformed JSON.';
$error = 'Syntax error, malformed JSON';
break;
case JSON_ERROR_UTF8:
// PHP >= 5.3.3
@ -3874,7 +3867,7 @@ class Client
break;
default:
// we have an unknown error
$error = 'Unknown JSON error occured.';
$error = 'Unknown JSON error occured';
break;
}
@ -3909,8 +3902,12 @@ class Client
private function check_site($site)
{
if ($this->debug && preg_match("/\s/", $site)) {
error_log('The provided (short) site name may not contain spaces');
trigger_error('The provided (short) site name may not contain any spaces');
return false;
}
return true;
}
/**
@ -3918,20 +3915,62 @@ class Client
*/
private function update_unificookie()
{
if (isset($_SESSION['unificookie'])) {
if (isset($_SESSION['unificookie']) && !empty($_SESSION['unificookie'])) {
$this->cookies = $_SESSION['unificookie'];
$this->is_loggedin = true;
/**
* if we have a JWT in our cookie we know we're dealing with a UniFi OS controller
*/
if (strpos($this->cookies, 'TOKEN') !== false) {
$this->is_unifi_os = true;
}
return true;
}
return false;
}
/**
* Extract the CSRF token from our Cookie string
*/
private function extract_csrf_token_from_cookie()
{
if ($this->cookies !== '') {
$cookie_bits = explode('=', $this->cookies);
if (!empty($cookie_bits) && array_key_exists(1, $cookie_bits)) {
$jwt = $cookie_bits[1];
} else {
return false;
}
$jwt_components = explode('.', $jwt);
if (!empty($jwt_components) && array_key_exists(1, $jwt_components)) {
$jwt_payload = $jwt_components[1];
} else {
return false;
}
return json_decode(base64_decode($jwt_payload))->csrfToken;
}
return false;
}
/**
* Execute the cURL request
*/
protected function exec_curl($path, $payload = '')
protected function exec_curl($path, $payload = null)
{
if (!in_array($this->request_type, $this->request_types_allowed)) {
trigger_error('an invalid HTTP request type was used: ' . $this->request_type);
}
if (!is_resource($ch = $this->get_curl_resource())) {
trigger_error('$ch as returned by get_curl_resource() is not a resource');
} else {
$json_payload = '';
$json_payload = [];
if ($this->is_unifi_os) {
$url = $this->baseurl . '/proxy/network' . $path;
@ -3941,26 +3980,47 @@ class Client
curl_setopt($ch, CURLOPT_URL, $url);
if (!empty($payload)) {
if ($payload !== null) {
curl_setopt($ch, CURLOPT_POST, true);
$json_payload = json_encode($payload, JSON_UNESCAPED_SLASHES);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json_payload);
$headers = [
'Content-Type: application/json',
'Content-Length: ' . strlen($json_payload),
'Accept: application/json'
];
if ($this->is_unifi_os) {
$csrf_token = $this->extract_csrf_token_from_cookie();
if ($csrf_token) {
$headers[] = 'x-csrf-token: ' . $csrf_token;
}
}
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
/**
* we shouldn't be using GET (the default request type) or DELETE when passing a payload,
* we switch to POST instead
*/
if ($this->request_type === 'GET' || $this->request_type === 'DELETE') {
$this->request_type = 'POST';
}
if ($this->request_type === 'PUT') {
curl_setopt($ch, CURLOPT_HTTPHEADER,
['Content-Type: application/json', 'Content-Length: ' . strlen($json_payload)]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
} else {
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $this->request_type);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
}
} else {
curl_setopt($ch, CURLOPT_POST, false);
if ($this->request_type === 'DELETE') {
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
if ($this->request_type === 'POST') {
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
}
}
if ($this->request_type === 'DELETE') {
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
}
/**
* execute the cURL request
*/
@ -3970,7 +4030,7 @@ class Client
}
/**
* has the session timed out? If so, we need to login again.
* has the Cookie/Token expired? If so, we need to login again.
*/
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
@ -3979,14 +4039,14 @@ class Client
if (isset($json_decoded_content['meta']['msg']) && $json_decoded_content['meta']['msg'] === 'api.err.LoginRequired') {
if ($this->debug) {
error_log('cURL debug: Needed to reconnect to UniFi Controller');
error_log('cURL debug: needed to reconnect to UniFi controller');
}
/**
* explicitly unset the old cookie now
* explicitly clear the expired Cookie/Token now
*/
if (isset($_SESSION['unificookie'])) {
unset($_SESSION['unificookie']);
$_SESSION['unificookie'] = '';
}
/**
@ -4052,7 +4112,6 @@ class Client
protected function get_curl_resource()
{
$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, $this->curl_ssl_verify_peer);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, $this->curl_ssl_verify_host);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);