API client class v1.1.58

- changed several references from UniFi SDN controller to UniFi Network controller
- added optional payload parameter to the list_alarms() method/function, contributed by @MikeSiekkinen through PR #68
- added example showing how to disable/enable a UniFi switch port
- updated restart_device() function/method, thanks go to @leonardogyn for reporting this
- added example to modify outlet settings on a UniFi SmartPower PDU Pro, thanks go to @panthergm for providing access

README.md

@@ -1,17 +1,21 @@
 ## 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 Network Controller**](https://unifi-network.ui.com/) API, versions 4.X.X and 5.X.X of the UniFi Network 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).
 
-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
 
-- a web server with PHP and cURL modules installed (tested on Apache 2.4 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.2.24 and cURL 7.58.0)
-- network connectivity between this web server and the server and port (normally TCP port 8443) where the UniFi Controller is running
+- a server with PHP, version 5.5.0 or higher, and the PHP cURL module installed (tested on Apache 2.4 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.2.24 and cURL 7.58.0)
+- direct network connectivity between this server and the host and port (normally TCP port 8443) where the UniFi Controller is running
+- you must use **local accounts**, not UniFi Cloud accounts, to access the UniFi Controller API through this class
 
-## UniFi OS Support
 
-Currently, UniFi OS-based controllers (UniFi Dream Machine Pro) are **not supported** due to several breaking changes to the API.
+## UbiOS Support
+
+Support for UbiOS-based controllers (UniFi Dream Machine Pro) has been added as of version 1.1.47. The class automatically detects UbiOS 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 UbiOS-based controller.
+
+Please test all methods you plan on using thoroughly before using the API Client with UbiOS devices in a production environment.
 
 ## Installation
 
@@ -19,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:
 
@@ -88,7 +92,7 @@ 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 Network Controller. For example with this URL:
 
    `https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard`
 
@@ -98,22 +102,26 @@ Please refer to the `examples/` directory for some more detailed examples which
 
 ## Functions/methods supported
 
-The class currently supports the following functions/methods to GET/POST/PUT/DELETE data through the UniFi Controller API. Please refer to the source code for more details on the functions/methods and their respective parameters.
+The class currently supports the following functions/methods to GET/POST/PUT/DELETE data through the UniFi Controller API. Please refer to the comments in the source code for more details on the functions/methods and their respective parameters.
 
 - login()
 - 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()
@@ -131,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()
@@ -149,6 +155,7 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
 - list_events()
 - list_extension()
 - list_firewallgroups()
+- list_firmware()
 - list_guests()
 - list_health()
 - list_hotspotop()
@@ -160,6 +167,7 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
 - list_radius_accounts() (supported on controller version 5.5.19 and higher)
 - list_radius_profiles()
 - list_rogueaps()
+- list_routing()
 - list_self()
 - list_settings()
 - list_sites()
@@ -171,14 +179,17 @@ 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_element_adoption() (supported on controller version 5.13.X and higher)
 - set_guestlogin_settings()
 - set_guestlogin_settings_base()
 - set_ips_settings_base() (supported on controller version 5.9.10 and higher)
@@ -193,11 +204,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()
@@ -207,26 +218,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()
@@ -236,19 +248,30 @@ 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()
 
-Internal functions, getters/setters:
+Other functions, getters/setters:
 
-- set_debug()
+- get_class_version()
+- get_connection_timeout()
+- get_cookie() (renamed from getcookie(), deprecated but still available, use get_cookies() instead)
+- get_cookies()
 - get_debug()
-- set_site()
-- get_site()
-- get_cookie() (renamed from getcookie())
-- get_last_results_raw()
+- 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?
 

composer.json

