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

API client class v1.1.42

Browse Source 
changed variable name $url to $path in custom_api_request() for consistency and clarity
rearranged layout of Client.php
added check to verify whether $ch is a resource
renamed get_curl_obj() to get_curl_resource() to reflect the variable type it returns

Added the new functions/methods:
* set_super_mgmt_settings_base()
* set_super_smtp_settings_base()
* set_super_identity_settings_base()
This commit is contained in:
malle-pietje 2019-10-15 14:04:37 +02:00
parent 09db47affd
commit 727cd6dc9c
3 changed files with 400 additions and 319 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -1,6 +1,6 @@
## UniFi Controller API client class
A PHP class which provides access to Ubiquiti's [**UniFi SDN Controller API**](https://unifi-sdn.ui.com/), versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.10.19 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 which provides access to Ubiquiti's [**UniFi SDN Controller API**](https://unifi-sdn.ui.com/), versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.11.39 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).
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.
@ -84,13 +84,13 @@ Please refer to the `examples/` directory for some more detailed examples which
#### IMPORTANT NOTES:
1. In the above example, `$site_id` is the short site "name" (usually 8 characters long) that is visible in the URL when managing the site in the UniFi SDN Controller, for example with this URL:
1. In the above example, `$site_id` is the short site "name" (usually 8 characters long) that is visible in the URL when managing the site in the UniFi SDN Controller. For example with this URL:
`https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard`
`jl3z2shm` is the short site "name" and the value to assign to $site_id.
2. The last optional parameter that is passed to the constructor in the above example (`true`), enables validation of the controller's SSL certificate which is otherwise **disabled** by default. It is highly recommended to enable this feature in production environments where you have a valid SSL cert installed on the UniFi Controller, and which is associated with the FQDN of the server as used in the `controller_url` parameter. This option was added with API client version 1.1.16.
2. The last optional parameter that is passed to the constructor in the above example (`true`), enables validation of the controller's SSL certificate which is otherwise **disabled** by default. It is highly recommended to enable this feature in production environments where you have a valid SSL cert installed on the UniFi Controller that is associated with the FQDN in the `controller_url` parameter. This option was added with API client version 1.1.16.
## Functions/methods supported

14
examples/auth_guest_basic.php
View File

@ -3,7 +3,7 @@
* PHP API usage example
*
* contributed by: Art of WiFi
* description: example basic PHP script to perform a basic auth of a guest device
* description: example PHP script to perform a basic auth of a guest device
*/
/**
@ -22,6 +22,16 @@ require_once('config.php');
*/
$mac = '<enter MAC address of guest device to auth>';
/**
* the MAC address of the Access Point the guest is currently connected to, enter null (without quotes)
* if not known or unavailable
*
* NOTE:
* although the AP MAC address is not a required parameter for the authorize_guest() function,
* adding this parameter will speed up the initial authorization process
*/
$ap_mac = '<enter MAC address of Access Point>';
/**
* the duration to authorize the device for in minutes
*/
@ -42,7 +52,7 @@ $loginresults = $unifi_connection->login();
/**
* then we authorize the device for the requested duration
*/
$auth_result = $unifi_connection->authorize_guest($mac, $duration);
$auth_result = $unifi_connection->authorize_guest($mac, $duration, null, null, null, $ap_mac);
/**
* provide feedback in json format

463
src/Client.php
View File

@ -114,8 +114,9 @@ class Client
return $this->is_loggedin = true;
}
$ch = $this->get_curl_obj();
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_REFERER, $this->baseurl . '/login');
curl_setopt($ch, CURLOPT_URL, $this->baseurl . '/api/login');
@ -167,6 +168,7 @@ class Client
}
}
}
}
return false;
}
@ -1769,14 +1771,14 @@ class Client
}
/**
* Revoke an admin
* ---------------
* Revoke an admin from the current site
* -------------------------------------
* returns true on success
* required parameter <admin_id> = _id value of the admin to revoke, can be obtained using the
* list_all_admins() method/function
*
* NOTES:
* only non-superadmins account can be revoked
* only non-superadmin accounts can be revoked
*/
public function revoke_admin($admin_id)
{
@ -2456,6 +2458,66 @@ class Client
return $this->process_response_boolean($response);
}
/**
* Update "Super Management" settings, base
* ------------------------------------------
* return true on success
* required parameter <settings_id> = 24 char string; value of _id for the site settings section where key = "super_mgmt", settings can be obtained
* using the list_settings() function
* required parameter <payload> = stdClass object or associative array containing the "Super Management" settings to apply, must be a (partial)
* object/array structured in the same manner as is returned by list_settings() for the "super_mgmt" section.
*/
public function set_super_mgmt_settings_base($settings_id, $payload)
{
if (!$this->is_loggedin) {
return false;
}
$response = $this->exec_curl('/api/s/' . $this->site . '/set/setting/super_mgmt/' . trim($settings_id), $payload);
return $this->process_response_boolean($response);
}
/**
* Update "Super SMTP" settings, base
* ------------------------------------------
* return true on success
* required parameter <settings_id> = 24 char string; value of _id for the site settings section where key = "super_smtp", settings can be obtained
* using the list_settings() function
* required parameter <payload> = stdClass object or associative array containing the "Super SMTP" settings to apply, must be a (partial)
* object/array structured in the same manner as is returned by list_settings() for the "super_smtp" section.
*/
public function set_super_smtp_settings_base($settings_id, $payload)
{
if (!$this->is_loggedin) {
return false;
}
$response = $this->exec_curl('/api/s/' . $this->site . '/set/setting/super_smtp/' . trim($settings_id), $payload);
return $this->process_response_boolean($response);
}
/**
* Update "Super Controller Identity" settings, base
* ------------------------------------------
* return true on success
* required parameter <settings_id> = 24 char string; value of _id for the site settings section where key = "super_identity", settings can be obtained
* using the list_settings() function
* required parameter <payload> = stdClass object or associative array containing the "Super Controller Identity" settings to apply, must be a (partial)
* object/array structured in the same manner as is returned by list_settings() for the "super_identity" section.
*/
public function set_super_identity_settings_base($settings_id, $payload)
{
if (!$this->is_loggedin) {
return false;
}
$response = $this->exec_curl('/api/s/' . $this->site . '/set/setting/super_identity/' . trim($settings_id), $payload);
return $this->process_response_boolean($response);
}
/**
* Rename access point
* -------------------
@ -3296,8 +3358,8 @@ class Client
/**
* Custom API request
* ------------------
* return results as requested
* required parameter <url> = string; suffix of the URL (following the port number) to pass request to, *must* start with a "/" character
* returns results as requested, returns false on incorrect parameters
* required parameter <path> = string; suffix of the URL (following the port number) to pass request to, *must* start with a "/" character
* optional parameter <request_type> = string; HTTP request type, can be GET (default), POST, PUT, or DELETE
* optional parameter <payload> = stdClass object or associative array containing the payload to pass
* optional parameter <return> = string; determines how to return results, value must be "boolean" when the method must return a
@ -3306,24 +3368,202 @@ class Client
* NOTE:
* Only use this method when you fully understand the behavior of the UniFi controller API. No input validation is performed, to be used with care!
*/
public function custom_api_request($url, $request_type = 'GET', $payload = null, $return = 'array')
public function custom_api_request($path, $request_type = 'GET', $payload = null, $return = 'array')
{
if (!$this->is_loggedin) {
return false;
}
$this->request_type = $request_type;
$response = $this->exec_curl($url, $payload);
$response = $this->exec_curl($path, $payload);
if ($return === 'array') {
return $this->process_response($response);
} elseif ($return === 'boolean') {
return $this->process_response_boolean($response);
}
return false;
}
/****************************************************************
* Internal (private) functions from here:
* setter/getter functions from here:
****************************************************************/
/**
* Set site
* --------
* modify the private property site, returns the new (short) site name
* required parameter <site> = string; must be the short site name of a site to which the
* provided credentials have access
*
* NOTE:
* this method can be useful when switching between sites
*/
public function set_site($site)
{
$this->check_site($site);
$this->site = trim($site);
return $this->site;
}
/**
* Get site
* --------
* get the value of private property site, returns the current (short) site name
*/
public function get_site()
{
return $this->site;
}
/**
* Set debug mode
* --------------
* sets debug mode to true or false, returns false if a non-boolean parameter was passed
* required parameter <enable> = boolean; true will enable debug mode, false will disable it
*/
public function set_debug($enable)
{
if ($enable === true || $enable === false) {
$this->debug = $enable;
return true;
}
trigger_error('Error: the parameter for set_debug() must be boolean');
return false;
}
/**
* Get debug mode
* --------------
* get the value of private property debug, returns the current boolean value for debug
*/
public function get_debug()
{
return $this->debug;
}
/**
* Get last raw results
* --------------------
* 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
*/
public function get_last_results_raw($return_json = false)
{
if ($this->last_results_raw !== null) {
if ($return_json) {
return json_encode($this->last_results_raw, JSON_PRETTY_PRINT);
}
return $this->last_results_raw;
}
return false;
}
/**
* Get last error message
* ----------------------
* returns the error message of the last method called in PHP stdClass Object format, returns false if unavailable
*/
public function get_last_error_message()
{
if ($this->last_error_message !== null) {
return $this->last_error_message;
}
return false;
}
/**
* 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
* 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.
*/
public function get_cookie()
{
if (!$this->is_loggedin) {
return false;
}
return $this->cookies;
}
/******************************************************************
* other getter/setter functions/methods from here, use with care!
******************************************************************/
public function get_cookies()
{
return $this->cookies;
}
public function get_request_type()
{
return $this->request_type;
}
public function get_ssl_verify_peer()
{
return $this->curl_ssl_verify_peer;
}
public function get_ssl_verify_host()
{
return $this->curl_ssl_verify_host;
}
public function set_cookies($cookies_value)
{
$this->cookies = $cookies_value;
}
public function set_request_type($request_type)
{
$this->request_type = $request_type;
}
public function set_connection_timeout($timeout)
{
$this->connect_timeout = $timeout;
}
public function set_last_results_raw($last_results)
{
$this->last_results_raw = $last_results;
}
public function set_last_error_message($last_error_message)
{
$this->last_error_message = $last_error_message;
}
public function set_ssl_verify_peer($ssl_verify_peer)
{
$this->curl_ssl_verify_peer = $ssl_verify_peer;
}
/**
* set the value for cURL option CURLOPT_SSL_VERIFYHOST, should be 0/false or 2
*/
public function set_ssl_verify_host($ssl_verify_host)
{
$this->curl_ssl_verify_host = $ssl_verify_host;
}
/****************************************************************
* internal (private and protected) functions from here:
****************************************************************/
/**
@ -3498,11 +3738,12 @@ class Client
*/
protected function exec_curl($path, $payload = '')
{
if (!is_resource($ch = $this->get_curl_resource())) {
trigger_error('$ch as returned by get_curl_resource() is not a resource');
} else {
$json_payload = '';
$url = $this->baseurl . $path;
$ch = $this->get_curl_obj();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLINFO_HEADER_OUT, true);
if (!empty($payload)) {
$json_payload = json_encode($payload, JSON_UNESCAPED_SLASHES);
@ -3532,7 +3773,7 @@ class Client
}
/**
* has the session timed out?
* has the session timed out? If so, we need to login again.
*/
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
@ -3549,23 +3790,24 @@ class Client
*/
if (isset($_SESSION['unificookie'])) {
unset($_SESSION['unificookie']);
$no_cookie_in_use = 1;
}
/**
* then login again
*/
$this->login();
/**
* when login was okay, exec the same command again
* when login was successful, execute the same command again
*/
if ($this->is_loggedin) {
curl_close($ch);
/**
* setup the cookie for the user within $_SESSION
* setup the cookie for the user within $_SESSION, if $_SESSION['unificookie'] does not exist
*/
if (isset($no_cookie_in_use) && session_status() != PHP_SESSION_DISABLED) {
if (!isset($_SESSION['unificookie']) && session_status() != PHP_SESSION_DISABLED) {
$_SESSION['unificookie'] = $this->cookies;
unset($no_cookie_in_use);
}
return $this->exec_curl($path, $payload);
@ -3603,10 +3845,14 @@ class Client
return $content;
}
return false;
}
/**
* Get the cURL object
* Create a new cURL resource and return a cURL handle,
* returns false on errors
*/
protected function get_curl_obj()
protected function get_curl_resource()
{
$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, true);
@ -3614,6 +3860,7 @@ class Client
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, $this->curl_ssl_verify_host);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $this->connect_timeout);
curl_setopt($ch, CURLINFO_HEADER_OUT, true);
if ($this->debug) {
curl_setopt($ch, CURLOPT_VERBOSE, true);
@ -3626,180 +3873,4 @@ class Client
return $ch;
}
/****************************************************************
* setter/getter functions from here:
****************************************************************/
/**
* Set site
* --------
* modify the private property site, returns the new (short) site name
* required parameter <site> = string; must be the short site name of a site to which the
* provided credentials have access
*
* NOTE:
* this method can be useful when switching between sites
*/
public function set_site($site)
{
$this->check_site($site);
$this->site = trim($site);
return $this->site;
}
/**
* Get site
* --------
* get the value of private property site, returns the current (short) site name
*/
public function get_site()
{
return $this->site;
}
/**
* Set debug mode
* --------------
* sets debug mode to true or false, returns false if a non-boolean parameter was passed
* required parameter <enable> = boolean; true will enable debug mode, false will disable it
*/
public function set_debug($enable)
{
if ($enable === true || $enable === false) {
$this->debug = $enable;
return true;
}
trigger_error('Error: the parameter for set_debug() must be boolean');
return false;
}
/**
* Get debug mode
* --------------
* get the value of private property debug, returns the current boolean value for debug
*/
public function get_debug()
{
return $this->debug;
}
/**
* Get last raw results
* --------------------
* 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
*/
public function get_last_results_raw($return_json = false)
{
if ($this->last_results_raw !== null) {
if ($return_json) {
return json_encode($this->last_results_raw, JSON_PRETTY_PRINT);
}
return $this->last_results_raw;
}
return false;
}
/**
* Get last error message
* ----------------------
* returns the error message of the last method called in PHP stdClass Object format, returns false if unavailable
*/
public function get_last_error_message()
{
if ($this->last_error_message !== null) {
return $this->last_error_message;
}
return false;
}
/**
* 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
* 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.
*/
public function get_cookie()
{
if (!$this->is_loggedin) {
return false;
}
return $this->cookies;
}
/****************************************************************
* other getter/setter functions/methods from here, use with care!
****************************************************************/
public function get_cookies()
{
return $this->cookies;
}
public function get_request_type()
{
return $this->request_type;
}
public function get_ssl_verify_peer()
{
return $this->curl_ssl_verify_peer;
}
public function get_ssl_verify_host()
{
return $this->curl_ssl_verify_host;
}
public function set_cookies($cookies_value)
{
$this->cookies = $cookies_value;
}
public function set_request_type($request_type)
{
$this->request_type = $request_type;
}
public function set_connection_timeout($timeout)
{
$this->connect_timeout = $timeout;
}
public function set_last_results_raw($last_results)
{
$this->last_results_raw = $last_results;
}
public function set_last_error_message($last_error_message)
{
$this->last_error_message = $last_error_message;
}
public function set_ssl_verify_peer($ssl_verify_peer)
{
$this->curl_ssl_verify_peer = $ssl_verify_peer;
}
/**
* set the value for cURL option CURLOPT_SSL_VERIFYHOST, should be 0/false or 2
*/
public function set_ssl_verify_host($ssl_verify_host)
{
$this->curl_ssl_verify_host = $ssl_verify_host;
}
}