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": 	"[email protected]",
+            "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);