jeroen/unifi-php-api
1
0
Fork 0
mirror of https://github.com/Art-of-WiFi/UniFi-API-client.git synced 2024-12-26 19:00:02 +01:00
Code Issues Packages Projects Releases Wiki Activity

added unblock_list.php and block_list.php examples, contributed by @malcolmcif

Browse Source 
added create_user() method/function
added forget_sta() method/function which is supported on controller version 5.9.* and higher
This commit is contained in:
malle-pietje 2018-05-21 13:06:50 +02:00
parent ccea0eee99
commit 4dddd08d8b
4 changed files with 234 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
README.md
View File

@ -1,6 +1,6 @@
## UniFi Controller API client class
A PHP class which provides access to Ubiquiti's **UniFi Controller API**, versions 4.x.x and 5.x.x of the UniFi Controller software are supported (version 5.6.29 has been confirmed to work). It's a standalone version of the class which is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
A PHP class which provides access to Ubiquiti's **UniFi Controller API**, versions 4.x.x and 5.x.x of the UniFi Controller software are supported (version 5.7.23 has been confirmed to work). It's a standalone version of the class which is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
This class can be installed using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
@ -31,6 +31,7 @@ The class currently supports the following functions/methods to get/post/put/del
- disable_ap()
- edit_usergroup()
- extend_guest_validity()
- forget_sta() (supported on controller version 5.9.* and higher)
- invite_admin()
- revoke_admin()
- led_override()
@ -137,7 +138,7 @@ Please refer to the source code for more details on the functions/methods and th
## Requirements
- a web server with PHP and cURL modules installed (tested on apache2 with PHP Version 5.6.1 and cURL 7.42.1)
- 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)
- network connectivity between this web server and the server and port (normally TCP port 8443) where the UniFi Controller is running
## Installation ##
@ -236,7 +237,7 @@ If you would like to contribute code (improvements), please open an issue and in
This class 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://dl.ubnt.com/unifi/5.7.20/unifi_sh_api
- and the API as published by Ubiquiti: https://dl.ubnt.com/unifi/5.7.23/unifi_sh_api
## Important Disclaimer

90
examples/block_list.php Executable file
View File

@ -0,0 +1,90 @@
<?php
/**
* PHP API usage example
*
* contributed by: @malcolmcif, based on another Art of WiFi example
* description: basic PHP script to block a list of mac addresses passed in via command line,
* output is to console in non json format
*
* usage:
* php block_list.php <list of comma seperated mac addresses>
*
* example:
* php block_list.php 09:09:09:09:09:09,10:10:10:10:10:10
*
*/
/**
* using the composer autoloader
*/
require_once('vendor/autoload.php');
/**
* 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');
$debug=false;
/**
* the MAC address(es) of the device(s) to block
*/
$macs_to_block = explode(',',$argv[1]);
/**
* The site to authorize the device with
*/
$site_id = 'MUST_DEFINE_THIS';
if ($site_id == "MUST_DEFINE_THIS")
{
print 'ERROR: set the site id in your script';
return;
}
/**
* 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(); // always true regardless of site id
foreach ($macs_to_block as &$mac)
{
// block_result is always true even if mac address does not exist :(
$block_result = $unifi_connection->block_sta($mac);
/**
* NOTE:
* during testing I had some strange behavior where clients were not reconnecting to the network correctly,
* they appeared unblocked and received a valid IP address but could not actually get any data.
* the clients did not come to life until I disabled the SSID and then re enabled it.
* I guessed maybe these commands were occurring too quickly for the controller so I have slowed them down;
* since introducing the sleep I have not seen the above behavior so it might be fixed
*/
sleep(1);
$getid_result = $unifi_connection->stat_client($mac);
if (property_exists($getid_result[0], "oui")) // this field(manufacturer) seems to exist on valid mac addresses
{
if (property_exists($getid_result[0], "name")) // this is the alias field if it has been defined
{
$name = $getid_result[0]->name;
}
else
{
$name = $getid_result[0]->hostname;
}
print 'blocked ' . $name . PHP_EOL;
}
else
{
print 'ERROR: could not block ' . $mac . PHP_EOL;
print ' check mac address is valid and part of your network' . PHP_EOL;
}
}
/**
* No json formatted data
*/
//echo json_encode($block_result, JSON_PRETTY_PRINT);

90
examples/unblock_list.php Executable file
View File