@@ -1,27 +1,28 @@
 {
-    "name": 		"art-of-wifi/unifi-api-client",
-    "type": 		"library",
-    "description": 	"API client class for use with Ubiquiti's UniFi controller",
+    "name":        "art-of-wifi/unifi-api-client",
+    "type":        "library",
+    "description": "API client class for use with Ubiquiti's UniFi controller",
     "keywords": [
-		"ubnt",
-		"ubiquiti",
-		"unifi",
-		"controller",
-		"api",
-		"client"
-	],
-    "homepage": 	"https://github.com/Art-of-WiFi/UniFi-API-client",
-    "license": 		"MIT",
+        "ubnt",
+        "ubiquiti",
+        "unifi",
+        "controller",
+        "api",
+        "client"
+    ],
+    "homepage":    "https://github.com/Art-of-WiFi/UniFi-API-client",
+    "license":     "MIT",
     "authors": [
         {
-            "name": 	"Art of WiFi",
-            "email": 	"info@artofowifi.net",
+            "name":     "Art of WiFi",
+            "email":    "info@artofowifi.net",
             "homepage": "http://artofwifi.net"
         }
     ],
     "require": {
-        "php": ">=5.4.0",
-		"ext-curl": "*"
+        "php": ">=5.5.0",
+        "ext-curl": "*",
+        "ext-json": "*"
     },
     "autoload": {
         "psr-4": {

examples/block_list.php

@@ -47,7 +47,7 @@ $unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $
 $set_debug_mode   = $unifi_connection->set_debug($debug);
 $loginresults     = $unifi_connection->login(); // always true regardless of site id
 
-foreach ($macs_to_block as &$mac) {
+foreach ($macs_to_block as $mac) {
     // block_result is always true even if mac address does not exist :(
     $block_result = $unifi_connection->block_sta($mac);
 

examples/config.template.php

@@ -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

examples/disable_switch_port.php

@@ -0,0 +1,78 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description:    example PHP script to disable/enable the port of a UniFi switch
+ * note:           Requires controller version 5.5.X or higher. This example assumes an override alreay exists for the desired port.
+ *                 To create a new port override simply append one (similar in structure to $updated_override) as needed to the
+ *                 $existing_overrides array
+ */
+
+/**
+ * using the composer autoloader
+ */
+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');
+
+/**
+ * the site to use to log in to the controller
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * the MAC address of the UniFi switch to re-configure
+ */
+$device_mac = '<enter MAC address>';
+
+/**
+ * index of port to modify/add
+ */
+$port_idx = 24;
+
+/**
+ * port configuration id to apply when enabling/disabling the port
+ *
+ * NOTE:
+ * port configurations are available through list_portconf()
+ */
+$port_conf_id = '<enter _id value of desired port configuration>';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller and do our thing
+ */
+$unifi_connection   = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, false);
+$set_debug_mode     = $unifi_connection->set_debug($debug);
+$loginresults       = $unifi_connection->login();
+$data               = $unifi_connection->list_devices($device_mac);
+$device_id          = $data[0]->device_id;
+$existing_overrides = $data[0]->port_overrides;
+
+foreach ($existing_overrides as $key => $value) {
+    if (!empty($value->port_idx) && $value->port_idx === $port_idx) {
+        $updated_override = [
+            'portconf_id' => $port_conf_id,
+            'port_idx'    => $port_idx,
+            'poe_mode'    => $value->poe_mode,
+            'name'        => 'Your-port-name',
+        ];
+
+        $existing_overrides[$key] = $updated_override;
+    }
+}
+
+$payload = [
+    'port_overrides' => $existing_overrides
+];
+
+$update_device = $unifi_connection->set_device_settings_base($device_id, $payload);
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($update_device, JSON_PRETTY_PRINT);

examples/modify_smartpower_pdu_outlet.php

@@ -0,0 +1,84 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description:    example basic PHP script to toggle power of an outlet on the UniFi SmartPower PDU Pro,
+ *                 last tested with UniFi controller version 6.1.19
+ */
+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');
+
+/**
+ * the site to use
+ */
+$site_id = 'default';
+
+/**
+ * MAC of UniFi SmartPower PDU Pro to work with
+ */
+$pdu_mac = '<MAC ADDRESS of PDU>';
+
+/**
+ * index value of the outlet to modify
+ */
+$outlet_idx = 20;
+
+/**
+ * new values for relay_state (enable/disable Power) and cycle_enabled (disable/enable Modem Power Cycle) for the above outlet,
+ * values must be boolean (true/false)
+ *
+ * NOTES:
+ * - here you can choose to also change the name of the outlet
+ * - outlet overrides are structured like this:
+ *    {
+ *        "index": 1,
+ *        "name": "USB Outlet 1",
+ *        "cycle_enabled": false,
+ *        "relay_state": true
+ *    }
+ */
+$new_relay_state   = true;
+$new_cycle_enabled = false;
+
+/**
+ * initialize the UniFi API connection class and log in to the controller and do our thing
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login();
+if ($loginresults) {
+    $pdu_details = $unifi_connection->list_devices($pdu_mac);
+
+    if (!empty($pdu_details) && property_exists($pdu_details[0], 'model') && $pdu_details[0]->model === 'USPPDUP' && property_exists($pdu_details[0], 'outlet_overrides')) {
+        $device_id        = $pdu_details[0]->_id;
+        $outlet_overrides = $pdu_details[0]->outlet_overrides;
+
+        foreach ($outlet_overrides as $key => $value) {
+            if ($value->index === $outlet_idx) {
+                $outlet_overrides[$key]->relay_state   = $new_relay_state;
+                $outlet_overrides[$key]->cycle_enabled = $new_cycle_enabled;
+            }
+        }
+
+        $pdu_update = $unifi_connection->set_device_settings_base($device_id, ['outlet_overrides' => $outlet_overrides]);
+
+        /**
+         * provide feedback in json format
+         */
+        echo 'results:' . PHP_EOL . PHP_EOL;
+        echo json_encode($pdu_update, JSON_PRETTY_PRINT);
+        echo PHP_EOL;
+    } else {
+        echo 'not a PDU device?';
+        echo PHP_EOL;
+    }
+} else {
+    echo 'we encountered a login error!';
+    echo PHP_EOL;
+}

examples/test_connection.php

@@ -17,7 +17,7 @@ require_once('config.php');
  * Check whether the cURL module supports SSL
  */
 if (!curl_version()['features'] & CURL_VERSION_SSL) {
-    print 'SSL is not supported with this cURL installation!' . PHP_EOL;
+    print PHP_EOL . 'SSL is not supported with this cURL installation!' . PHP_EOL;
 }
 
 /**
@@ -25,44 +25,48 @@ if (!curl_version()['features'] & CURL_VERSION_SSL) {
  */
 $ch = curl_init();
 
-/**
- * Set the required cURL options
- */
-curl_setopt($ch, CURLOPT_URL, $controllerurl);
-curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
-curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
-curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
+if (is_resource($ch)) {
+    /**
+     * If we have a resource, we proceed and set the required cURL options
+     */
+    curl_setopt($ch, CURLOPT_URL, $controllerurl);
+    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
+    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
+    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
 
-/**
- * This cURL option can have a value of 0-6
- * see this URL for more details:
- * http://php.net/manual/en/function.curl-setopt.php
- * 0 is the default value and is used by the PHP API client class
- */
-curl_setopt($ch, CURLOPT_SSLVERSION, 0);
+    /**
+     * This cURL option can have a value of 0-6
+     * see this URL for more details:
+     * http://php.net/manual/en/function.curl-setopt.php
+     * 0 is the default value and is used by the PHP API client class
+     */
+    curl_setopt($ch, CURLOPT_SSLVERSION, 0);
 
-/**
- * Be more verbose
- */
-curl_setopt($ch, CURLOPT_VERBOSE, true);
+    /**
+     * Be more verbose
+     */
+    curl_setopt($ch, CURLOPT_VERBOSE, true);
 
-/**
- * $results contains the output as returned by the cURL request,
- * returns true when successful, else returns false
- */
-print 'verbose output from the cURL request:' . PHP_EOL;
-$results = curl_exec($ch);
+    /**
+     * $results contains the output as returned by the cURL request,
+     * returns true when successful, else returns false
+     */
+    print PHP_EOL . 'verbose output from the cURL request:' . PHP_EOL;
+    $results = curl_exec($ch);
 
-print PHP_EOL . 'curl_getinfo output:' . PHP_EOL;
-print_r(curl_getinfo($ch));
+    print PHP_EOL . 'curl_getinfo output:' . PHP_EOL;
+    print_r(curl_getinfo($ch));
 
-/**
- * If we receive a cURL error, output it before the results
- */
-if (curl_errno($ch)) {
-    print PHP_EOL . 'cURL error: ' . curl_error($ch) . PHP_EOL;
+    /**
+     * If we receive a cURL error, output it before the results
+     */
+    if (curl_errno($ch)) {
+        print PHP_EOL . 'cURL error: ' . curl_error($ch) . PHP_EOL;
+    }
+
+    print PHP_EOL . '$results:' . PHP_EOL;
+    print_r($results);
+    print PHP_EOL;
+} else {
+    print PHP_EOL . 'ERROR: cURL could not be initialized!' . PHP_EOL;
 }
-
-print PHP_EOL . '$results:' . PHP_EOL;
-print_r($results);
-print PHP_EOL;

examples/update_switch_poe-mode.php

@@ -72,8 +72,8 @@ $current_conf     = $data[0]->port_overrides;
 /**
  * This reads in the values provided via URL or in the command line, if nothing is set than it will poe_mode will be set to "auto"
  */
-if (isset($_GET[$poe_mode])) {
-    $poe_mode = $_GET[poe_mode];
+if (isset($_GET['poe_mode'])) {
+    $poe_mode = $_GET['poe_mode'];
 } elseif (isset($argv[1])) {
     $poe_mode = $argv[1];
 } else {