API client class v1.1.37

updated both READMEs
added cmd_stat() function, can currently only be used to reset DPI counters for the current site
added optional group_id parameter to list_firewallgroups() which allows you to select a single firewall group, thanks to @VWT-Dan for the suggestion

README.md

@@ -1,6 +1,6 @@
 ## UniFi Controller API client class
 
-A PHP class which provides access to Ubiquiti's **UniFi Controller API**, versions 4.X.X and 5.X.X of the UniFi Controller software are supported (version 5.8.24 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 which provides access to Ubiquiti's **UniFi Controller API**, versions 4.X.X and 5.X.X of the UniFi Controller software are supported (version 5.9.29 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).
 
 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.
 
@@ -85,6 +85,7 @@ The class currently supports the following functions/methods to get/post/put/del
 - set_device_settings_base()
 - set_guestlogin_settings()
 - set_guestlogin_settings_base()
+- set_ips_settings_base() (supported on controller version 5.9.10 and higher)
 - set_locate_ap() (deprecated but still available as alias)
 - set_networksettings_base()
 - set_radius_account_base()
@@ -126,6 +127,7 @@ The class currently supports the following functions/methods to get/post/put/del
 - 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()
@@ -137,6 +139,7 @@ The class currently supports the following functions/methods to get/post/put/del
 - upgrade_device_external()
 - start_rolling_upgrade()
 - cancel_rolling_upgrade()
+- cmd_stat()
 
 Internal functions, getters/setters:
 

examples/README.md

@@ -9,6 +9,17 @@ Then update the contents of your new config.php with your controller details and
 
 Also make sure to update the path for the composer autoloader file (`vendor/autoload.php`) or the file containing the Class itself (`src/Client.php`) in your `require_once()` statement as required.
 
+#### Executing scripts from the CLI
+
+Most of the included example scripts can be run from the CLI or shell as follows after the necessary credentials and parameters have been added or updated:
+
+
+```sh
+$ php list_site_health.php
+```
+
+NOTE: this does require the `php-cli` module to be installed
+
 ### Contribute
 
 If you would like to share your own example file(s), please open an issue and include your code there or else create a pull request.

src/Client.php

@@ -428,7 +428,7 @@ class Client
             return false;
         }
 
-        $end        = is_null($end) ? ((time()) * 1000) : intval($end);
+        $end        = is_null($end) ? (time() * 1000) : intval($end);
         $start      = is_null($start) ? $end - (12 * 3600 * 1000) : intval($start);
         $attributes = [
             'bytes',
@@ -463,7 +463,7 @@ class Client
             return false;
         }
 
-        $end        = is_null($end) ? ((time()) * 1000) : intval($end);
+        $end        = is_null($end) ? (time() * 1000) : intval($end);
         $start      = is_null($start) ? $end - (7 * 24 * 3600 * 1000) : intval($start);
         $attributes = [
             'bytes',
@@ -536,7 +536,7 @@ class Client
             return false;
         }
 
-        $end   = is_null($end) ? ((time()) * 1000) : intval($end);
+        $end   = is_null($end) ? (time() * 1000) : intval($end);
         $start = is_null($start) ? $end - (12 * 3600 * 1000) : intval($start);
         $json  = ['attrs' => ['bytes', 'num_sta', 'time'], 'start' => $start, 'end' => $end];
         if (!is_null($mac)) {
@@ -567,7 +567,7 @@ class Client
             return false;
         }
 
-        $end   = is_null($end) ? ((time()) * 1000) : intval($end);
+        $end   = is_null($end) ? (time() * 1000) : intval($end);
         $start = is_null($start) ? $end - (7 * 24 * 3600 * 1000) : intval($start);
         $json  = ['attrs' => ['bytes', 'num_sta', 'time'], 'start' => $start, 'end' => $end];
         if (!is_null($mac)) {
@@ -597,7 +597,7 @@ class Client
             return false;
         }
 
-        $end   = is_null($end) ? ((time()) * 1000) : intval($end);
+        $end   = is_null($end) ? (time() * 1000) : intval($end);
         $start = is_null($start) ? $end - (7 * 24 * 3600 * 1000) : intval($start);
         $json  = ['attrs' => ['bytes', 'num_sta', 'time'], 'start' => $start, 'end' => $end];
         if (!is_null($mac)) {
@@ -634,7 +634,7 @@ class Client
             return false;
         }
 
-        $end      = is_null($end) ? ((time()) * 1000) : intval($end);
+        $end      = is_null($end) ? (time() * 1000) : intval($end);
         $start    = is_null($start) ? $end - (12 * 3600 * 1000) : intval($start);
         $attribs  = is_null($attribs) ? ['time', 'rx_bytes', 'tx_bytes'] : array_merge(['time'], $attribs);
         $json     = ['attrs' => $attribs, 'start' => $start, 'end' => $end, 'mac' => strtolower($mac)];
@@ -666,7 +666,7 @@ class Client
             return false;
         }
 
