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

- minor syntax improvement based on Scrutinizer feedback

Browse Source 
- added create_dynamicdns() and set_dynamicdns() methods, "borrowed" routes from @smos
- made a start at changing the function/method comments to PHPDoc format (PSR-5) which will support auto-generated class documentation
(https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#5-the-phpdoc-format)
This commit is contained in:
malle-pietje 2020-06-20 16:12:13 +02:00
parent 0d99d4a776
commit 2b34890a67
2 changed files with 160 additions and 139 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
README.md
View File

@ -1,6 +1,6 @@
## UniFi Controller API client class
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.66 has been confirmed to work) as well as UbiOS-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).
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.72 has been confirmed to work) as well as UbiOS-based controllers (version 5.12.59 has been confirmed to work). This class is used by our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
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.
@ -23,7 +23,7 @@ You can use [Composer](#composer), [Git](#git) or simply [Download the Release](
### Composer
The preferred method is via [composer](https://getcomposer.org). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.
The preferred installation method is through [composer](https://getcomposer.org). Follow these [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.
Once composer is installed, simply execute this command from the shell in your project directory:
@ -108,16 +108,20 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
- logout()
- adopt_device()
- archive_alarm()
- assign_existing_admin()
- authorize_guest()
- block_sta()
- cancel_rolling_upgrade()
- cmd_stat()
- count_alarms()
- create_dynamicdns()
- create_firewallgroup()
- create_hotspotop()
- create_network()
- create_radius_account()
- create_site()
- create_usergroup()
- create_user()
- create_usergroup()
- create_voucher()
- create_wlan()
- custom_api_request()
@ -135,12 +139,10 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
- extend_guest_validity()
- forget_sta() (supported on controller version 5.9.X and higher)
- invite_admin()
- assign_existing_admin()
- revoke_admin()
- led_override()
- list_admins()
- list_all_admins()
- list_alarms()
- list_all_admins()
- list_aps() (deprecated but still available as alias)
- list_backups()
- list_clients()
@ -177,14 +179,16 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
- locate_ap()
- move_device()
- power_cycle_switch_port()
- reboot_cloudkey()
- reconnect_sta()
- rename_ap()
- restart_ap() (deprecated but still available as alias)
- restart_device()
- reboot_cloudkey()
- revoke_admin()
- revoke_voucher()
- set_ap_radiosettings()
- set_device_settings_base()
- set_dynamicdns()
- set_guestlogin_settings()
- set_guestlogin_settings_base()
- set_ips_settings_base() (supported on controller version 5.9.10 and higher)
@ -199,11 +203,11 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
- set_site_name()
- set_site_ntp()
- set_site_snmp()
- set_super_mgmt_settings_base()
- set_super_smtp_settings_base()
- set_super_identity_settings_base()
- set_sta_name()
- set_sta_note()
- set_super_identity_settings_base()
- set_super_mgmt_settings_base()
- set_super_smtp_settings_base()
- set_usergroup()
- set_wlan_mac_filter()
- set_wlansettings()
@ -213,26 +217,27 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
- site_ledson() (deprecated but still available as alias)
- spectrum_scan()
- spectrum_scan_state()
- start_rolling_upgrade()
- stat_5minutes_aps() (supported on controller version 5.5.X and higher)
- stat_5minutes_gateway() (supported on controller version 5.7.X and higher)
- stat_5minutes_site() (supported on controller version 5.5.X and higher)
- stat_5minutes_user (supported on controller version 5.7.X and higher)
- stat_allusers()
- stat_auths()
- stat_client()
- stat_5minutes_aps() (supported on controller version 5.5.X and higher)
- stat_hourly_aps()
- stat_daily_aps()
- stat_5minutes_gateway() (supported on controller version 5.7.X and higher)
- stat_hourly_gateway() (supported on controller version 5.7.X and higher)
- stat_daily_gateway() (supported on controller version 5.7.X and higher)
- stat_5minutes_site() (supported on controller version 5.5.X and higher)
- stat_hourly_site()
- stat_daily_site()
- stat_5minutes_user (supported on controller version 5.7.X and higher)
- stat_hourly_user() (supported on controller version 5.7.X and higher)
- stat_daily_user() (supported on controller version 5.7.X and higher)
- stat_hourly_aps()
- stat_hourly_gateway() (supported on controller version 5.7.X and higher)
- stat_hourly_site()
- stat_hourly_user() (supported on controller version 5.7.X and higher)
- stat_ips_events() (supported on controller version 5.9.10 and higher)
- stat_payment()
- stat_sessions()
- stat_sites()
- stat_speedtest_results()
- stat_ips_events() (supported on controller version 5.9.10 and higher)
- stat_sta_sessions_latest()
- stat_status()
- stat_sysinfo()
@ -242,32 +247,29 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
- unset_locate_ap() (deprecated but still available as alias)
- upgrade_device()
- upgrade_device_external()
- start_rolling_upgrade()
- cancel_rolling_upgrade()
- cmd_stat()
Other functions, getters/setters:
- set_debug()
- get_debug()
- set_site()
- get_site()
- set_cookies()
- get_cookies()
- get_cookie() (renamed from getcookie(), deprecated but still available, use get_cookies() instead)
- get_last_results_raw()
- get_last_error_message()
- set_request_type()
- get_request_type()
- set_ssl_verify_peer()
- get_ssl_verify_peer()
- set_ssl_verify_host()
- get_ssl_verify_host()
- set_connection_timeout()
- get_connection_timeout()
- set_is_unifi_os()
- get_is_unifi_os()
- get_class_version()
- get_connection_timeout()
- get_cookie() (renamed from getcookie(), deprecated but still available, use get_cookies() instead)
- get_cookies()
- get_debug()
- get_is_unifi_os()
- get_last_error_message()
- get_last_results_raw()
- get_request_type()
- get_site()
- get_ssl_verify_host()
- get_ssl_verify_peer()
- set_connection_timeout()
- set_cookies()
- set_debug()
- set_is_unifi_os()
- set_request_type()
- set_site()
- set_ssl_verify_host()
- set_ssl_verify_peer()
## Need help or have suggestions?

215
src/Client.php
View File

@ -1,6 +1,8 @@
<?php
namespace UniFi_API;
/**
* This file is part of the art-of-wifi/unifi-api-client package
* the UniFi API client class
*
* 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
@ -8,16 +10,12 @@
* and the API as published by Ubiquiti:
* https://www.ubnt.com/downloads/unifi/<UniFi controller version number>/unifi_sh_api
*
* Copyright (c) 2017, Art of WiFi <info@artofwifi.net>
*
* This source file is subject to the MIT license that is bundled
* with this package in the file LICENSE.md
*/
namespace UniFi_API;
/**
* the UniFi API client class
* @package art-of-wifi/unifi-api-client
* @author Art of WiFi <info@artofwifi.net>
* @version 1.1.57
* @license This class is subject to the MIT license that is bundled with this package in the file LICENSE.md
* @example See this directory in the package repository for a variety of examples:
* https://github.com/Art-of-WiFi/UniFi-API-client/tree/master/examples
*/
class Client
{
@ -33,7 +31,7 @@ class Client
protected $is_loggedin = false;
protected $is_unifi_os = false;
protected $exec_retries = 0;
protected $class_version = '1.1.56';
protected $class_version = '1.1.57';
private $cookies = '';
private $request_type = 'GET';
private $request_types_allowed = ['GET', 'POST', 'PUT', 'DELETE'];
@ -45,18 +43,17 @@ class Client
/**
* Construct an instance of the UniFi API client class
* ---------------------------------------------------
* returns 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 which *must* include 'https://'' prefix,
* a port suffix (e.g. :8443) is required for non-UniFi OS controllers,
* do not add trailing slashes, defaults to 'https://127.0.0.1:8443'
* optional parameter <site> = string; short site name to access, defaults to 'default'
* optional parameter <version> = string; the version number of the controller
* 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)
* disables validation of the controller certificate
*
* @param string $user user name to use when connecting to the UniFi controller
* @param string $password password to use when connecting to the UniFi controller
* @param string $baseurl optional, 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, defaults to 'https://127.0.0.1:8443'
* @param string $site optional, short site name to access, defaults to 'default'
* @param string $version optional, the version number of the controller
* @param bool $ssl_verify optional, 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)
* disables validation of the controller certificate
*/
public function __construct($user, $password, $baseurl = '', $site = '', $version = '', $ssl_verify = false)
{
@ -81,7 +78,7 @@ class Client
$this->version = trim($version);
}
if ((boolean)$ssl_verify === true) {
if ((boolean) $ssl_verify === true) {
$this->curl_ssl_verify_peer = true;
$this->curl_ssl_verify_host = 2;
}
@ -91,8 +88,7 @@ class Client
* This method is 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 when you're done, simply call logout()
* NOTE: to force the class instance to log out when you're done, simply call logout()
*/
public function __destruct()
{
@ -113,8 +109,8 @@ class Client
/**
* Login to the UniFi controller
* -----------------------------
* returns true upon success
*
* @return bool returns true upon success
*/
public function login()
{
@ -240,8 +236,8 @@ class Client
/**
* Logout from the UniFi controller
* --------------------------------
* returns true upon success
*
* @return bool returns true upon success
*/
public function logout()
{
@ -298,14 +294,14 @@ class Client
/**
* Authorize a client device
* -------------------------
* return true on success
* required parameter <mac> = client MAC address
* required parameter <minutes> = minutes (from now) until authorization expires
* optional parameter <up> = upload speed limit in kbps
* optional parameter <down> = download speed limit in kbps
* optional parameter <MBytes> = data transfer limit in MB
* optional parameter <ap_mac> = AP MAC address to which client is connected, should result in faster authorization
*
* @param string $mac client MAC address
* @param int $minutes minutes (from now) until authorization expires
* @param int $up optional, upload speed limit in kbps
* @param int $down optional, download speed limit in kbps
* @param int $MBytes optional, data transfer limit in MB
* @param int $ap_mac optional, AP MAC address to which client is connected, should result in faster authorization
* @return bool returns true upon success
*/
public function authorize_guest($mac, $minutes, $up = null, $down = null, $MBytes = null, $ap_mac = null)
{
@ -335,9 +331,9 @@ class Client
/**
* Unauthorize a client device
* ---------------------------
* return true on success
* required parameter <mac> = client MAC address
*
* @param string $mac client MAC address
* @return bool returns true upon success
*/
public function unauthorize_guest($mac)
{
@ -348,9 +344,9 @@ class Client
/**
* Reconnect a client device
* -------------------------
* return true on success
* required parameter <mac> = client MAC address
*
* @param string $mac client MAC address
* @return bool returns true upon success
*/
public function reconnect_sta($mac)
{
@ -361,9 +357,9 @@ class Client
/**
* Block a client device
* ---------------------
* return true on success
* required parameter <mac> = client MAC address
*
* @param string $mac client MAC address
* @return bool returns true upon success
*/
public function block_sta($mac)
{
@ -374,9 +370,9 @@ class Client
/**
* Unblock a client device
* -----------------------
* return true on success
* required parameter <mac> = client MAC address
*
* @param string $mac client MAC address
* @return bool returns true upon success
*/
public function unblock_sta($mac)
{
@ -387,13 +383,13 @@ class Client
/**
* Forget one or more client devices
* ---------------------------------
* return true on success
* required parameter <macs> = array of client MAC addresses
*
* NOTE:
* only supported with controller versions 5.9.X and higher, can be
* slow (up to 5 minutes) on larger controllers
*
* @param array $macs array of client MAC addresses (strings)
* @return bool returns true upon success
*/
public function forget_sta($macs)
{
@ -404,15 +400,15 @@ class Client
/**
* Create a new user/client-device
* -------------------------------
* return an array with a single object containing details of the new user/client-device on success, else return false
* required parameter <mac> = client MAC address
* required parameter <user_group_id> = _id value for the user group the new user/client-device should belong to which
* can be obtained from the output of list_usergroups()
* optional parameter <name> = name to be given to the new user/client-device
* optional parameter <note> = note to be applied to the new user/client-device
* optional parameter <is_guest> = boolean; defines whether the new user/client-device is a guest or not
* optional parameter <is_wired> = boolean; defines whether the new user/client-device is wired or not
*
* @param string $mac client MAC address
* @param string $user_group_id _id value for the user group the new user/client-device should belong to which
* can be obtained from the output of list_usergroups()
* @param string $name optional, name to be given to the new user/client-device
* @param string $note optional, note to be applied to the new user/client-device
* @param bool $is_guest optional, defines whether the new user/client-device is a guest or not
* @param bool $is_wired optional, defines whether the new user/client-device is wired or not
* @return array returns an array with a single object containing details of the new user/client-device on success, else returns false
*/
public function create_user($mac, $user_group_id, $name = null, $note = null, $is_guest = null, $is_wired = null)
{
@ -441,13 +437,11 @@ class Client
/**
* Add/modify/remove a client-device note
* --------------------------------------
* return true on success
* required parameter <user_id> = id of the client-device to be modified
* optional parameter <note> = note to be applied to the client-device
*
* NOTES:
* - when note is empty or not set, the existing note for the client-device will be removed and "noted" attribute set to false
* @param string $user_id id of the client-device to be modified
* @param string $note optional, note to be applied to the client-device, when empty or not set,
* the existing note for the client-device will be removed and "noted" attribute set to false
* @return bool returns true upon success
*/
public function set_sta_note($user_id, $note = null)
{
@ -459,13 +453,11 @@ class Client
/**
* Add/modify/remove a client device name
* --------------------------------------
* return true on success
* required parameter <user_id> = id of the client device to be modified
* optional parameter <name> = name to be applied to the client device
*
* NOTES:
* - when name is empty or not set, the existing name for the client device will be removed
* @param string $user_id id of the client-device to be modified
* @param string $note optional, name to be applied to the client device, when empty or not set,
* the existing name for the client device will be removed
* @return bool returns true upon success
*/
public function set_sta_name($user_id, $name = null)
{
@ -476,16 +468,16 @@ class Client
/**
* 5 minutes site stats method
* ---------------------------
* returns an array of 5-minute stats objects for the current site
* optional parameter <start> = Unix timestamp in milliseconds
* optional parameter <end> = Unix timestamp in milliseconds
*
* NOTES:
* - defaults to the past 12 hours
* - this function/method is only supported on controller versions 5.5.* and later
* - make sure that the retention policy for 5 minutes stats is set to the correct value in
* the controller settings
*
* @param int $start optional, Unix timestamp in milliseconds
* @param int $end optional, Unix timestamp in milliseconds
* @return array returns an array of 5-minute stats objects for the current site
*/
public function stat_5minutes_site($start = null, $end = null)
{
@ -1500,7 +1492,7 @@ class Client
return false;
}
$payload= [
$payload = [
'name' => trim($name),
'email' => trim($email),
'for_sso' => $enable_sso,
@ -1832,16 +1824,6 @@ class Client
return $this->fetch_results('/api/s/' . $this->site . '/list/portforward');
}
/**
* List dynamic DNS settings
* -------------------------
* returns an array of dynamic DNS settings
*/
public function list_dynamicdns()
{
return $this->fetch_results('/api/s/' . $this->site . '/list/dynamicdns');
}
/**
* List port configurations
* ------------------------
@ -2221,6 +2203,43 @@ class Client
return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/sitemgr', $payload);
}
/**
* List dynamic DNS settings (using REST)
* --------------------------------------
* returns an array of dynamic DNS settings
*/
public function list_dynamicdns()
{
return $this->fetch_results('/api/s/' . $this->site . '/rest/dynamicdns');
}
/**
* Create dynamic DNS settings, base (using REST)
* ----------------------------------------------
* return true on success
* required parameter <payload> = stdClass object or associative array containing the configuration to apply to the site, must be a
* (partial) object/array structured in the same manner as is returned by list_dynamicdns() for the site.
*/
public function create_dynamicdns($payload)
{
return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/dynamicdns', $payload);
}
/**
* Update site dynamic DNS, base (using REST)
* ------------------------------------------
* return true on success
* required parameter <dynamicdns_id> = 24 char string; _id of the settings which can be found with the list_dynamicdns() function
* required parameter <payload> = stdClass object or associative array containing the configuration to apply to the site, must be a
* (partial) object/array structured in the same manner as is returned by list_dynamicdns() for the site.
*/
public function set_dynamicdns($dynamicdns_id, $payload)
{
$this->request_type = 'PUT';
return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/dynamicdns/' . trim($dynamicdns_id), $payload);
}
/**
* List network settings (using REST)
* ----------------------------------
@ -2620,7 +2639,7 @@ class Client
*/
public function spectrum_scan($ap_mac)
{
$payload = ['cmd' => 'spectrum-scan', 'mac' => strtolower($ap_mac)];
$payload = ['cmd' => 'spectrum-scan', 'mac' => strtolower($ap_mac)];
return $this->fetch_results_boolean('/api/s/' . $this->site . '/cmd/devmgr', $payload);
}
@ -3151,11 +3170,11 @@ class Client
* Fetch results
* -------------
* execute the cURL request and return results
* required parameter <path> = request path
* optional parameter <payload> = payload to pass with the request
* optional parameter <boolean> = whether the method should return a boolean result, else return
* required parameter <path> = string, request path
* optional parameter <payload> = PHP associative array or stdClass Object, payload to pass with the request
* optional parameter <boolean> = boolean, whether the method should return a boolean result, else return
* the "data" array
* optional parameter <login_required> = whether the method requires to be logged in or not
* optional parameter <login_required> = boolean, whether the method requires to be logged in or not
*/
protected function fetch_results($path, $payload = null, $boolean = false, $login_required = true)
{
@ -3199,9 +3218,9 @@ class Client
* Fetch results where output should be boolean (true/false)
* ---------------------------------------------------------
* execute the cURL request and return a boolean value
* required parameter <path> = request path
* optional parameter <payload> = payload to pass with the request
* optional parameter <login_required> = whether the method requires to be logged in or not
* required parameter <path> = string, request path
* optional parameter <payload> = PHP associative array or stdClass Object, payload to pass with the request
* optional parameter <login_required> = boolean, whether the method requires to be logged in or not
*/
protected function fetch_results_boolean($path, $payload = null, $login_required = true)
{