API Browser version 1.0.20, API client class version 1.1.9

- API client class: changed trigger_error() to error_log() for an informative message to prevent Symphony catching it as an error and halting - API client class: modified stat_hourly_aps() and stat_daily_aps() functions/methods to allow pulling stats for a single device - API client class: added list_tags() function/method - API browser tool: added support for list_tags() function/method
Art-of-WiFi · Aug 11, 2017 · 01ccee7 · 01ccee7
1 parent 7ca99fd
commit 01ccee7
Show file tree

Hide file tree

Showing 5 changed files with 74 additions and 37 deletions.
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@ It comes bundled with **an extensive PHP class for access to the UniFi Controlle
 
 Please keep the following in mind:
 - not all data collections/API endpoints are supported (yet), see the list below of currently supported data collections/API endpoints
-- currently supports versions 4.x.x and 5.x.x of the UniFi Controller software (version 5.4.12 has been confirmed to work)
+- currently supports versions 4.x.x and 5.x.x of the UniFi Controller software (version 5.5.20 has been confirmed to work)
 - there is still work to be done to add/improve functionality and usability of this tool so suggestions/comments are welcome. Please use the github issue list or the Ubiquiti Community forums (https://community.ubnt.com/t5/UniFi-Wireless/UniFi-API-browser-tool-released/m-p/1392651) to share your ideas.
 - please read the Security Notice below before installing this tool!
 
@@ -40,6 +40,7 @@ The UniFi API browser tool offers the following features:
   - list devices (access points, USG routers and USW switches)
   - list wlan groups
   - list rogue access points
+  - list devices tags (supported on controller version 5.5.19 and higher)
 - Stats
   - hourly site stats
   - daily site stats
@@ -79,12 +80,12 @@ Please note that the bundled API client supports many more API endpoints, not al
 The PHP API client that comes bundled with this tool is based on the work done by the following developers:
 - domwo: http://community.ubnt.com/t5/UniFi-Wireless/little-php-class-for-unifi-api/m-p/603051
 - fbagnol: https://github.com/fbagnol/class.unifi.php
-- and the API as published by Ubiquiti: https://www.ubnt.com/downloads/unifi/5.4.14/unifi_sh_api
+- and the API as published by Ubiquiti: https://www.ubnt.com/downloads/unifi/5.5.20/unifi_sh_api
 
 Other included libraries:
-- Bootstrap (version 3.3.6) http://getbootstrap.com/
-- Font-awesome (version 4.5.0) https://fortawesome.github.io/Font-Awesome/
-- jQuery (version 2.2.0) https://jquery.com/
+- Bootstrap (version 3.3.7) http://getbootstrap.com/
+- Font-awesome (version 4.7.0) https://fortawesome.github.io/Font-Awesome/
+- jQuery (version 2.2.4) https://jquery.com/
 - jQuery JSONView (version 1.2.3) https://github.com/yesmeck/jquery-jsonview
 
 ### Requirements

diff --git a/examples/auth_guest_with_note.php b/examples/auth_guest_with_note.php
@@ -3,7 +3,7 @@
  * PHP API usage example
  *
  * contributed by: slooffmaster
- * description: example basic PHP script to auth a guest device and attach a note to it, this method would normally be used for offline authorization only!
+ * description: example basic PHP script to auth a guest device and attach a note to it
  */
 
 /**
@@ -25,14 +25,14 @@
 $duration = 2000;
 
 /**
- * the note to attach to the device
+ * The site to authorize the device with
  */
-$note = 'Note to attach to newly authorized device';
+$site_id = '<enter your site id here>';
 
 /**
- * The site to authorize the device with
+ * the note to attach to the device
  */
-$site_id = '<enter your site id here>';
+$note = 'Note to attach to newly authorized device';
 
 /**
  * load the Unifi API connection class and log in to the controller
@@ -43,22 +43,27 @@
 $loginresults   = $unifidata->login();
 
 /**
- * To add note to a new device we need to do the following before authorizing the device:
- * - first block the device to get an entry in the user collection
- * - get the device id from the user collection
- * - add note to the device
- * - then unblock the device again
+ * we authorize the device for the requested duration and attach the note to it's object
  */
-$block_result   = $unifidata->block_sta($mac);
-$getid_result   = $unifidata->stat_client($mac);
-$user_id        = $getid_result[0]->_id;
-$note_result    = $unifidata->set_sta_note($user_id, $note);
-$unblock_result = $unifidata->unblock_sta($mac);
+$auth_result  = $unifidata->authorize_guest($mac, $duration);
+$getid_result = $unifidata->stat_client($mac);
+$user_id      = $getid_result[0]->_id;
+$note_result  = $unifidata->set_sta_note($user_id, $note);
 
 /**
- * then we authorize the device for the requested duration
+ * When using older Controller versions (< 5.5.x) to attach a note to a new (unconnected) device, we instead need to take the
+ * following steps before authorizing the device:
+ * - first block the device to get an entry in the user collection
+ * - get the device id from the user collection
+ * - attach note to the device
+ * - then unblock the device again **after the authorization has taken place**
  */
-$auth_result = $unifidata->authorize_guest($mac, $duration);
+//$block_result   = $unifidata->block_sta($mac);
+//$getid_result   = $unifidata->stat_client($mac);
+//$user_id        = $getid_result[0]->_id;
+//$note_result    = $unifidata->set_sta_note($user_id, $note);
+//$unblock_result = $unifidata->unblock_sta($mac);
+//$auth_result    = $unifidata->authorize_guest($mac, $duration);
 
 /**
  * provide feedback in json format

diff --git a/index.php b/index.php
@@ -10,7 +10,7 @@
  *   the currently supported data collections/API endpoints in the README.md file
  * - this tool currently supports versions 4.x and 5.x of the UniFi Controller software
  *
- * VERSION: 1.0.19
+ * VERSION: 1.0.20
  *
  * ------------------------------------------------------------------------------------
  *
@@ -20,7 +20,7 @@
  * with this package in the file LICENSE.md
  *
  */
-define('API_BROWSER_VERSION', '1.0.19');
+define('API_BROWSER_VERSION', '1.0.20');
 
 /**
  * check whether the PHP curl module is available
@@ -349,6 +349,10 @@
             $selection = 'list devices';
             $data      = $unifidata->list_devices();
             break;
+        case 'list_tags':
+            $selection = 'list tags';
+            $data      = $unifidata->list_tags();
+            break;
         case 'list_wlan_groups':
             $selection = 'list wlan groups';
             $data      = $unifidata->list_wlan_groups();
@@ -694,6 +698,11 @@ function sites_sort($site_a, $site_b)
                             <li id="list_devices"><a href="?action=list_devices">list devices</a></li>
                             <li id="list_wlan_groups"><a href="?action=list_wlan_groups">list wlan groups</a></li>
                             <li id="list_rogueaps"><a href="?action=list_rogueaps">list rogue access points</a></li>
+                            <!-- all sites stats, only to be displayed when we have detected a capable controller version -->
+                            <?php if ($detected_controller_version != 'undetected' && version_compare($detected_controller_version, '5.5.0') >= 0) { ?>
+                                <li role="separator" class="divider"></li>
+                                <li id="list_tags"><a href="?action=list_tags">list tags</a></li>
+                            <?php } ?>
                         </ul>
                     </li>
                     <li id="stats-menu" class="dropdown">

diff --git a/phpapi/README.md b/phpapi/README.md
@@ -45,6 +45,7 @@ The class currently supports the following functions/methods to get/set data thr
 - list_self()
 - list_settings()
 - list_sites()
+- list_tags() (supported on controller version 5.5.19 and higher)
 - list_usergroups()
 - list_users()
 - list_wlan_groups()

diff --git a/phpapi/class.unifi.php b/phpapi/class.unifi.php
@@ -9,7 +9,7 @@
  * and the API as published by Ubiquiti:
  *    https://www.ubnt.com/downloads/unifi/5.3.8/unifi_sh_api
  *
- * VERSION: 1.1.8
+ * VERSION: 1.1.9
  *
  * NOTES:
  * - this class will only work with UniFi Controller versions 4.x and 5.x. There are no checks to prevent
@@ -34,7 +34,7 @@
  * with this package in the file LICENSE.md
  *
  */
-define('API_CLASS_VERSION', '1.1.8');
+define('API_CLASS_VERSION', '1.1.9');
 
 class UnifiApi
 {
@@ -401,43 +401,49 @@ public function stat_hourly_site($start = null, $end = null)
     }
 
     /**
-     * Hourly stats method for all access points
-     * -----------------------------------------
+     * Hourly stats method for a single access point or all access points
+     * ------------------------------------------------------------------
      * returns an array of hourly stats objects
      * optional parameter <start> = Unix timestamp in seconds
      * optional parameter <end>   = Unix timestamp in seconds
+     * optional parameter <mac>   = AP MAC address to return stats for
      *
      * NOTES:
      * - defaults to the past 7*24 hours
      * - UniFi controller does not keep these stats longer than 5 hours with versions < 4.6.6
      */
-    public function stat_hourly_aps($start = null, $end = null)
+    public function stat_hourly_aps($start = null, $end = null, $mac = null)
     {
         if (!$this->is_loggedin) return false;
         $end             = is_null($end) ? ((time())*1000) : $end;
         $start           = is_null($start) ? $end-(7*24*3600*1000) : $start;
-        $json            = json_encode(['attrs' => ['bytes', 'num_sta', 'time'], 'start' => $start, 'end' => $end]);
+        $json            = ['attrs' => ['bytes', 'num_sta', 'time'], 'start' => $start, 'end' => $end];
+        if (!is_null($mac)) $json['mac'] = $mac;
+        $json            = json_encode($json);
         $content_decoded = json_decode($this->exec_curl($this->baseurl.'/api/s/'.$this->site.'/stat/report/hourly.ap', 'json='.$json));
         return $this->process_response($content_decoded);
     }
 
     /**
-     * Daily stats method for all access points
-     * ----------------------------------------
+     * Daily stats method for a single access point or all access points
+     * -----------------------------------------------------------------
      * returns an array of daily stats objects
      * optional parameter <start> = Unix timestamp in seconds
      * optional parameter <end>   = Unix timestamp in seconds
+     * optional parameter <mac>   = AP MAC address to return stats for
      *
      * NOTES:
      * - defaults to the past 7*24 hours
      * - UniFi controller does not keep these stats longer than 5 hours with versions < 4.6.6
      */
-    public function stat_daily_aps($start = null, $end = null)
+    public function stat_daily_aps($start = null, $end = null, $mac = null)
     {
         if (!$this->is_loggedin) return false;
         $end             = is_null($end) ? ((time())*1000) : $end;
         $start           = is_null($start) ? $end-(7*24*3600*1000) : $start;
-        $json            = json_encode(['attrs' => ['bytes', 'num_sta', 'time'], 'start' => $start, 'end' => $end]);
+        $json            = ['attrs' => ['bytes', 'num_sta', 'time'], 'start' => $start, 'end' => $end];
+        if (!is_null($mac)) $json['mac'] = $mac;
+        $json            = json_encode($json);
         $content_decoded = json_decode($this->exec_curl($this->baseurl.'/api/s/'.$this->site.'/stat/report/daily.ap', 'json='.$json));
         return $this->process_response($content_decoded);
     }
@@ -685,6 +691,20 @@ public function list_devices($device_mac = null)
         return $this->process_response($content_decoded);
     }
 
