API client class v1.1.48

- applied several patches to Client.php as suggested by scrutinizer-ci.com
- moved resource checks to get_curl_resource() method/function
- extended create_user() function/method with several optional parameters
- changed headers that are passed with each request containing a payload

README.md

@@ -1,15 +1,21 @@
 ## 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.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).
+A PHP class that provides access to Ubiquiti's [**UniFi SDN Controller**](https://unifi-sdn.ui.com/) API, versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.12.35 has been confirmed to work) as well as UniFi OS-based controllers (version 5.12.59 has been confirmed to work). This class is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
 
-This class can be installed manually or using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
+The package can be installed manually or using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
 
 ## Requirements
 
-- 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.10 and cURL 7.58.0)
+- 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
 
-## Installation ##
+## 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.
+
+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.
 
@@ -169,7 +175,9 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
 - power_cycle_switch_port()
 - reconnect_sta()
 - rename_ap()
-- restart_ap()
+- restart_ap() (deprecated but still available as alias)
+- restart_device()
+- reboot_cloudkey()
 - revoke_voucher()
 - set_ap_radiosettings()
 - set_device_settings_base()
@@ -261,7 +269,7 @@ This class is based on the initial work by the following developers:
 
 and the API as published by Ubiquiti:
 
-- https://dl.ubnt.com/unifi/5.10.19/unifi_sh_api
+- https://dl.ui.com/unifi/5.12.35/unifi_sh_api
 
 ## Important Disclaimer
 

examples/ap_upgrade_firmware.php

@@ -3,7 +3,7 @@
  * PHP API usage example
  *
  * contributed by: @4oo4
- * description: example script to check and upgrade device firmware (can be scheduled with systemd/cron)
+ * description: example script to upgrade device firmware (can be scheduled with systemd/cron)
  *              to the most current version
  */
 require_once('vendor/autoload.php');

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'
+$controllerurl      = ''; // full url to the UniFi Controller, eg. 'https://22.22.11.11:8443', for UniFi OS-based
-$controllerversion  = ''; // the version of the Controller software, eg. '4.6.6' (must be at least 4.0.0)
+                          // 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/list_connected_users.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * 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
+ */
+/**
+ * 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 short name of the site which you wish to query
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller and pull the requested data
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login();
+$clients_array    = $unifi_connection->list_clients();
+
+/**
+ * output the results in JSON format
+ */
+header('Content-Type: application/json; charset=utf-8');
+echo json_encode($clients_array);

examples/reconnect_client.php

@@ -0,0 +1,45 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to force a client device to reconnect
+ */
+
+/**
+ * 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 MAC address to reconnect
+ */
+$mac_to_reconnect = '<MAC address>';
+
+/**
+ * site where the above MAC address is connected
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login();
+
+/**
+ * then we force the device to reconnect
+ */
+$reconnect_result = $unifi_connection->reconnect_sta($mac_to_reconnect);
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($reconnect_result, JSON_PRETTY_PRINT);

examples/update_switch_poe-mode.php

@@ -0,0 +1,94 @@
+<?php
+/**
+ * PHP API usage example to turn the PoE of the selected switch ports to "off" or "auto"
+ *
+ * contributed by: @Kaltt
+ * description:    A use case for this script is to turn off the PoE of the port where a camera is connected in order to turn off the camera
+ *
+ * usage:          If the file is called via a web URL, it should be called like: update_switch_poe-mode.php?poe_mode=off
+ *                 If the file is called via the command line, it should be called like: php update_switch_poe-mode.php off
+ *                 The values can be "off" or "auto"
+ */
+
+/**
+ * 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 = '<short site name of a site the credentials used have access to>';
+
+/**
+ * the MAC address of the AC-IW device to re-configure
+ */
+$device_mac = '<enter MAC address>';
+
+/**
+ * $lanports is an array that defines which ports should be changed
+ */
+$lanports = [6];
+
+/**
+ * This is the function that reads out the current port configuration and changes the value for the poe_mode for the ports defined in $lanports
+ */
+function update_ports($running_config, $ports, $poe_mode){
+    /**
+     * Update already non-default ports
+     */
+    $running_config_count = count($running_config);
+    for($i = 0; $i < $running_config_count; $i++){
+        if(in_array($running_config[$i]->port_idx, $ports)){
+            $running_config[$i]->poe_mode = $poe_mode;
+            unset($ports[array_search($running_config[$i]->port_idx, $ports)]);
+        }
+    }
+
+    $add_conf = [];
+    foreach($ports as $port){
+        $add_conf[] = [
+            'port_idx' => $port,
+            'poe_mode' => $poe_mode
+        ];
+    }
+
+    return array_merge($running_config, $add_conf);
+}
+
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion, false);
+$set_debug_mode   = $unifi_connection->set_debug(false);
+$loginresults     = $unifi_connection->login();
+$data             = $unifi_connection->list_devices($device_mac);
+$device_id        = $data[0]->device_id;
+$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'];
+} elseif (isset($argv[1])) {
+    $poe_mode = $argv[1];
+} else {
+    $poe_mode = 'auto';
+}
+
+$new_ports_config = [
+    'port_overrides' => update_ports($current_conf, $lanports, $poe_mode)
+];
+
+$update_device = $unifi_connection->set_device_settings_base($device_id, $new_ports_config);
+
+if (!$update_device) {
+    $error = $unifi_connection->get_last_results_raw();
+    echo json_encode($error, JSON_PRETTY_PRINT);
+}
+
+echo json_encode($update_device, JSON_PRETTY_PRINT);