minor changes

added an example to update WLAN settings for recent controllers (5.5.X and higher)

README.md

@@ -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.18 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.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).
 
 This class can be installed using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
 
@@ -13,6 +13,7 @@ If you find this PHP API client class useful and wish to support it's further de
 ## Methods and functions supported
 
 The class currently supports the following functions/methods to get/post/put/delete data through the UniFi Controller API:
+
 - login()
 - logout()
 - adopt_device()
@@ -27,6 +28,7 @@ The class currently supports the following functions/methods to get/post/put/del
 - create_usergroup()
 - create_voucher()
 - create_wlan()
+- delete_device()
 - delete_network()
 - delete_radius_account()
 - delete_site()
@@ -37,6 +39,7 @@ The class currently supports the following functions/methods to get/post/put/del
 - extend_guest_validity()
 - led_override()
 - list_admins()
+- list_all_admins()
 - list_alarms()
 - list_aps() (deprecated but still available as alias)
 - list_clients()
@@ -67,6 +70,7 @@ The class currently supports the following functions/methods to get/post/put/del
 - list_wlan_groups()
 - list_wlanconf()
 - locate_ap()
+- move_device()
 - power_cycle_switch_port()
 - reconnect_sta()
 - rename_ap()
@@ -112,8 +116,9 @@ The class currently supports the following functions/methods to get/post/put/del
 - upgrade_device_external()
 
 Internal functions, getters/setters:
+
 - set_debug()
-- set_site()
+- get_debug()
 - set_site()
 - get_site()
 - get_cookie() (renamed from getcookie())
@@ -206,9 +211,9 @@ Please refer to the `examples/` directory for some more detailed examples which
 
 2. In the example above, `$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`  
+   `https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard`
 
-   In this case, `jl3z2shm` is the value required for $site_id.  
+   In this case, `jl3z2shm` is the value required for $site_id.
 
 ## Need help or have suggestions?
 
@@ -220,7 +225,7 @@ If you would like to contribute code (improvements), please open an issue and in
 
 ## Credits
 
-This class is largely based on the work done by the following developers:
+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.6.18-8261dc5066/unifi_sh_api

examples/create_site.php

@@ -0,0 +1,40 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to create a new site, returns true upon success
+ */
+
+/**
+ * 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');
+
+/**
+ * the site to use to log in to the controller
+ */
+$site_id = '<short site name of a site the credentials used have access to>';
+
+/**
+ * description of the new site
+ */
+$description = 'new site';
+
+/**
+ * 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);
+$loginresults     = $unifi_connection->login();
+$results          = $unifi_connection->create_site($description);
+
+/**
+ * provide feedback (the newly created vouchers) in json format
+ */
+echo json_encode($vouchers, JSON_PRETTY_PRINT);

examples/delete_site.php

@@ -0,0 +1,41 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to delete a site, returns true upon success
+ */
+
+/**
+ * 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');
+
+/**
+ * the site to use to log in to the controller
+ */
+$site_id = '<short site name of a site the credentials used have access to>';
+
+
+/**
+ * the site to delete, may not be the same site as referenced by $site_id
+ */
+$site_to_delete = '<_id value of the site>';
+
+/**
+ * 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);
+$loginresults     = $unifi_connection->login();
+$results          = $unifi_connection->delete_site($site_to_delete);
+
+/**
+ * provide feedback (the newly created vouchers) in json format
+ */
+echo json_encode($vouchers, JSON_PRETTY_PRINT);

examples/update_wlan_settings_5.5.X.php

