Permalink
Browse files

initial commit

  • Loading branch information...
Erik Slooff
Erik Slooff committed Sep 5, 2017
0 parents commit 508dde33f0d11ca21f92af399461d2db3ee33bf0
@@ -0,0 +1,2 @@
# Ignore personal config file
examples/config.php
@@ -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.
149 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.
@@ -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/"
}
}
}
@@ -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!
@@ -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);
@@ -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);
@@ -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);
Oops, something went wrong.

0 comments on commit 508dde3

Please sign in to comment.