API client class v1.1.62

- added several monthly stats methods: `stat_monthly_gateway()`, `stat_monthly_site()`, `stat_monthly_aps()`, `stat_monthly_user()`, thanks go to @Roel Janssens for spotting these MongoDB collections - test for `object` or `resource` in `get_curl_resource()`, closes PR #82 submitted by @banakito - applied change to comments in `example/modify_smartpower_pdu_outlet.php` based on a suggestion by @thesohoguy - removed unnecessary variable from `list_apgroups()`, thanks go to Stephen Davies for reporting - added an optional parameter $ap_group_ids to the `create_wlan()` function/method for UniFi controller versions 6.0.X and higher, thanks go to Stephen Davies for contributing
Art-of-WiFi · Dec 10, 2020 · c82481a · c82481a
1 parent 2c74356
commit c82481a
Show file tree

Hide file tree

Showing 3 changed files with 129 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -249,6 +249,10 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
 - stat_status()
 - stat_sysinfo()
 - stat_voucher()
+- stat_monthly_aps()
+- stat_monthly_gateway()
+- stat_monthly_site()
+- stat_monthly_user()
 - unauthorize_guest()
 - unblock_sta()
 - unset_locate_ap() (deprecated but still available as alias)

diff --git a/examples/modify_smartpower_pdu_outlet.php b/examples/modify_smartpower_pdu_outlet.php
@@ -55,6 +55,9 @@
 if ($loginresults) {
     $pdu_details = $unifi_connection->list_devices($pdu_mac);
 
+    /**
+     * change the model below from USPPDUP to UP1 when using a USP-Plug (thanks to @thesohoguy for contributing this)
+     */
     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;

diff --git a/src/Client.php b/src/Client.php
@@ -12,7 +12,7 @@
  *
  * @package UniFi Controller API client class
  * @author  Art of WiFi <[email protected]>
- * @version 1.1.61
+ * @version 1.1.62
  * @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
@@ -31,7 +31,7 @@ class Client
     protected $is_loggedin         = false;
     protected $is_unifi_os         = false;
     protected $exec_retries        = 0;
-    protected $class_version       = '1.1.61';
+    protected $class_version       = '1.1.62';
     private $cookies               = '';
     private $request_type          = 'GET';
     private $request_types_allowed = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
@@ -564,6 +564,36 @@ public function stat_daily_site($start = null, $end = null)
         return $this->fetch_results('/api/s/' . $this->site . '/stat/report/daily.site', $payload);
     }
 
