UniFi API browser 2.0.0

major overhaul to support Bootstrap 4 and to switch to AJAX for data transfer between server and browser
added user authentication
many more features

Author: malle-pietje

.gitignore

@@ -1,2 +1,14 @@
 # Ignore personal config file
-config.php
+config/config.php
+config/users.php
+
+# ignore these files
+desktop.ini
+*.sublime-workspace
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

README.md

@@ -11,18 +11,24 @@ You will find examples and detailed instructions there.
 Please keep the following in mind:
 
 - the API browser tool doesn't support all available data collections/API endpoints, see the list below of those that are currently supported
-- currently, versions 4.x.x and 5.x.x of the UniFi Controller software are supported (version 5.10.12 has been confirmed to work)
+- currently, versions 4.x.x and 5.x.x of the UniFi Controller software are supported (version 5.11.50 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](https://github.com/Art-of-WiFi/UniFi-API-browser/issues) 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/questions.
 - please read the Security Notice below before installing this tool!
 
+
+### Upgrading from 1.X to 2.X
+
+Because the structure of the configuration file has changed slightly, we recommend creating a fresh install when upgrading from 1.X to 2.X.
+
+
 ### Features
 
 The UniFi API browser tool offers the following features:
 
 - browse data collections/API endpoints exposed by the UniFi Controller API in an easy manner
 - switch between sites managed by the connected controller
-- switch between output formats (currently `json`, `PHP array`, `PHP var_dump`, `PHP var_export`, `json highlighted` and `PHP array using Kint` have been implemented)
-- copy the results to clipboard (only output formats `json`, `PHP array`, `PHP var_dump` and `PHP var_export` are supported, will fail gracefully with large collections)
+- switch between output formats (currently `JSON`, `JSON highlighted`, `PHP array, interactive` and `PHP array, highlighted` have been implemented)
+- copy the results to clipboard (this is only supported with the `JSON` output format, will fail gracefully with large collections)
 - switch between default Bootstrap theme and the [Bootswatch](https://bootswatch.com/) themes
 - an "About" modal which shows version information for PHP, cURL and the UniFi Controller
 - very easy setup with minimal dependencies
@@ -52,9 +58,9 @@ The UniFi API browser tool offers the following features:
   - daily site stats
   - hourly access point stats
   - daily access point stats
-  - all sites stats (supported on controller version 5.2.9 and higher)
+  - all sites stats
   - health metrics
-  - dashboard metrics (supported on controller version 4.9.1.alpha and higher)
+  - dashboard metrics
   - port forward stats
 - Hotspot
   - stat vouchers
@@ -84,11 +90,13 @@ The UniFi API browser tool offers the following features:
 
 Please note that the bundled API client supports many more API endpoints, not all make sense to add to the API browser though.
 
+
 ### Requirements
 
-- a web server with PHP and cURL modules installed (tested on apache2 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.0.7 and cURL 7.37.0)
+- a web server with PHP and cURL modules installed (tested on apache2 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.2.5 and cURL 7.60.0)
 - network connectivity between this web server and the server (and port) where the UniFi controller is running (in case you are seeing errors, please check out [this issue](https://github.com/Art-of-WiFi/UniFi-API-browser/issues/4))
-- clients using this tool should have internet access because the CSS and JS files are loaded from CDNs.
+- clients using this tool should have internet access because several CSS and JS files are loaded from public CDNs.
+
 
 ### Installation
 
@@ -101,40 +109,53 @@ git clone https://github.com/Art-of-WiFi/UniFi-API-browser.git
 
 Alternatively you may choose to download the zip file and unzip it in your directory of choice, then follow the configuration steps below.
 
+
 ### Configuration
 
-- credentials for access to the UniFi Controller API can be configured, in part or in whole, in the file named `config.template.php` which should be copied/renamed to `config.php`
-- starting with API browser tool version 1.0.34, if all or a portion of the credentials are not specified in the `config.php` file or this file is not present, then a login form will ask for the missing credential information
-- starting with version 1.0.3, you can store **multiple controller configurations** in an array inside the `config.php` file
-- please refer to the comments in the `config.template.php` file for further instructions
+- credentials for access to the UniFi Controller API can be configured, in part or in whole, in the file named `config/config-template.php` which should be copied/renamed to `config/config.php`
+- starting with version 1.0.3, you can store **multiple controller configurations** in an array inside the `config/config.php` file
+- please refer to the instructions in the `config/config-template.php` file for further configuration instructions
+- starting with API browser tool version 2.0.0 you can restrict access to the tool by creating user accounts and passwords, please refer to the instructions in the `config/users-template.php` file for further details
 - after following these steps, you can open the tool in your browser (assuming you installed it in the root folder of your web server as suggested above) by going to this url: `http(s)://<server IP address>/UniFi-API-browser/`
 
+
 ### Updates
 
 If you have installed the tool using the `git clone` command, you can install updates by going into the directory where the tool has been installed, and running the `git pull` command from there.
 
 Otherwise you can simply copy the contents from the latest [zip file](https://github.com/Art-of-WiFi/UniFi-API-browser/archive/master.zip) to the directory where the tool has been installed.
 
+
 ### Credits
 
-The PHP API client that comes bundled with this tool is based on the work done by the following developers:
+The PHP API client that comes bundled with this tool is based on the work 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://dl.ubnt.com/unifi/5.6.18-8261dc5066/unifi_sh_api
+
+and the API as published by Ubiquiti:
+
+- https://dl.ui.com/unifi/5.12.21-a25e774adb/unifi_sh_api
 
 Other included libraries:
 
-- Bootstrap (version 3.3.7) https://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
-- Kint (version 2.1.2) https://kint-php.github.io/kint
-- clipboard.js (2.0.1) https://clipboardjs.com/
+- Bootstrap 4 (version 4.3.1) https://getbootstrap.com
+- Bootswatch themes (version 4.3.1) https://bootswatch.com/
+- Font Awesome icons (version 5.11.2) https://fontawesome.com/
+- jQuery (version 3.4.1) https://jquery.com
+- Highlight.js (version 9.15.10) https://highlightjs.org/
+- Kint (version 2.2) https://kint-php.github.io/kint
+- clipboard.js (2.0.4) https://clipboardjs.com/
+
 
 ### Security notice
 
-The use of this tool is **not secured in any way**! Make sure to prevent unauthorised access to it, preventing exposure of details and credentials such as user names and passwords for access to the UniFi Controller!
+We highly recommend enabling user name/password authentication by creating a `config/users.php` based on the included `config/users-template.php` file. When creating passwords and their SHA512 hashes for entry in the `config/users.php` file, please make sure to use strong random passwords.
+
+Please refer to the instructions in the `config/users-template.php` file for further details
+
+It is your own responsibility to implement the necessary additional controls in securing this application and preventing unwanted access.
+
 
 ### Screenshots
 

TODO.md

@@ -1,21 +1,17 @@
 ## TODO:
 
 1. Make the output format selectable like with the siteid, so that after selection we can switch between the two lines below for different output presentation. Possible options to add are ~~PHP array/json~~/table/chart:
-    - ~~print_r ($data);~~
-    - ~~echo json_encode($data, JSON_PRETTY_PRINT);~~
     - DataTables for table output and more
         - requires "flattening" of multidimensional arrays/objects
         - or else only expose a selection of attributes
     - Chart output as option for certain data collections (and selected attributes)
+        - same requirements as for tables
 
 2. Add the option to export data to CSV file format
     - need to have the option to select which fields to export
     - could be combined with the DataTables output option
     - requires "flattening" of multidimensional arrays/objects
 
-3. ~~Add simple user/password login~~
-    - ~~consider setting user name/password in the config file, though not very secure~~
-    - ~~avoid dependencies such as MySQL etc. as much as possible~~
 
 ### Call for suggestions
 

ajax/fetch_about_modal_metrics.php

@@ -0,0 +1,57 @@
+<?php
+/**
+ * Copyright (c) 2019, Art of WiFi
+ * www.artofwifi.net
+ *
+ * This file is subject to the MIT license that is bundled
+ * with this package in the file LICENSE.md
+ *
+ */
+
+/**
+ * load the files containing shared functions and the collections
+ */
+require_once('../common.php');
+require_once('../collections.php');
+
+/**
+ * load the configuration file if readable
+ */
+if (is_file('../config/config.php') && is_readable('../config/config.php')) {
+    include('../config/config.php');
+} else {
+    die();
+}
+
+/**
+ * in order to use the PHP $_SESSION array for temporary storage of variables, session_start() is required
+ */
+session_start();
+
+/**
+ * initialize the results array
+ */
+$results = [
+    'controller_url'     => 'unknown',
+    'controller_user'    => 'unknown',
+    'controller_version' => 'not detected',
+    'memory_used'        => $_SESSION['memory_used'],
+];
+
+/**
+ * and fill in the details for the controller if available
+ */
+if (!empty($_SESSION['controller'])) {
+    $results['controller_url']  = $_SESSION['controller']['url'];
+    $results['controller_user'] = $_SESSION['controller']['user'];
+
+    if (!empty($_SESSION['controller']['detected_version'])) {
+        $results['controller_version'] = $_SESSION['controller']['detected_version'];
+    }
+}
+
+/**
+ * output the results with correct JSON formatting
+ */
+header('Content-Type: application/json; charset=utf-8');
+echo (json_encode($results));