initial commit

.gitignore

@@ -0,0 +1,2 @@
+# Ignore personal config file
+examples/config.php

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016, Art of WiFi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,149 @@
+## UniFi controller API client class
+
+This PHP class provides access to the **UniFi Controller API** and is based off the work of @domwo and @fbagnol and the API shell client as published by UBNT.
+
+Please refer to the code samples in the `examples` directory for a starting point for your own PHP code.
+
+### Donations
+If you'd like to support further development of this PHP API client class, please use the donate button below. All donations go to the project maintainer.
+
+[![Donate](https://www.paypalobjects.com/en_GB/i/btn/btn_donate_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=M7TVNVX3Z44VN)
+
+### Install
+
+Simply execute this command from your project directory:
+
+```
+composer require art-of-wifi/unifi-api-client
+```
+
+### Requirements
+- a web server with PHP and cURL modules installed (tested on apache2 with PHP Version 5.6.1 and cURL 7.42.1)
+- network connectivity between this web server and the server and port (normally port 8443) where the UniFi controller is running
+
+### Methods and functions supported
+
+This class currently supports the following functions/methods to get/set data through the UniFi controller API:
+- login()
+- logout()
+- add_site()
+- adopt_device()
+- authorize_guest()
+- unauthorize_guest()
+- block_sta()
+- unblock_sta()
+- create_hotspotop()
+- create_voucher()
+- delete_site()
+- disable_ap()
+- led_override()
+- list_admins()
+- list_alarms()
+- count_alarms()
+- upgrade_device()
+- upgrade_device_external()
+- spectrum_scan()
+- spectrum_scan_state()
+- list_devices()
+- list_aps() (deprecated but still available as alias)
+- list_clients()
+- list_dashboard()
+- list_dynamicdns()
+- list_events()
+- list_extension()
+- list_guests()
+- list_health()
+- list_hotspotop()
+- list_networkconf()
+- list_portconf()
+- list_portforward_stats()
+- list_portforwarding()
+- list_radius_accounts() (supported on controller version 5.5.19 and higher)
+- list_rogueaps()
+- list_self()
+- list_settings()
+- list_sites()
+- list_tags() (supported on controller version 5.5.19 and higher)
+- list_usergroups()
+- list_users()
+- list_wlan_groups()
+- list_wlanconf()
+- list_current_channels()
+- list_dpi_stats()
+- reconnect_sta()
+- rename_ap()
+- restart_ap()
+- revoke_voucher()
+- extend_guest_validity()
+- set_ap_radiosettings()
+- set_guestlogin_settings()
+- locate_ap()
+- set_locate_ap() (deprecated but still available as alias)
+- unset_locate_ap() (deprecated but still available as alias)
+- set_sta_name()
+- set_sta_note()
+- set_usergroup()
+- edit_usergroup()
+- add_usergroup()
+- delete_usergroup()
+- edit_usergroup()
+- add_usergroup()
+- delete_usergroup()
+- set_wlansettings()
+- create_wlan()
+- delete_wlan()
+- site_leds()
+- site_ledsoff() (deprecated but still available as alias)
+- site_ledson() (deprecated but still available as alias)
+- stat_allusers()
+- stat_auths()
+- stat_client()
+- stat_daily_site()
+- stat_daily_aps()
+- stat_hourly_aps()
+- stat_hourly_site()
+- stat_payment()
+- stat_sessions()
+- stat_sites()
+- stat_sta_sessions_latest()
+- stat_sysinfo()
+- stat_voucher()
+
+Internal functions:
+- set_debug()
+- get_last_results_raw()
+- get_last_error_message()
+
+Please refer to the source code for more details on each function/method and it's parameters.
+
+### Example usage
+A basic example how to use the class:
+
+```php
+
+...
+/**
+ * initialize the Unifi API connection class, log in to the controller and request the alarms collection
+ * (this example assumes you have already assigned the correct values to the variables used)
+ */
+$unifi_connection = new UniFi_API\Client($controller_user, $controller_password, $controller_url, $site_id, $controller_version);
+$login            = $unifi_connection->login();
+$results          = $unifi_connection->list_alarms(); // returns the alarms in a PHP array
+...
+
+```
+
+>**NOTE:**
+>
+>$site_id is the 8 character short site "name" which is visible in the URL when managing the site in the UniFi controller:
+>
+>```
+>https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard
+>```
+>
+>Here `jl3z2shm` is the value required for $site_id.
+
+Have a look at the files in the `examples` directory for more examples how to use this class.
+
+## Important Disclaimer
+Many of these functions are not officially supported by UBNT and as such, may not be supported in future versions of the UniFi controller API.

composer.json

@@ -0,0 +1,31 @@
+{
+    "name": 		"art-of-wifi/unifi-api-client",
+    "type": 		"library",
+    "description": 	"API client class for use with Ubiquiti's UniFi controller",
+    "keywords": [
+		"ubnt",
+		"ubiquiti",
+		"unifi",
+		"controller",
+		"api",
+		"client"
+	],
+    "homepage": 	"https://github.com/Art-of-WiFi/UniFi-API-client",
+    "license": 		"MIT",
+    "authors": [
+        {
+            "name": 	"Art of WiFi",
+            "email": 	"info@artofowifi.net",
+            "homepage": "http://artofwifi.net"
+        }
+    ],
+    "require": {
+        "php": ">=5.6.0",
+		"ext-curl": "*"
+    },
+    "autoload": {
+        "psr-4": {
+            "UniFi-API\\": "src/"
+        }
+    }
+}

examples/README.md

@@ -0,0 +1,15 @@
+## API client class usage examples
+This directory contains some PHP code examples which demonstrate usage of the PHP API client class and can be used as a good starting point for your own custom code.
+
+### Usage
+
+Copy the appropriate example file to your working directory together with a copy of the config.template.php file which should be renamed to config.php.
+Then update the contents of your new config.php with your controller details and credentials and modify the example file as required to fit your needs.
+
+### 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.
+
+## Important Disclaimer
+
+Use these examples at your own risk!

examples/ap_scanning_state.php

@@ -0,0 +1,33 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to fetch an Access Point's scanning state/results
+ */
+
+/**
+ * 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');
+
+/**
+ * site id and MAC address of AP to query
+ */
+$site_id = '<enter your site id here>';
+$ap_mac  = '<enter MAC address of Access Point to check>';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller and do our thing
+ * spectrum_scan_state()
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login();
+$data             = $unifi_connection->spectrum_scan_state($ap_mac);
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($data, JSON_PRETTY_PRINT);

examples/auth_guest_basic.php

@@ -0,0 +1,45 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to perform a basic auth of a guest device
+ */
+
+/**
+ * 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 MAC address of the device to authorize
+ */
+$mac = '<enter MAC address of guest device to auth>';
+
+/**
+ * the duration to authorize the device for in minutes
+ */
+$duration = 2000;
+
+/**
+ * The site to authorize the device with
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login();
+
+/**
+ * then we authorize the device for the requested duration
+ */
+$auth_result = $unifi_connection->authorize_guest($mac, $duration);
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($auth_result, JSON_PRETTY_PRINT);

examples/auth_guest_with_note.php

@@ -0,0 +1,68 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to auth a guest device and attach a note to it
+ */
+
+/**
+ * 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 MAC address of the device to authorize
+ */
+$mac = '<enter MAC address of guest device to auth>';
+
+/**
+ * the duration to authorize the device for in minutes
+ */
+$duration = 2000;
+
+/**
+ * The site to authorize the device with
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * the note to attach to the device
+ */
+$note = 'Note to attach to newly authorized device';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login();
+
+/**
+ * we authorize the device for the requested duration and attach the note to it's object
+ */
+$auth_result  = $unifi_connection->authorize_guest($mac, $duration);
+$getid_result = $unifi_connection->stat_client($mac);
+$user_id      = $getid_result[0]->_id;
+$note_result  = $unifi_connection->set_sta_note($user_id, $note);
+
+/**
+ * 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**
+ */
+//$block_result   = $unifi_connection->block_sta($mac);
+//$getid_result   = $unifi_connection->stat_client($mac);
+//$user_id        = $getid_result[0]->_id;
+//$note_result    = $unifi_connection->set_sta_note($user_id, $note);
+//$unblock_result = $unifi_connection->unblock_sta($mac);
+//$auth_result    = $unifi_connection->authorize_guest($mac, $duration);
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($auth_result, JSON_PRETTY_PRINT);

examples/config.template.php

@@ -0,0 +1,24 @@
+<?php
+/**
+ * Copyright (c) 2017, Art of WiFi
+ *
+ * This file is subject to the MIT license that is bundled
+ * with this package in the file LICENSE.md
+ *
+ */
+
+/**
+ * Controller configuration
+ * ===============================
+ * Copy this file to your working directory, rename it to config.php and update the section below with your UniFi
+ * controller details and credentials
+ */
+$controlleruser     = ''; // the user name for access to the UniFi Controller
+$controllerpassword = ''; // the password for access to the UniFi Controller
+$controllerurl      = ''; // full url to the UniFi Controller, eg. 'https://22.22.11.11:8443'
+$controllerversion  = ''; // the version of the Controller software, eg. '4.6.6' (must be at least 4.0.0)
+
+/**
+ * set to true (without quotes) to enable debug output to the browser and the PHP error log
+ */
+$debug = false;

examples/create_voucher.php

@@ -0,0 +1,45 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to create a set of vouchers
+ */
+
+/**
+ * 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 voucher duration in minutes
+ */
+$voucher_duration = 2000;
+
+/**
+ * the number of vouchers to create
+ */
+$voucher_count = 1;
+
+/**
+ * The site where you want to create the voucher(s)
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login();
+
+/**
+ * then we create the required number of vouchers for the requested duration
+ */
+$voucher_result = $unifi_connection->create_voucher($voucher_duration, $voucher_count);
+
+/**
+ * provide feedback (the newly created voucher code, without the dash) in json format
+ */
+echo json_encode($voucher_result, JSON_PRETTY_PRINT);

examples/extend_guest_auth.php

@@ -0,0 +1,45 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: mtotone
+ * description: example of how to extend validity of guest authorizations
+ */
+
+/**
+ * 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');
+
+// must be adapted to your site!
+$site_id   = "default";
+$site_name = "*enter your site name*";
+
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login();
+
+if ($loginresults === 400) {
+	print "UniFi controller login failure, please check your credentials in config.php.\n";
+} else {
+	$guestlist = $unifi_connection->list_guests();
+	// print "<pre>"; print_r ($guestlist); print "</pre>";
+	// loop thru all known guests
+	foreach ($guestlist as $guest) {
+		// print "<pre>"; print_r ($guest); print "</pre>";
+		print "<pre>" . $guest->_id . " (" . $guest->mac . "), valid until " . date (DATE_ATOM, $guest->end) . " (" . $guest->end . ")</pre>";
+
+		// just a sample: only extend validity of guests which have end date after 2017-04-02
+		if ($guest->end > 1491166482) {
+			// extend clients five times = five days
+			if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
+			if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
+			if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
+			if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
+			if (!$unifi_connection->extend_guest_validity ($guest->_id)) print "Extend failed for guest with id " . $guest->_id . "\n";
+		}
+	}
+
+	$logout_results = $unifi_connection->logout();
+}

examples/list_alarms.php

@@ -0,0 +1,31 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to pull current alarms from the UniFi controller and output in json format
+ */
+
+/**
+ * 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
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller and do our thing
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login();
+$data             = $unifi_connection->list_alarms();
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($data, JSON_PRETTY_PRINT);

examples/list_ap_connected_users.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example to pull connected user numbers for Access Points from the Unifi controller and output the results
+ *              in raw HTML format
+ */
+
+/**
+ * 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 short name of the site which you wish to query
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller and pull the requested data
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login();
+$aps_array        = $unifi_connection->list_aps();
+
+/**
+ * output the results in HTML format
+ */
+header('Content-Type: text/html; charset=utf-8');
+foreach ($aps_array as $ap) {
+	if ($ap->type === 'uap') {
+		echo '<b>AP name:</b>' . $ap->name . ' <b>model:</b>' . $ap->model . ' <b># connected clients:</b>' . $ap->num_sta . '<br>';
+	}
+}

examples/list_site_health.php

@@ -0,0 +1,34 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example to pull site health metrics from the Unifi controller and output the results
+ *              in json format
+ */
+
+/**
+ * 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 short name of the site you wish to query
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller and pull the requested data
+ */
+
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login();
+$result           = $unifi_connection->list_health();
+
+/**
+ * output the results in correct json formatting
+ */
+header('Content-Type: application/json');
+echo (json_encode($result, JSON_PRETTY_PRINT));

examples/list_social_auth_details.php

@@ -0,0 +1,40 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to pull Facebook social auth details from the UniFi controller and output
+ *              them in basic HTML format
+ */
+
+/**
+ * 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
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller and do our thing
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion);
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login();
+$data             = $unifi_connection->stat_payment();
+
+/**
+ * cycle through the results and print social auth details if set,
+ * at this stage you can choose to do with the payment objects whatever is needed
+ */
+echo 'Results from Facebook social auth:<br>';
+foreach ($data as $payment) {
+    if (isset($payment->gateway) && $payment->gateway == 'facebook') {
+        echo 'First name: ' . $payment->first_name . ' Last name: ' . $payment->last_name . ' E-mail address: ' . $payment->email . '<br>';
+    }
+}
+
+echo '<hr><br>';

examples/toggle_led.php

@@ -0,0 +1,51 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example to toggle the locate function (flashing LED) on an Access Point and
+ *              output the response in json format
+ */
+
+/**
+ * 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');
+
+/**
+ * site id to use
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * other specific variables to be used
+ */
+$mac = '<enter MAC address of your AP here>';
+
+/**
+ * initialize the UniFi API connection class and log in to the controller to do our thing
+ */
+$unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $controllerurl, $site_id, $controllerversion); // initialize the class instance
+$set_debug_mode   = $unifi_connection->set_debug($debug);
+$loginresults     = $unifi_connection->login();
+
+/**
+ * using the new method/function
+ */
+$data = $unifi_connection->locate_ap($mac, true); // uncomment to switch locating on
+//$data = $unifi_connection->locate_ap($mac, false); // uncomment to switch locating off (choose either of these two lines!)
+
+if ($data) {
+    /**
+     * provide feedback in json format
+     */
+    echo json_encode($data, JSON_PRETTY_PRINT);
+} else {
+    /**
+     * method returned false so we display the raw results in json format
+     */
+    echo '<pre>';
+    print_r($unifi_connection->get_last_results_raw(true));
+    echo '</pre>';
+}