+    /**
+     * Fetch monthly site stats
+     *
+     * NOTES:
+     * - defaults to the past 52 weeks (52*7*24 hours)
+     * - "bytes" are no longer returned with controller version 4.9.1 and later
+     *
+     * @param  int   $start optional, Unix timestamp in milliseconds
+     * @param  int   $end   optional, Unix timestamp in milliseconds
+     * @return array        returns an array of monthly stats objects for the current site
+     */
+    public function stat_monthly_site($start = null, $end = null)
+    {
+        $end     = empty($end) ? (time() - (time() % 3600)) * 1000 : intval($end);
+        $start   = empty($start) ? $end - (52 * 7 * 24 * 3600 * 1000) : intval($start);
+        $attribs = [
+            'bytes',
+            'wan-tx_bytes',
+            'wan-rx_bytes',
+            'wlan_bytes',
+            'num_sta',
+            'lan-num_sta',
+            'wlan-num_sta',
+            'time'
+        ];
+        $payload = ['attrs' => $attribs, 'start' => $start, 'end' => $end];
+
+        return $this->fetch_results('/api/s/' . $this->site . '/stat/report/monthly.site', $payload);
+    }
+
     /**
      * Fetch 5 minutes stats for a single access point or all access points
      *
@@ -646,6 +676,33 @@ public function stat_daily_aps($start = null, $end = null, $mac = null)
         return $this->fetch_results('/api/s/' . $this->site . '/stat/report/daily.ap', $payload);
     }
 
+    /**
+     * Fetch monthly stats for a single access point or all access points
+     *
+     * NOTES:
+     * - defaults to the past 52 weeks (52*7*24 hours)
+     * - make sure that the retention policy for hourly stats is set to the correct value in
+     *   the controller settings
+     *
+     * @param  int    $start optional, Unix timestamp in milliseconds
+     * @param  int    $end   optional, Unix timestamp in milliseconds
+     * @param  string $mac   optional, AP MAC address to return stats for, when empty,
+     *                       stats for all APs are returned
+     * @return array         returns an array of monthly stats objects
+     */
+    public function stat_monthly_aps($start = null, $end = null, $mac = null)
+    {
+        $end     = empty($end) ? time() * 1000 : intval($end);
+        $start   = empty($start) ? $end - (52 * 7 * 24 * 3600 * 1000) : intval($start);
+        $attribs = ['bytes', 'num_sta', 'time'];
+        $payload = ['attrs' => $attribs, 'start' => $start, 'end' => $end];
+        if (!empty($mac)) {
+            $payload['mac'] = strtolower($mac);
+        }
+
+        return $this->fetch_results('/api/s/' . $this->site . '/stat/report/monthly.ap', $payload);
+    }
+
     /**
      * Fetch 5 minutes stats for a single user/client device
      *
@@ -730,6 +787,34 @@ public function stat_daily_user($mac, $start = null, $end = null, $attribs = nul
         return $this->fetch_results('/api/s/' . $this->site . '/stat/report/daily.user', $payload);
     }
 
+    /**
+     * Fetch monthly stats for a single user/client device
+     *
+     * NOTES:
+     * - defaults to the past 13 weeks (52*7*24 hours)
+     * - only supported with UniFi controller versions 5.8.X and higher
+     * - make sure that the retention policy for monthly stats is set to the correct value in
+     *   the controller settings
+     * - make sure that "Clients Historical Data" has been enabled in the UniFi controller settings in the Maintenance section
+     *
+     * @param  string $mac     MAC address of user/client device to return stats for
+     * @param  int    $start   optional, Unix timestamp in milliseconds
+     * @param  int    $end     optional, Unix timestamp in milliseconds
+     * @param  array  $attribs array containing attributes (strings) to be returned, valid values are:
+     *                         rx_bytes, tx_bytes, signal, rx_rate, tx_rate, rx_retries, tx_retries, rx_packets, tx_packets
+     *                         default is ['rx_bytes', 'tx_bytes']
+     * @return array           returns an array of monthly stats objects
+     */
+    public function stat_monthly_user($mac, $start = null, $end = null, $attribs = null)
+    {
+        $end     = empty($end) ? time() * 1000 : intval($end);
+        $start   = empty($start) ? $end - (13 * 7 * 24 * 3600 * 1000) : intval($start);
+        $attribs = empty($attribs) ? ['time', 'rx_bytes', 'tx_bytes'] : array_merge(['time'], $attribs);
+        $payload = ['attrs' => $attribs, 'start' => $start, 'end' => $end, 'mac' => strtolower($mac)];
+
+        return $this->fetch_results('/api/s/' . $this->site . '/stat/report/monthly.user', $payload);
+    }
+
     /**
      * Fetch 5 minutes gateway stats
      *
@@ -787,7 +872,7 @@ public function stat_hourly_gateway($start = null, $end = null, $attribs = null)
      * Fetch daily gateway stats
      *
      * NOTES:
-     * - defaults to the past 52*7*24 hours
+     * - defaults to the past 52 weeks (52*7*24 hours)
      * - requires a USG
      *
      * @param  int   $start   optional, Unix timestamp in milliseconds
@@ -808,6 +893,31 @@ public function stat_daily_gateway($start = null, $end = null, $attribs = null)
         return $this->fetch_results('/api/s/' . $this->site . '/stat/report/daily.gw', $payload);
     }
 
+    /**
+     * Fetch monthly gateway stats
+     *
+     * NOTES:
+     * - defaults to the past 52 weeks (52*7*24 hours)
+     * - requires a USG
+     *
+     * @param  int   $start   optional, Unix timestamp in milliseconds
+     * @param  int   $end     optional, Unix timestamp in milliseconds
+     * @param  array $attribs array containing attributes (strings) to be returned, valid values are:
+     *                        mem, cpu, loadavg_5, lan-rx_errors, lan-tx_errors, lan-rx_bytes,
+     *                        lan-tx_bytes, lan-rx_packets, lan-tx_packets, lan-rx_dropped, lan-tx_dropped
+     *                        default is ['time', 'mem', 'cpu', 'loadavg_5']
+     * @return array          returns an array of monthly stats objects for the gateway belonging to the current site
+     */
+    public function stat_monthly_gateway($start = null, $end = null, $attribs = null)
+    {
+        $end     = empty($end) ? (time() - (time() % 3600)) * 1000 : intval($end);
+        $start   = empty($start) ? $end - (52 * 7 * 24 * 3600 * 1000) : intval($start);
+        $attribs = empty($attribs) ? ['time', 'mem', 'cpu', 'loadavg_5'] : array_merge(['time'], $attribs);
+        $payload = ['attrs' => $attribs, 'start' => $start, 'end' => $end];
+
+        return $this->fetch_results('/api/s/' . $this->site . '/stat/report/monthly.gw', $payload);
+    }
+
     /**
      * Fetch speed test results
      *
@@ -1085,7 +1195,7 @@ public function delete_usergroup($group_id)
      */
     public function list_apgroups()
     {
-        return $this->fetch_results('/v2/api/site/' . $this->site . '/apgroups/' . trim($group_id));
+        return $this->fetch_results('/v2/api/site/' . $this->site . '/apgroups');
     }
 
     /**
@@ -2405,6 +2515,7 @@ public function list_wlanconf($wlan_id = null)
      * @param  boolean $uapsd_enabled    optional, enable/disable Unscheduled Automatic Power Save Delivery
      * @param  boolean $schedule_enabled optional, enable/disable wlan schedule
      * @param  array   $schedule         optional, schedule rules
+     * @param  array   $ap_group_ids     optional, array of ap group ids, required for UniFi controller versions 6.0.X and higher
      * @return bool                      true on success
      */
     public function create_wlan(
@@ -2422,7 +2533,8 @@ public function create_wlan(
         $vlan             = null,
         $uapsd_enabled    = false,
         $schedule_enabled = false,
-        $schedule         = []
+        $schedule         = [],
+        $ap_group_ids     = null
     ) {
         $payload = [
             'name'             => $name,
@@ -2448,6 +2560,10 @@ public function create_wlan(
             $payload['x_passphrase'] = $x_passphrase;
         }
 
+        if (!empty($ap_group_ids) && is_array($ap_group_ids)) {
+            $payload['ap_group_ids'] = $ap_group_ids;
+        }
+
         return $this->fetch_results_boolean('/api/s/' . $this->site . '/add/wlanconf', $payload);
     }
 
@@ -3583,9 +3699,6 @@ private function extract_csrf_token_from_cookie()
         return false;
     }
 
-    /**
-     */
-
     /**
      * Execute the cURL request
      *
@@ -3764,7 +3877,7 @@ protected function exec_curl($path, $payload = null)
     protected function get_curl_resource()
     {
         $ch = curl_init();
-        if (is_resource($ch)) {
+        if (is_object($ch) || is_resource($ch)) {
             $curl_options = [
                 CURLOPT_SSL_VERIFYPEER => $this->curl_ssl_verify_peer,
                 CURLOPT_SSL_VERIFYHOST => $this->curl_ssl_verify_host,