-        $end      = is_null($end) ? ((time()) * 1000) : intval($end);
+        $end      = is_null($end) ? (time() * 1000) : intval($end);
         $start    = is_null($start) ? $end - (7 * 24 * 3600 * 1000) : intval($start);
         $attribs  = is_null($attribs) ? ['time', 'rx_bytes', 'tx_bytes'] : array_merge(['time'], $attribs);
         $json     = ['attrs' => $attribs, 'start' => $start, 'end' => $end, 'mac' => strtolower($mac)];
@@ -698,7 +698,7 @@ class Client
             return false;
         }
 
-        $end      = is_null($end) ? ((time()) * 1000) : intval($end);
+        $end      = is_null($end) ? (time() * 1000) : intval($end);
         $start    = is_null($start) ? $end - (7 * 24 * 3600 * 1000) : intval($start);
         $attribs  = is_null($attribs) ? ['time', 'rx_bytes', 'tx_bytes'] : array_merge(['time'], $attribs);
         $json     = ['attrs' => $attribs, 'start' => $start, 'end' => $end, 'mac' => strtolower($mac)];
@@ -732,7 +732,7 @@ class Client
             return false;
         }
 
-        $end      = is_null($end) ? ((time()) * 1000) : intval($end);
+        $end      = is_null($end) ? (time() * 1000) : intval($end);
         $start    = is_null($start) ? $end - (12 * 3600 * 1000) : intval($start);
         $attribs  = is_null($attribs) ? ['time', 'mem', 'cpu', 'loadavg_5'] : array_merge(['time'], $attribs);
         $json     = json_encode(['attrs' => $attribs, 'start' => $start, 'end' => $end]);
@@ -762,7 +762,7 @@ class Client
             return false;
         }
 
-        $end      = is_null($end) ? ((time()) * 1000) : intval($end);
+        $end      = is_null($end) ? (time() * 1000) : intval($end);
         $start    = is_null($start) ? $end - (7 * 24 * 3600 * 1000) : intval($start);
         $attribs  = is_null($attribs) ? ['time', 'mem', 'cpu', 'loadavg_5'] : array_merge(['time'], $attribs);
         $json     = json_encode(['attrs' => $attribs, 'start' => $start, 'end' => $end]);
@@ -818,7 +818,7 @@ class Client
             return false;
         }
 
-        $end      = is_null($end) ? ((time()) * 1000) : intval($end);
+        $end      = is_null($end) ? (time() * 1000) : intval($end);
         $start    = is_null($start) ? $end - (24 * 3600 * 1000) : intval($start);
         $json     = ['attrs' => ['xput_download', 'xput_upload', 'latency', 'time'], 'start' => $start, 'end' => $end];
         $json     = json_encode($json);
@@ -827,6 +827,35 @@ class Client
         return $this->process_response($response);
     }
 
+    /**
+     * Method to fetch IPS/IDS event
+     * ----------------------------------
+     * returns an array of IPS/IDS event objects
+     * optional parameter <start> = Unix timestamp in milliseconds
+     * optional parameter <end>   = Unix timestamp in milliseconds
+     * optional parameter <limit> = Maximum number of events to return, defaults to 10000
+     *
+     * NOTES:
+     * - defaults to the past 24 hours
+     * - requires a USG
+     * - supported in UniFi controller versions 5.9.X and higher
+     */
+    public function stat_ips_events($start = null, $end = null, $limit = null)
+    {
+        if (!$this->is_loggedin) {
+            return false;
+        }
+
+        $end      = is_null($end) ? (time() * 1000) : intval($end);
+        $start    = is_null($start) ? $end - (24 * 3600 * 1000) : intval($start);
+        $limit    = is_null($limit) ? 10000 : intval($limit);
+        $json     = ['start' => $start, 'end' => $end, '_limit' => $limit];
+        $json     = json_encode($json);
+        $response = $this->exec_curl('/api/s/' . $this->site . '/stat/ips/event', 'json=' . $json);
+
+        return $this->process_response($response);
+    }
+
     /**
      * Show all login sessions
      * -----------------------
@@ -1068,12 +1097,12 @@ class Client
         }
 
         $this->request_type = 'POST';
-        $json               = json_encode([
+        $json = json_encode([
             'name'              => $group_name,
             'qos_rate_max_down' => intval($group_dn),
             'qos_rate_max_up'   => intval($group_up)
         ]);
-        $response           = $this->exec_curl('/api/s/' . $this->site . '/rest/usergroup', $json);
+        $response = $this->exec_curl('/api/s/' . $this->site . '/rest/usergroup', $json);
 
         return $this->process_response($response);
     }
@@ -1095,7 +1124,7 @@ class Client
         }
 
         $this->request_type = 'PUT';
-        $json               = json_encode([
+        $json = json_encode([
             '_id'               => $group_id,
             'name'              => $group_name,
             'qos_rate_max_down' => intval($group_dn),
@@ -1103,7 +1132,7 @@ class Client
             'site_id'           => $site_id
         ]);
 
-        $response           = $this->exec_curl('/api/s/' . $this->site . '/rest/usergroup/' . trim($group_id), $json);
+        $response = $this->exec_curl('/api/s/' . $this->site . '/rest/usergroup/' . trim($group_id), $json);
 
         return $this->process_response($response);
     }
@@ -1129,15 +1158,16 @@ class Client
     /**
      * List firewall groups (using REST)
      * ----------------------------------
-     * returns an array containing the current firewall groups on success
+     * returns an array containing the current firewall groups or the selected firewall group on success
+     * optional parameter <group_id> = id of the single firewall group to list
      */