+    /**
+     * List (device) tags
+     * ------------------
+     * returns an array of known device tag objects
+     *
+     * NOTES: this endpoint was introduced with controller versions 5.5.X
+     */
+    public function list_tags()
+    {
+        if (!$this->is_loggedin) return false;
+        $content_decoded = json_decode($this->exec_curl($this->baseurl.'/api/s/'.$this->site.'/rest/tag'));
+        return $this->process_response($content_decoded);
+    }
+
     /**
      * List rogue access points
      * ------------------------
@@ -1649,9 +1669,10 @@ private function exec_curl($url, $data = '')
          * has the session timed out?
          */
         $httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
-        $strerr = '{ "data" : [ ] , "meta" : { "msg" : "api.err.LoginRequired" , "rc" : "error"}}';
+        $strerr   = '{ "data" : [ ] , "meta" : { "msg" : "api.err.LoginRequired" , "rc" : "error"}}';
+
         if ($httpcode == 401 && strcmp($content, $strerr) == 0) {
-            trigger_error("cURL: Needed reconnect to UniFi Controller");
+            error_log('cURL: Needed reconnect to UniFi Controller');
 
             /**
              * explicit unset the old cookie now
@@ -1672,7 +1693,7 @@ private function exec_curl($url, $data = '')
                 /**
                  * setup the cookie for the user within $_SESSION
                  */
-                if (isset($have_cookie_in_use)) {
+                if (isset($have_cookie_in_use) && session_status() != PHP_SESSION_DISABLED) {
                     $_SESSION['unificookie'] = $this->cookies;
                     unset($have_cookie_in_use);
                 }