@@ -0,0 +1,83 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to update WLAN settings when using a controller version 5.5.X or higher
+ *              where set_ap_radiosettings() throws an error
+ */
+
+/**
+ * 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');
+
+/**
+ * the site to use to log in to the controller
+ */
+$site_id = '<short site name of a site the credentials used have access to>';
+
+/**
+ * the MAC address of the access point to modify
+ */
+$ap_mac = '<enter MAC address>';
+
+/**
+ * power level for 2.4GHz
+ */
+$ng_tx_power_mode = 'low';
+
+/**
+ * channel for 2.4GHz
+ */
+$ng_channel = 6;
+
+/**
+ * power level for 5GHz
+ */
+$na_tx_power_mode = 'medium';
+
+/**
+ * channel for 5GHz
+ */
+$na_channel = 44;
+
+/**
+ * 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, false);
+$set_debug_mode   = $unifi_connection->set_debug(false);
+$loginresults     = $unifi_connection->login();
+$data             = $unifi_connection->list_devices($ap_mac);
+$radio_table      = $data[0]->radio_table;
+$device_id        = $data[0]->device_id;
+
+foreach($radio_table as $radio){
+    if($radio->radio === 'ng'){
+        $radio->tx_power_mode = $ng_tx_power_mode;
+        $radio->channel = $ng_channel;
+    }
+
+    if($radio->radio === 'na'){
+        $radio->tx_power_mode = $na_tx_power_mode;
+        $radio->channel = $na_channel;
+    }
+}
+
+$update_device = $unifi_connection->set_device_settings_base($device_id, ['radio_table' => $radio_table]);
+
+if(!$update_device){
+    $error = $unifi_connection->get_last_results_raw();
+    echo json_encode($error, JSON_PRETTY_PRINT);
+}
+
+/**
+ * provide feedback in json format
+ */
+echo json_encode($update_device, JSON_PRETTY_PRINT);

src/Client.php

@@ -46,9 +46,9 @@ class Client
      * optional parameter <baseurl>    = string; base URL of the UniFi controller, must include "https://" prefix and port suffix (:8443)
      * optional parameter <site>       = string; short site name to access, defaults to "default"
      * optional parameter <version>    = string; the version number of the controller, defaults to "5.4.16"
-     * optional parameter <ssl_verify> = boolean; whether to validate the controller's SSL certificate or not, true is recommended for
-     *                                   production environments to prevent potential MitM attacks, default is to not validate the
-     *                                   controller certificate
+     * optional parameter <ssl_verify> = boolean; whether to validate the controller's SSL certificate or not, a value of true is
+     *                                   recommended for production environments to prevent potential MitM attacks, default (false) is to
+     *                                   not validate the controller certificate
      */
     function __construct($user, $password, $baseurl = '', $site = '', $version = '', $ssl_verify = false)
     {
@@ -178,8 +178,8 @@ class Client
      */
     public function set_site($site)
     {
+        $this->check_site($site);
         $this->site = trim($site);
-        $this->check_site($this->site);
         return $this->site;
     }
 
@@ -210,6 +210,16 @@ class Client
         return false;
     }
 
+    /**
+     * Get debug mode
+     * --------------
+     * get the value of private property debug, returns the current boolean value for debug
+     */
+    public function get_debug()
+    {
+        return $this->debug;
+    }
+
     /**
      * Get last raw results
      * --------------------
@@ -242,6 +252,12 @@ class Client
      * Get Cookie from UniFi Controller
      * --------------------------------
      * returns the UniFi controller cookie
+     *
+     * NOTES:
+     * - when the results from this method are stored in $_SESSION['unificookie'], the class will initially not
+     *   log in to the controller when a subsequent request is made using a new instance. This speeds up the
+     *   overall request considerably. If that subsequent request fails (e.g. cookies have expired), a new login
+     *   is executed automatically and the value of $_SESSION['unificookie'] is updated.
      */
     public function get_cookie()
     {
@@ -878,6 +894,18 @@ class Client
         return $this->process_response($response);
     }
 
+    /**
+     * List all admins
+     * ---------------
+     * returns an array containing administrator objects for all sites
+     */
+    public function list_all_admins()
+    {
+        if (!$this->is_loggedin) return false;
+        $response = $this->exec_curl('/api/stat/admin');
+        return $this->process_response($response);
+    }
+
     /**
      * List wlan_groups
      * ----------------
@@ -1255,6 +1283,9 @@ class Client
      * required parameter <ht>(default=20)
      * required parameter <tx_power_mode>
      * required parameter <tx_power>(default=0)
+     *
+     * NOTES:
+     * - only supported on pre-5.X.X controller versions
      */
     public function set_ap_radiosettings($ap_id, $radio, $channel, $ht, $tx_power_mode, $tx_power)
     {