-    public function list_firewallgroups()
+    public function list_firewallgroups($group_id = null)
     {
         if (!$this->is_loggedin) {
             return false;
         }
 
-        $response = $this->exec_curl('/api/s/' . $this->site . '/rest/firewallgroup');
+        $response = $this->exec_curl('/api/s/' . $this->site . '/rest/firewallgroup/' . trim($group_id));
 
         return $this->process_response($response);
     }
@@ -1162,12 +1192,12 @@ class Client
         }
 
         $this->request_type = 'POST';
-        $json               = json_encode([
+        $json = json_encode([
             'name'          => $group_name,
             'group_type'    => $group_type,
             'group_members' => $group_members
         ]);
-        $response           = $this->exec_curl('/api/s/' . $this->site . '/rest/firewallgroup', $json);
+        $response = $this->exec_curl('/api/s/' . $this->site . '/rest/firewallgroup', $json);
 
         return $this->process_response($response);
     }
@@ -1197,14 +1227,14 @@ class Client
         }
 
         $this->request_type = 'PUT';
-        $json               = json_encode([
+        $json = json_encode([
             '_id'           => $group_id,
             'name'          => $group_name,
             'group_type'    => $group_type,
             'group_members' => $group_members,
             'site_id'       => $site_id
         ]);
-        $response           = $this->exec_curl('/api/s/' . $this->site . '/rest/firewallgroup/' . trim($group_id),
+        $response = $this->exec_curl('/api/s/' . $this->site . '/rest/firewallgroup/' . trim($group_id),
             $json);
 
         return $this->process_response($response);
@@ -1228,6 +1258,22 @@ class Client
         return $this->process_response_boolean($response);
     }
 
+    /**
+     * List firewall rules (using REST)
+     * ----------------------------------
+     * returns an array containing the current firewall rules on success
+     */
+    public function list_firewallrules()
+    {
+        if (!$this->is_loggedin) {
+            return false;
+        }
+
+        $response = $this->exec_curl('/api/s/' . $this->site . '/rest/firewallrule');
+
+        return $this->process_response($response);
+    }
+
     /**
      * List health metrics
      * -------------------
@@ -2274,7 +2320,7 @@ class Client
             return false;
         }
 
-        $json     = json_encode([
+        $json = json_encode([
             'radio_table' => [
                 'radio'         => $radio,
                 'channel'       => $channel,
@@ -2344,7 +2390,7 @@ class Client
         if (!$this->is_loggedin) {
             return false;
         }
-        $json     = [
+        $json = [
             'portal_enabled'    => $portal_enabled,
             'portal_customized' => $portal_customized,
             'redirect_enabled'  => $redirect_enabled,
@@ -2365,7 +2411,7 @@ class Client
      * ------------------------------------------
      * return true on success
      * required parameter <network_settings> = stdClass object or associative array containing the configuration to apply to the guestlogin, must be a (partial)
-     *                                         object/array structured in the same manner as is returned by list_settings() for the guest_access.
+     *                                         object/array structured in the same manner as is returned by list_settings() for the "guest_access" section.
      */
     public function set_guestlogin_settings_base($guestlogin_settings)
     {
@@ -2379,6 +2425,25 @@ class Client
         return $this->process_response_boolean($response);
     }
 
+    /**
+     * Update IPS/IDS settings, base
+     * ------------------------------------------
+     * return true on success
+     * required parameter <ips_settings> = stdClass object or associative array containing the IPS/IDS settings to apply, must be a (partial)
+     *                                     object/array structured in the same manner as is returned by list_settings() for the "ips" section.
+     */
+    public function set_ips_settings_base($ips_settings)
+    {
+        if (!$this->is_loggedin) {
+            return false;
+        }
+
+        $json     = json_encode($ips_settings, JSON_UNESCAPED_SLASHES);
+        $response = $this->exec_curl('/api/s/' . $this->site . '/set/setting/ips', 'json=' . $json);
+
+        return $this->process_response_boolean($response);
+    }
+
     /**
      * Rename access point
      * -------------------
@@ -2725,7 +2790,7 @@ class Client
             return false;
         }
 
-        $json     = [
+        $json = [
             '_sort'  => '-time',
             'within' => intval($historyhours),
             'type'   => null,
@@ -3117,6 +3182,28 @@ class Client
         return $this->process_response_boolean($response);
     }
 
+    /**
+     * Execute specific 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)
+    {
+        if (!$this->is_loggedin) {
+            return false;
+        }
+
+        $json     = json_encode(['cmd' => trim($command)]);
+        $response = $this->exec_curl('/api/s/' . $this->site . '/cmd/stat', 'json=' . $json);
+
+        return $this->process_response_boolean($response);
+    }
+
     /****************************************************************
      * "Aliases" for deprecated functions from here, to support
      * backward compatibility: