API client class v1.1.45

- added function/method force_provision(), contributed by @VWT-Dan
- added example update_switch_poe-mode.php, contributed by @Kaltt

examples/update_switch_poe-mode.php

@@ -0,0 +1,93 @@
+<?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
+     */
+    for($i = 0; $i < count($running_config); $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);

src/Client.php

@@ -73,7 +73,7 @@ class Client
             $this->version = trim($version);
         }
 
-        if ($ssl_verify === true) {
+        if ((boolean)$ssl_verify === true) {
             $this->curl_ssl_verify_peer = true;
             $this->curl_ssl_verify_host = 2;
         }
@@ -1381,6 +1381,27 @@ class Client
         return $this->process_response($response);
     }
 
+    /**
+     * Generate backup
+     * ---------------------------
+     * returns a URL from where the backup file can be downloaded once generated
+     *
+     * NOTES:
+     * this is an experimental function, please do not use unless you know exactly
+     * what you're doing
+     */
+    public function generate_backup()
+    {
+        if (!$this->is_loggedin) {
+            return false;
+        }
+
+        $payload  = ['cmd' => 'backup'];
+        $response = $this->exec_curl('/api/s/' . $this->site . '/cmd/backup', $payload);
+
+        return $this->process_response($response);
+    }
+
     /**
      * List auto backups
      * ---------------------------
@@ -2219,6 +2240,25 @@ class Client
         return $this->process_response_boolean($response);
     }
 
+    /**
+     * Force provision of a device
+     * ---------------------------
+     * return true on success
+     * required parameter <mac> = device MAC address
+     */
+    public function force_provision($mac)
+    {
+        if (!$this->is_loggedin) {
+            return false;
+        }
+
+        $payload  = ['mac' => strtolower($mac), 'cmd' => 'force-provision'];
+        $response = $this->exec_curl('/api/s/' . $this->site . '/cmd/devmgr', $payload);
+
+
+        return $this->process_response_boolean($response);
+    }
+
     /**
      * Reboot a UniFi CloudKey
      * -----------------------
@@ -3281,14 +3321,11 @@ class Client
     }
 
     /**
-     * Execute specific command
-     * ------------------------
+     * Execute specific stats command
+     * ------------------------------
      * return true on success
      * required parameter <command>  = string; command to execute, known valid values
      *                                 'reset-dpi': reset all DPI counters for the current site
-     *
-     * NOTE:
-     * the provided <command> parameter isn't validated so make sure you're using a correct value
      */
     public function cmd_stat($command)
     {
@@ -3296,6 +3333,10 @@ class Client
             return false;
         }
 
+        if (!in_array($command, ['reset-dpi'])) {
+            return false;
+        }
+
         $payload  = ['cmd' => trim($command)];
         $response = $this->exec_curl('/api/s/' . $this->site . '/cmd/stat', $payload);
 
@@ -3768,8 +3809,8 @@ class Client
      */
     private function check_site($site)
     {
-        if ($this->debug && strlen($site) !== 8 && $site !== 'default') {
-            error_log('The provided (short) site name is probably incorrect');
+        if ($this->debug && preg_match("/\s/", $site)) {
+            error_log('The provided (short) site name may not contain spaces');
         }
     }
 
@@ -3793,6 +3834,7 @@ class Client
         } else {
             $json_payload = '';
             $url          = $this->baseurl . $path;
+
             curl_setopt($ch, CURLOPT_URL, $url);
 
             if (!empty($payload)) {
@@ -3868,7 +3910,7 @@ class Client
             }
 
             if ($this->debug) {
-                print PHP_EOL . '<pre>';
+                print '<pre>';
                 print PHP_EOL . '---------cURL INFO-----------' . PHP_EOL;
                 print_r(curl_getinfo($ch));
                 print PHP_EOL . '-------URL & PAYLOAD---------' . PHP_EOL;
@@ -3882,7 +3924,7 @@ class Client
                 print PHP_EOL . '----------RESPONSE-----------' . PHP_EOL;
                 print $content;
                 print PHP_EOL . '-----------------------------' . PHP_EOL;
-                print '</pre>' . PHP_EOL;
+                print '</pre>';
             }
 
             curl_close($ch);