diff --git a/README.md b/README.md index f4c9708..b27af81 100755 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ## UniFi Controller API client class -A PHP class that provides access to Ubiquiti's [**UniFi Network Controller**](https://unifi-network.ui.com/) API, versions 4.X.X, 5.X.X and 6.0.X of the UniFi Network Controller software are supported (version 6.0.42 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 by 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 Network Controller**](https://unifi-network.ui.com/) API, versions 4.X.X, 5.X.X and 6.0.X of the UniFi Network Controller software are supported (version 6.0.43 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 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 by using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects. @@ -13,13 +13,13 @@ The package can be installed manually or by using composer/[packagist](https://p ## UniFi OS Support -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. +Support for UniFi OS-based controllers (UniFi Dream Machine Pro or Cloud Key Gen2/Cloud Key Gen2 Plus with firmware version 2.0.24 or higher) 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 -You can use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client class. +Use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client class. ### Composer @@ -31,7 +31,7 @@ Once composer is installed, simply execute this command from the shell in your p composer require art-of-wifi/unifi-api-client ``` - Or you can manually add the package to your composer.json file: + Or manually add the package to your composer.json file: ```javascript { @@ -44,7 +44,7 @@ composer require art-of-wifi/unifi-api-client Finally, be sure to include the autoloader in your code: ```php -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; ``` ### Git @@ -58,15 +58,15 @@ git clone https://github.com/Art-of-WiFi/UniFi-API-client.git When git is done cloning, include the file containing the class like so in your code: ```php -require_once('path/to/src/Client.php'); +require_once 'path/to/src/Client.php'; ``` ### Download the Release -If you prefer not to use composer or git, you can simply [download the package](https://github.com/Art-of-WiFi/UniFi-API-client/archive/master.zip), uncompress the zip file, then include the file containing the class in your code like so: +If you prefer not to use composer or git, simply [download the package](https://github.com/Art-of-WiFi/UniFi-API-client/archive/master.zip), uncompress the zip file, then include the file containing the class in your code like so: ```php -require_once('path/to/src/Client.php'); +require_once 'path/to/src/Client.php'; ``` ## Example usage @@ -77,7 +77,7 @@ A basic example how to use the class: /** * load the class using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * initialize the Unifi API connection class, log in to the controller and request the alarms collection @@ -88,7 +88,7 @@ $login = $unifi_connection->login(); $results = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects ``` -Please refer to the `examples/` directory for some more detailed examples which you can use as a starting point for your own PHP code. +Please refer to the `examples/` directory for some more detailed examples which can be used as a starting point for your own PHP code. #### IMPORTANT NOTES: @@ -269,7 +269,7 @@ Other functions, getters/setters: - get_is_unifi_os() - get_last_error_message() - get_last_results_raw() -- get_request_type() +- get_request_method() - get_site() - get_ssl_verify_host() - get_ssl_verify_peer() @@ -277,7 +277,7 @@ Other functions, getters/setters: - set_cookies() - set_debug() - set_is_unifi_os() -- set_request_type() +- set_request_method() - set_site() - set_ssl_verify_host() - set_ssl_verify_peer() diff --git a/examples/ap_scanning_state.php b/examples/ap_scanning_state.php index 91e308e..ab4198c 100755 --- a/examples/ap_scanning_state.php +++ b/examples/ap_scanning_state.php @@ -3,19 +3,19 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example basic PHP script to fetch an Access Point's scanning state/results + * description: example basic PHP script to fetch an Access Point's scanning state/results */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * site id and MAC address of AP to query diff --git a/examples/ap_upgrade_firmware.php b/examples/ap_upgrade_firmware.php index 9989460..086fe47 100755 --- a/examples/ap_upgrade_firmware.php +++ b/examples/ap_upgrade_firmware.php @@ -3,11 +3,11 @@ * PHP API usage example * * contributed by: @4oo4 - * description: example script to upgrade device firmware (can be scheduled with systemd/cron) - * to the most current version + * description: example script to upgrade device firmware (can be scheduled with systemd/cron) + * to the most current version */ -require_once('vendor/autoload.php'); -require_once('config.php'); +require_once 'vendor/autoload.php'; +require_once 'config.php'; /** * site id of the AP to update diff --git a/examples/auth_guest_basic.php b/examples/auth_guest_basic.php index d44072d..c2b4ffc 100755 --- a/examples/auth_guest_basic.php +++ b/examples/auth_guest_basic.php @@ -3,19 +3,19 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example PHP script to perform a basic auth of a guest device + * description: example PHP script to perform a basic auth of a guest device */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * the MAC address of the device to authorize diff --git a/examples/auth_guest_with_note.php b/examples/auth_guest_with_note.php index bac529e..9bf5bc4 100755 --- a/examples/auth_guest_with_note.php +++ b/examples/auth_guest_with_note.php @@ -3,21 +3,21 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example basic PHP script to auth a guest device and attach a note to it, - * this requires the device to be connected to the WLAN/LAN at moment of - * authorization + * description: example basic PHP script to auth a guest device and attach a note to it, + * this requires the device to be connected to the WLAN/LAN at moment of + * authorization */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * the MAC address of the device to authorize diff --git a/examples/block_list.php b/examples/block_list.php index 1166ade..a247b00 100755 --- a/examples/block_list.php +++ b/examples/block_list.php @@ -3,27 +3,26 @@ * PHP API usage example * * contributed by: @malcolmcif, based on another Art of WiFi example - * description: basic PHP script to block a list of mac addresses passed in via command line, - * output is to console in non json format + * description: basic PHP script to block a list of mac addresses passed in via command line, + * output is to console in non json format * * usage: * php block_list.php * * example: * php block_list.php 09:09:09:09:09:09,10:10:10:10:10:10 - * */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; $debug = false; /** diff --git a/examples/change_super_mgmt.php b/examples/change_super_mgmt.php index 95347e1..fcb2ef5 100755 --- a/examples/change_super_mgmt.php +++ b/examples/change_super_mgmt.php @@ -3,14 +3,14 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example basic PHP script to modify the super_mgmt settings for UniFi controller and output results - * in json format + * description: example basic PHP script to modify the super_mgmt settings for UniFi controller and output results + * in json format */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * UniFi controller credentials and the site to use, in this case since we are modifying global settings you can select @@ -18,7 +18,7 @@ require_once('vendor/autoload.php'); * * NOTE: in this case you need to enter Super Administrator account credentials in config.php */ -require_once('config.php'); +require_once 'config.php'; $site_id = 'default'; $debug = false; diff --git a/examples/change_wlan_password.php b/examples/change_wlan_password.php index ff11833..d2ebc8d 100755 --- a/examples/change_wlan_password.php +++ b/examples/change_wlan_password.php @@ -3,19 +3,19 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example basic PHP script to change the WPA2 password/PSK of a WLAN, returns true on success + * description: example basic PHP script to change the WPA2 password/PSK of a WLAN, returns true on success */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * The site to which the WLAN you want to modify belongs diff --git a/examples/config.template.php b/examples/config.template.php index f789bd6..2252bc2 100755 --- a/examples/config.template.php +++ b/examples/config.template.php @@ -1,10 +1,8 @@ '; /** * parameters */ -$url = '/api/s/' . $site_id . '/stat/fwupdate/latest-version'; -$request_type = 'GET'; -$payload = null; -$return = 'array'; +$url = '/api/s/' . $site_id . '/stat/fwupdate/latest-version'; +$request_method = 'GET'; +$payload = null; +$return = 'array'; /** * initialize the UniFi API connection class and log in to the controller and do our thing @@ -38,7 +38,7 @@ $return = 'array'; $unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion); $set_debug_mode = $unifi_connection->set_debug($debug); $loginresults = $unifi_connection->login(); -$results = $unifi_connection->custom_api_request($url, $request_type, $payload, $return); +$results = $unifi_connection->custom_api_request($url, $request_method, $payload, $return); /** * provide feedback in JSON format or as PHP Object diff --git a/examples/extend_guest_auth.php b/examples/extend_guest_auth.php index 463d87a..be0389c 100755 --- a/examples/extend_guest_auth.php +++ b/examples/extend_guest_auth.php @@ -3,19 +3,19 @@ * PHP API usage example * * contributed by: mtotone - * description: example of how to extend validity of guest authorizations + * description: example of how to extend validity of guest authorizations */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * must be adapted to your site! diff --git a/examples/list_alarms.php b/examples/list_alarms.php index 4c82d50..38a7550 100755 --- a/examples/list_alarms.php +++ b/examples/list_alarms.php @@ -3,19 +3,19 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example basic PHP script to pull current alarms from the UniFi controller and output in json format + * description: example basic PHP script to pull current alarms from the UniFi controller and output in json format */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * the site to use diff --git a/examples/list_ap_connected_users.php b/examples/list_ap_connected_users.php index e87b331..14c3809 100755 --- a/examples/list_ap_connected_users.php +++ b/examples/list_ap_connected_users.php @@ -3,20 +3,20 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example to pull connected user numbers for Access Points from the UniFi controller and output the results - * in raw HTML format + * description: example to pull connected user numbers for Access Points from the UniFi controller and output the results + * in raw HTML format */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * the short name of the site which you wish to query diff --git a/examples/list_connected_users.php b/examples/list_connected_users.php index 0cc2c68..a41b3e4 100755 --- a/examples/list_connected_users.php +++ b/examples/list_connected_users.php @@ -3,19 +3,19 @@ * PHP API usage example * * contributed by: @gahujipo - * description: example to pull connected users and their details from the UniFi controller and output the results - * in JSON format + * description: example to pull connected users and their details from the UniFi controller and output the results + * in JSON format */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * the short name of the site which you wish to query diff --git a/examples/list_site_health.php b/examples/list_site_health.php index a7e0159..daf03bb 100755 --- a/examples/list_site_health.php +++ b/examples/list_site_health.php @@ -3,20 +3,20 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example to pull site health metrics from the UniFi controller and output the results - * in json format + * description: example to pull site health metrics from the UniFi controller and output the results + * in json format */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * the short name of the site you wish to query diff --git a/examples/list_sites.php b/examples/list_sites.php new file mode 100755 index 0000000..97e89cb --- /dev/null +++ b/examples/list_sites.php @@ -0,0 +1,46 @@ +set_debug($debug); +$loginresults = $unifi_connection->login(); +$data = $unifi_connection->list_sites(); + +/** + * we can render the full results in json format + */ +//echo json_encode($data, JSON_PRETTY_PRINT); + +/** + * or we print each site name and site id + */ +foreach ($data as $site) { + echo 'Site name: ' . $site->desc . ', site id: ' . $site->name . PHP_EOL; +} + +echo PHP_EOL; \ No newline at end of file diff --git a/examples/list_social_auth_details.php b/examples/list_social_auth_details.php index 7557ae3..8f9574f 100755 --- a/examples/list_social_auth_details.php +++ b/examples/list_social_auth_details.php @@ -3,20 +3,20 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example basic PHP script to pull Facebook social auth details from the UniFi controller and output - * them in basic HTML format + * description: example basic PHP script to pull Facebook social auth details from the UniFi controller and output + * them in basic HTML format */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * the site to use diff --git a/examples/list_user_stats.php b/examples/list_user_stats.php index 7d7feab..a4555e0 100755 --- a/examples/list_user_stats.php +++ b/examples/list_user_stats.php @@ -3,19 +3,19 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example basic PHP script to pull stats for s epcific user/client device from the UniFi controller and output in json format + * description: example basic PHP script to pull stats for s epcific user/client device from the UniFi controller and output in json format */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * the site to use diff --git a/examples/modify_smartpower_pdu_outlet.php b/examples/modify_smartpower_pdu_outlet.php index cedda41..07b33ba 100755 --- a/examples/modify_smartpower_pdu_outlet.php +++ b/examples/modify_smartpower_pdu_outlet.php @@ -12,7 +12,7 @@ require 'vendor/autoload.php'; * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * the site to use diff --git a/examples/reconnect_client.php b/examples/reconnect_client.php index bd8e32e..81d41d9 100755 --- a/examples/reconnect_client.php +++ b/examples/reconnect_client.php @@ -3,19 +3,19 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example basic PHP script to force a client device to reconnect + * description: example basic PHP script to force a client device to reconnect */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * the MAC address to reconnect diff --git a/examples/test_connection.php b/examples/test_connection.php index c9a824a..8de4653 100755 --- a/examples/test_connection.php +++ b/examples/test_connection.php @@ -3,7 +3,7 @@ * Test the connection to your UniFi controller * * contributed by: Art of WiFi - * description: PHP script to check/debug the connection to your controller using PHP and cURL + * description: PHP script to check/debug the connection to your controller using PHP and cURL */ /** @@ -11,7 +11,7 @@ * see the config.template.php file for an example. * (will only be used here to get the URL to the controller) */ -require_once('config.php'); +require_once 'config.php'; /** * Check whether the cURL module supports SSL diff --git a/examples/toggle_led.php b/examples/toggle_led.php index a43b816..2bec7d1 100755 --- a/examples/toggle_led.php +++ b/examples/toggle_led.php @@ -3,20 +3,20 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example to toggle the locate function (flashing LED) on an Access Point and - * output the response in json format + * description: example to toggle the locate function (flashing LED) on an Access Point and + * output the response in json format */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * site id to use diff --git a/examples/unblock_list.php b/examples/unblock_list.php index eef89d1..30d41ab 100755 --- a/examples/unblock_list.php +++ b/examples/unblock_list.php @@ -3,8 +3,8 @@ * PHP API usage example * * contributed by: @malcolmcif, based on another Art of WiFi example - * description: basic PHP script to unblock a list of mac addresses passed in via command line, - * output is to console in non json format + * description: basic PHP script to unblock a list of mac addresses passed in via command line, + * output is to console in non json format * * usage: * php unblock_list.php @@ -17,13 +17,13 @@ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; $debug = false; /** diff --git a/examples/update_ac-iw_ports.php b/examples/update_ac-iw_ports.php index ec6f8c8..f2c0c2f 100755 --- a/examples/update_ac-iw_ports.php +++ b/examples/update_ac-iw_ports.php @@ -3,21 +3,21 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example basic PHP script to update the port settings of an AC-IW device - * FYI: the AC-IW device has three ports, one for the wired uplink and two with external connectors - * note: requires controller version 5.5.X or higher (to be verified) + * description: example basic PHP script to update the port settings of an AC-IW device + * FYI: the AC-IW device has three ports, one for the wired uplink and two with external connectors + * note: requires controller version 5.5.X or higher (to be verified) */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * the site to use to log in to the controller diff --git a/examples/update_device_wlan_settings_5.5.X.php b/examples/update_device_wlan_settings_5.5.X.php index cd594de..ee07272 100755 --- a/examples/update_device_wlan_settings_5.5.X.php +++ b/examples/update_device_wlan_settings_5.5.X.php @@ -3,20 +3,20 @@ * PHP API usage example * * contributed by: Art of WiFi - * description: example basic PHP script to update WLAN settings of a device when using a controller version 5.5.X or higher - * where set_ap_radiosettings() throws an error + * description: example basic PHP script to update WLAN settings of a device when using a controller version 5.5.X or higher + * where set_ap_radiosettings() throws an error */ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * the site to use to log in to the controller diff --git a/examples/update_switch_poe-mode.php b/examples/update_switch_poe-mode.php index 83186b9..132479a 100755 --- a/examples/update_switch_poe-mode.php +++ b/examples/update_switch_poe-mode.php @@ -13,13 +13,13 @@ /** * using the composer autoloader */ -require_once('vendor/autoload.php'); +require_once 'vendor/autoload.php'; /** * include the config file (place your credentials etc. there if not already present) * see the config.template.php file for an example */ -require_once('config.php'); +require_once 'config.php'; /** * the site to use to log in to the controller diff --git a/src/Client.php b/src/Client.php index 3616a54..2c06235 100755 --- a/src/Client.php +++ b/src/Client.php @@ -12,7 +12,7 @@ namespace UniFi_API; * * @package UniFi_Controller_API_Client_Class * @author Art of WiFi - * @version Release: 1.1.63 + * @version Release: 1.1.64 * @license This class is subject to the MIT license that is bundled with this package in the file LICENSE.md * @example This directory in the package repository contains a collection of examples: * https://github.com/Art-of-WiFi/UniFi-API-client/tree/master/examples @@ -22,24 +22,25 @@ class Client /** * protected and private 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; - protected $is_unifi_os = false; - protected $exec_retries = 0; - protected $class_version = '1.1.63'; - private $cookies = ''; - private $request_type = 'GET'; - private $request_types_allowed = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']; - 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; + protected $baseurl = 'https://127.0.0.1:8443'; + protected $user = ''; + protected $password = ''; + protected $site = 'default'; + protected $version = '6.0.43'; + protected $debug = false; + protected $is_loggedin = false; + protected $is_unifi_os = false; + protected $exec_retries = 0; + protected $class_version = '1.1.64'; + private $cookies = ''; + private $headers = []; + private $request_method = 'GET'; + private $request_methods_allowed = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']; + 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 @@ -178,7 +179,7 @@ class Client /** * execute the cURL request and get the HTTP response code */ - $content = curl_exec($ch); + $response = curl_exec($ch); $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); if (curl_errno($ch)) { @@ -190,7 +191,7 @@ class Client print PHP_EOL . '-----------LOGIN-------------' . PHP_EOL; print_r(curl_getinfo($ch)); print PHP_EOL . '----------RESPONSE-----------' . PHP_EOL; - print $content; + print $response; print PHP_EOL . '-----------------------------' . PHP_EOL; print '' . PHP_EOL; } @@ -205,17 +206,17 @@ class Client return $http_code; } - $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE); - $headers = substr($content, 0, $header_size); - $body = trim(substr($content, $header_size)); + $response_header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE); + $response_headers = substr($response, 0, $response_header_size); + $response_body = trim(substr($response, $response_header_size)); curl_close($ch); /** * we are good to extract the cookies */ - if ($http_code >= 200 && $http_code < 400 && !empty($body)) { - preg_match_all('|Set-Cookie: (.*);|Ui', $headers, $results); + if ($http_code >= 200 && $http_code < 400 && !empty($response_body)) { + preg_match_all('|Set-Cookie: (.*);|Ui', $response_headers, $results); if (array_key_exists(1, $results)) { $this->cookies = implode(';', $results[1]); @@ -260,19 +261,16 @@ class Client /** * constuct HTTP request headers as required */ - $headers = ['content-length: 0']; - $logout_path = '/logout'; + $this->headers = ['content-length: 0']; + $logout_path = '/logout'; if ($this->is_unifi_os) { $logout_path = '/api/auth/logout'; $curl_options[CURLOPT_CUSTOMREQUEST] = 'POST'; - $csrf_token = $this->extract_csrf_token_from_cookie(); - if ($csrf_token) { - $headers[] = 'x-csrf-token: ' . $csrf_token; - } + $this->create_x_csrf_token_header(); } - $curl_options[CURLOPT_HTTPHEADER] = $headers; + $curl_options[CURLOPT_HTTPHEADER] = $this->headers; $curl_options[CURLOPT_URL] = $this->baseurl . $logout_path; curl_setopt_array($ch, $curl_options); @@ -1111,8 +1109,12 @@ class Client return false; } - $this->request_type = 'PUT'; - $payload = ['_id' => $client_id, 'use_fixedip' => $use_fixedip]; + $this->request_method = 'PUT'; + $payload = [ + '_id' => $client_id, + 'use_fixedip' => $use_fixedip + ]; + if ($use_fixedip) { if ($network_id) { $payload['network_id'] = $network_id; @@ -1163,7 +1165,7 @@ class Client */ public function edit_usergroup($group_id, $site_id, $group_name, $group_dn = -1, $group_up = -1) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; $payload = [ '_id' => $group_id, 'name' => $group_name, @@ -1183,7 +1185,7 @@ class Client */ public function delete_usergroup($group_id) { - $this->request_type = 'DELETE'; + $this->request_method = 'DELETE'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/usergroup/' . trim($group_id)); } @@ -1223,7 +1225,7 @@ class Client */ public function edit_apgroup($group_id, $group_name, $device_macs) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; $payload = [ '_id' => $group_id, 'attr_no_delete' => false, @@ -1242,7 +1244,7 @@ class Client */ public function delete_apgroup($group_id) { - $this->request_type = 'DELETE'; + $this->request_method = 'DELETE'; return $this->fetch_results_boolean('/v2/api/site/' . $this->site . '/apgroups/' . trim($group_id)); } @@ -1296,7 +1298,7 @@ class Client return false; } - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; $payload = [ '_id' => $group_id, 'name' => $group_name, @@ -1316,7 +1318,7 @@ class Client */ public function delete_firewallgroup($group_id) { - $this->request_type = 'DELETE'; + $this->request_method = 'DELETE'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/firewallgroup/' . trim($group_id)); } @@ -1523,7 +1525,7 @@ class Client */ public function set_site_country($country_id, $payload) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/country/' . trim($country_id), $payload); } @@ -1542,7 +1544,7 @@ class Client */ public function set_site_locale($locale_id, $payload) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/locale/' . trim($locale_id), $payload); } @@ -1558,7 +1560,7 @@ class Client */ public function set_site_snmp($snmp_id, $payload) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/snmp/' . trim($snmp_id), $payload); } @@ -1574,7 +1576,7 @@ class Client */ public function set_site_mgmt($mgmt_id, $payload) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/mgmt/' . trim($mgmt_id), $payload); } @@ -1590,7 +1592,7 @@ class Client */ public function set_site_guest_access($guest_access_id, $payload) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/guest_access/' . trim($guest_access_id), $payload); } @@ -1606,7 +1608,7 @@ class Client */ public function set_site_ntp($ntp_id, $payload) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/ntp/' . trim($ntp_id), $payload); } @@ -1622,7 +1624,7 @@ class Client */ public function set_site_connectivity($connectivity_id, $payload) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/connectivity/' . trim($connectivity_id), $payload); } @@ -1791,7 +1793,7 @@ class Client * Fetch controller status * * NOTES: in order to get useful results (e.g. controller version) you can call get_last_results_raw() - * immediately after this method + * immediately after this method. Login not required. * * @return bool true upon success (controller is online) */ @@ -2128,7 +2130,7 @@ class Client return false; } - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; $payload = ['disabled' => $disable]; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/device/' . trim($ap_id), $payload); @@ -2152,8 +2154,8 @@ class Client return false; } - $this->request_type = 'PUT'; - $payload = ['led_override' => $override_mode]; + $this->request_method = 'PUT'; + $payload = ['led_override' => $override_mode]; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/device/' . trim($device_id), $payload); } @@ -2428,7 +2430,7 @@ class Client */ public function set_dynamicdns($dynamicdns_id, $payload) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/dynamicdns/' . trim($dynamicdns_id), $payload); } @@ -2466,7 +2468,7 @@ class Client */ public function set_networksettings_base($network_id, $payload) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/networkconf/' . trim($network_id), $payload); } @@ -2479,7 +2481,7 @@ class Client */ public function delete_network($network_id) { - $this->request_type = 'DELETE'; + $this->request_method = 'DELETE'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/networkconf/' . trim($network_id)); } @@ -2577,7 +2579,7 @@ class Client */ public function set_wlansettings_base($wlan_id, $payload) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/wlanconf/' . trim($wlan_id), $payload); } @@ -2630,7 +2632,7 @@ class Client */ public function delete_wlan($wlan_id) { - $this->request_type = 'DELETE'; + $this->request_method = 'DELETE'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/wlanconf/' . trim($wlan_id)); } @@ -2703,7 +2705,8 @@ class Client /** * Count alarms * - * @param bool $archived if true all alarms are counted, if false only non-archived (active) alarms are counted + * @param bool $archived optional, if true all alarms are counted, if false only non-archived (active) alarms are counted, + * by default all alarms are counted * @return array containing the alarm count */ public function count_alarms($archived = null) @@ -2716,7 +2719,8 @@ class Client /** * Archive alarms(s) * - * @param string $alarm_id _id of the alarm to archive which can be found with the list_alarms() function, + * @param string $alarm_id optional, _id of the alarm to archive which can be found with the list_alarms() function, + * by default all alarms are archived * @return bool true on success */ public function archive_alarm($alarm_id = null) @@ -2823,7 +2827,8 @@ class Client /** * Fetch firmware versions * - * @param string $type "available" or "cached", determines which firmware types to return + * @param string $type optional, "available" or "cached", determines which firmware types to return, + * default value is "available" * @return array containing firmware versions */ public function list_firmware($type = 'available') @@ -2889,7 +2894,7 @@ class Client */ public function set_device_settings_base($device_id, $payload) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/device/' . trim($device_id), $payload); } @@ -2996,7 +3001,7 @@ class Client */ public function set_radius_account_base($account_id, $payload) { - $this->request_type = 'PUT'; + $this->request_method = 'PUT'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/account/' . trim($account_id), $payload); } @@ -3012,7 +3017,7 @@ class Client */ public function delete_radius_account($account_id) { - $this->request_type = 'DELETE'; + $this->request_method = 'DELETE'; return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/account/' . trim($account_id)); } @@ -3058,16 +3063,16 @@ 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! * - * @param string $path suffix of the URL (following the port number) to pass request to, *must* start with a "/" character - * @param string $request_type optional, HTTP request type, can be GET (default), POST, PUT, PATCH, or DELETE - * @param object|array $payload optional, stdClass object or associative array containing the payload to pass - * @param string $return optional, string; determines how to return results, when "boolean" the method must return a - * boolean result (true/false) or "array" when the method must return an array - * @return bool|array returns results as requested, returns false on incorrect parameters + * @param string $path suffix of the URL (following the port number) to pass request to, *must* start with a "/" character + * @param string $request_method optional, HTTP request type, can be GET (default), POST, PUT, PATCH, or DELETE + * @param object|array $payload optional, stdClass object or associative array containing the payload to pass + * @param string $return optional, string; determines how to return results, when "boolean" the method must return a + * boolean result (true/false) or "array" when the method must return an array + * @return bool|array returns results as requested, returns false on incorrect parameters */ - public function custom_api_request($path, $request_type = 'GET', $payload = null, $return = 'array') + public function custom_api_request($path, $request_method = 'GET', $payload = null, $return = 'array') { - if (!in_array($request_type, $this->request_types_allowed)) { + if (!in_array($request_method, $this->request_methods_allowed)) { return false; } @@ -3075,7 +3080,7 @@ class Client return false; } - $this->request_type = $request_type; + $this->request_method = $request_method; if ($return === 'array') { return $this->fetch_results($path, $payload); @@ -3310,6 +3315,7 @@ class Client * Get version of the Class * * @return string semver compatible version of this class + * https://semver.org/ */ public function get_class_version() { @@ -3331,29 +3337,29 @@ class Client } /** - * Get current request type + * Get current request method * * @return string request type */ - public function get_request_type() + public function get_request_method() { - return $this->request_type; + return $this->request_method; } /** - * Set request type + * Set request method * - * @param string $request_type a valid HTTP request type - * @return bool whether request was successful or not + * @param string $request_method a valid HTTP request method + * @return bool whether request was successful or not */ - public function set_request_type($request_type) + public function set_request_method($request_method) { - if (!in_array($request_type, $this->request_types_allowed)) { + if (!in_array($request_method, $this->request_methods_allowed)) { return false; } - $this->request_type = $request_type; + $this->request_method = $request_method; return true; } @@ -3388,7 +3394,6 @@ class Client return true; } - /** * Get value for cURL option CURLOPT_SSL_VERIFYHOST * @@ -3651,7 +3656,7 @@ class Client /** * Update the unificookie if sessions are enabled * - * @return bool true when unificookie was updated, else return false + * @return bool true when unificookie was updated, else returns false */ private function update_unificookie() { @@ -3672,11 +3677,11 @@ class Client } /** - * Extract the CSRF token from our Cookie string + * Add a header containing the CSRF token from our Cookie string * - * @return bool|string the CSRF token upon success or false when unable to extract the CSRF token + * @return bool true upon success or false when unable to extract the CSRF token */ - private function extract_csrf_token_from_cookie() + private function create_x_csrf_token_header() { if (!empty($this->cookies)) { $cookie_bits = explode('=', $this->cookies); @@ -3693,7 +3698,9 @@ class Client return false; } - return json_decode(base64_decode($jwt_payload))->csrfToken; + $this->headers[] = 'x-csrf-token: ' . json_decode(base64_decode($jwt_payload))->csrfToken; + + return true; } return false; @@ -3704,12 +3711,12 @@ class Client * * @param string $path path for the request * @param object|array $payload optional, payload to pass with the request - * @return bool|array response returned by the controller API + * @return bool|array response returned by the controller API, false upon error */ 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 (!in_array($this->request_method, $this->request_methods_allowed)) { + trigger_error('an invalid HTTP request type was used: ' . $this->request_method); } if (!($ch = $this->get_curl_resource())) { @@ -3718,11 +3725,7 @@ class Client return false; } - /** - * assigne default values to these vars - */ $json_payload = ''; - $headers = []; if ($this->is_unifi_os) { $url = $this->baseurl . '/proxy/network' . $path; @@ -3745,7 +3748,7 @@ class Client $curl_options[CURLOPT_POST] = true; $curl_options[CURLOPT_POSTFIELDS] = $json_payload; - $headers = [ + $this->headers = [ 'content-type: application/json', 'content-length: ' . strlen($json_payload) ]; @@ -3754,35 +3757,32 @@ class Client * we shouldn't be using GET (the default request type) or DELETE when passing a payload, * switch to POST instead */ - if ($this->request_type === 'GET' || $this->request_type === 'DELETE') { - $this->request_type = 'POST'; + if ($this->request_method === 'GET' || $this->request_method === 'DELETE') { + $this->request_method = 'POST'; } } - switch ($this->request_type) { - case 'DELETE': - $curl_options[CURLOPT_CUSTOMREQUEST] = 'DELETE'; - break; - case 'PATCH': - $curl_options[CURLOPT_CUSTOMREQUEST] = 'PATCH'; - break; + switch ($this->request_method) { case 'POST': $curl_options[CURLOPT_CUSTOMREQUEST] = 'POST'; break; + case 'DELETE': + $curl_options[CURLOPT_CUSTOMREQUEST] = 'DELETE'; + break; case 'PUT': $curl_options[CURLOPT_CUSTOMREQUEST] = 'PUT'; break; + case 'PATCH': + $curl_options[CURLOPT_CUSTOMREQUEST] = 'PATCH'; + break; } - if ($this->is_unifi_os && $this->request_type !== 'GET') { - $csrf_token = $this->extract_csrf_token_from_cookie(); - if ($csrf_token) { - $headers[] = 'x-csrf-token: ' . $csrf_token; - } + if ($this->is_unifi_os && $this->request_method !== 'GET') { + $this->create_x_csrf_token_header(); } - if (count($headers) > 0) { - $curl_options[CURLOPT_HTTPHEADER] = $headers; + if (count($this->headers) > 0) { + $curl_options[CURLOPT_HTTPHEADER] = $this->headers; } curl_setopt_array($ch, $curl_options); @@ -3790,7 +3790,7 @@ class Client /** * execute the cURL request */ - $content = curl_exec($ch); + $response = curl_exec($ch); if (curl_errno($ch)) { trigger_error('cURL error: ' . curl_error($ch)); } @@ -3858,7 +3858,7 @@ class Client } print PHP_EOL . '----------RESPONSE-----------' . PHP_EOL; - print $content; + print $response; print PHP_EOL . '-----------------------------' . PHP_EOL; print '' . PHP_EOL; } @@ -3866,11 +3866,11 @@ class Client curl_close($ch); /** - * set request_type value back to default, just in case + * set request_method value back to default, just in case */ - $this->request_type = 'GET'; + $this->request_method = 'GET'; - return $content; + return $response; } /**