@ -0,0 +1,90 @@
<?php
/**
* PHP API usage example
*
* contributed by: @malcolmcif, based on another Art of WiFi example
* description: basic PHP script to unblock a list of mac addresses passed in via command line,
* output is to console in non json format
*
* usage:
* php unblock_list.php <list of comma seperated mac addresses>
*
* example:
* php unblock_list.php 09:09:09:09:09:09,10:10:10:10:10:10
*
*/
/**
* using the composer autoloader
*/
require_once('vendor/autoload.php');
/**
* 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');
$debug=false;
/**
* the MAC addresses of the device(s) to unblock
*/
$macs_to_unblock = explode(',',$argv[1]);
/**
* The site to authorize the device with
*/
$site_id = 'MUST_DEFINE_THIS';
if ($site_id == "MUST_DEFINE_THIS")
{
print 'ERROR: set the site id in your script';
return;
}
/**
* 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(); // always true regardless of site id
foreach ($macs_to_unblock as &$mac)
{
// block_result is always true even if mac address does not exist :(
$block_result = $unifi_connection->unblock_sta($mac);
/**
* NOTE:
* during testing I had some strange behavior where clients were not reconnecting to the network correctly,
* they appeared unblocked and received a valid IP address but could not actually get any data.
* the clients did not come to life until I disabled the SSID and then re enabled it.
* I guessed maybe these commands were occurring too quickly for the controller so I have slowed them down;
* since introducing the sleep I have not seen the above behavior so it might be fixed
*/
sleep(1);
$getid_result = $unifi_connection->stat_client($mac);
if (property_exists($getid_result[0], "oui")) // this field(manufacturer) seems to exist on valid mac addresses
{
if (property_exists($getid_result[0], "name"))
{
$name = $getid_result[0]->name;
}
else
{
$name = $getid_result[0]->hostname;
}
print 'unblocked ' . $name . PHP_EOL;
}
else
{
print 'ERROR: could not unblock ' . $mac . PHP_EOL;
print ' check mac address is valid and part of your network' . PHP_EOL;
}
}
/**
* provide feedback in json format
*/
//echo json_encode($block_result, JSON_PRETTY_PRINT);

56
src/Client.php
View File

@ -138,8 +138,8 @@ class Client
}
if ($code === 400) {
trigger_error('We have received an HTTP response status: 400. Probably a controller login failure');
return $code;
trigger_error('We have received an HTTP response status: 400. Probably a controller login failure');
return $code;
}
}
}
@ -358,14 +358,57 @@ class Client
}
/**
* Add/modify/remove a client device note
* Forget one or more client devices
* ---------------------------------
* return true on success
* required parameter <macs> = array of client MAC addresses
*
* NOTE:
* only supported with controller versions 5.9.X and higher
*/
public function forget_sta($macs)
{
if (!$this->is_loggedin) return false;
$json = json_encode(['cmd' => 'forget-sta', 'macs' => $macs]);
$response = $this->exec_curl('/api/s/'.$this->site.'/cmd/stamgr', 'json='.$json);
return $this->process_response_boolean($response);
}
/**
* Create a new user/client-device
* -------------------------------
* return an array with a single object containing details of the new user/client-device on success, else return false
* required parameter <mac> = client MAC address
* required parameter <user_group_id> = _id value for the user group the new user/client-device should belong to which
* can be obtained from the output of list_usergroups()
* optional parameter <name> = name to be given to the new user/client-device
* optional parameter <note> = note to be applied to the new user/client-device
*/
public function create_user($mac, $user_group_id, $name = null, $note = null)
{
if (!$this->is_loggedin) return false;
$this->request_type = 'POST';
$new_user = ['mac' => $mac, 'usergroup_id' => $user_group_id];
if (!is_null($name)) $new_user['name'] = $name;
if (!is_null($note)) {
$new_user['note'] = $note;
$new_user['noted'] = true;
}
$json = ['objects' => [['data' => $new_user]]];
$json = json_encode($json);
$response = $this->exec_curl('/api/s/'.$this->site.'/group/user', 'json='.$json);
return $this->process_response($response);
}
/**
* Add/modify/remove a client-device note
* --------------------------------------
* return true on success
* required parameter <user_id> = id of the user device to be modified
* optional parameter <note> = note to be applied to the user device
* required parameter <user_id> = id of the client-device to be modified
* optional parameter <note> = note to be applied to the client-device
*
* NOTES:
* - when note is empty or not set, the existing note for the user will be removed and "noted" attribute set to false
* - when note is empty or not set, the existing note for the client-device will be removed and "noted" attribute set to false
*/
public function set_sta_note($user_id, $note = null)
{
@ -1995,6 +2038,7 @@ class Client
*
* NOTES:
* - only applies to switches and their PoE ports...
* - port must be actually providing power
*/
public function power_cycle_switch_port($switch_mac, $port_idx)
{