API client class v1.1.41

changed create_wlan function/method to not include passphrase in payload when security = "open" and passphrase = null
fixed indentations in several places
added custom_api_request() function/method which allows a programmer to issue custom API requests that may not yet be supported by this client (to be used with care!)
added example to demonstrate use of custom_api_request()
removed repetitive code and optimized exec_curl() when creating the final payload, resulting in 10-20% performance increase and slightly lower memory consumption by PHP

README.md

@@ -1,12 +1,12 @@
 ## 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.9.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 SDN Controller API**](https://unifi-sdn.ui.com/), versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.10.19 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 manually or using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
 
 ## Requirements
 
-- 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)
+- a web server with PHP and cURL modules installed (tested on Apache 2.4 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.2.10 and cURL 7.58.0)
 - network connectivity between this web server and the server and port (normally TCP port 8443) where the UniFi Controller is running
 
 ## Installation ##
@@ -84,17 +84,17 @@ Please refer to the `examples/` directory for some more detailed examples which
 
 #### IMPORTANT NOTES:
 
-1. The last optional parameter that is passed to the constructor in the above example (`true`), enables validation of the controller's SSL certificate which is otherwise **disabled** by default. It is highly recommended to enable this feature in production environments where you have a valid SSL cert installed on the UniFi Controller, and which is associated with the FQDN of the server as used in the `controller_url` parameter. This option was added with API client version 1.1.16.
-
-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:
+1. In the above example, `$site_id` is the short site "name" (usually 8 characters long) that is visible in the URL when managing the site in the UniFi SDN Controller, for example with this URL:
 
    `https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard`
 
-   In this case, `jl3z2shm` is the value required for $site_id.
+   `jl3z2shm` is the short site "name" and the value to assign to $site_id.
 
-## Methods and functions supported
+2. The last optional parameter that is passed to the constructor in the above example (`true`), enables validation of the controller's SSL certificate which is otherwise **disabled** by default. It is highly recommended to enable this feature in production environments where you have a valid SSL cert installed on the UniFi Controller, and which is associated with the FQDN of the server as used in the `controller_url` parameter. This option was added with API client version 1.1.16.
 
-The class currently supports the following functions/methods to get/post/put/delete data through the UniFi Controller API:
+## Functions/methods supported
+
+The class currently supports the following functions/methods to GET/POST/PUT/DELETE data through the UniFi Controller API. Please refer to the source code for more details on the functions/methods and their respective parameters.
 
 - login()
 - logout()
@@ -112,6 +112,7 @@ The class currently supports the following functions/methods to get/post/put/del
 - create_user()
 - create_voucher()
 - create_wlan()
+- custom_api_request()
 - delete_device()
 - delete_firewallgroup()
 - delete_network()
@@ -126,6 +127,7 @@ The class currently supports the following functions/methods to get/post/put/del
 - extend_guest_validity()
 - forget_sta() (supported on controller version 5.9.X and higher)
 - invite_admin()
+- assign_existing_admin()
 - revoke_admin()
 - led_override()
 - list_admins()
@@ -239,8 +241,6 @@ Internal functions, getters/setters:
 - get_last_results_raw()
 - get_last_error_message()
 
-Please refer to the source code for more details on the functions/methods and their parameters.
-
 ## Need help or have suggestions?
 
 There is still work to be done to add functionality and further improve the usability of this class, so all suggestions/comments are welcome. Please use the GitHub [issue list](https://github.com/Art-of-WiFi/UniFi-API-client/issues) or the Ubiquiti Community forums (https://community.ubnt.com/t5/UniFi-Wireless/PHP-class-to-access-the-UniFi-controller-API-updates-and/td-p/1512870) to share your suggestions and questions.
@@ -251,10 +251,14 @@ If you would like to contribute code (improvements), please open an issue and in
 
 ## Credits
 
-This class is based on the work done by the following developers:
+This class is based on the initial work 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.8.24/unifi_sh_api
+
+and the API as published by Ubiquiti:
+
+- https://dl.ubnt.com/unifi/5.10.19/unifi_sh_api
 
 ## Important Disclaimer
 

examples/ap_scanning_state.php

@@ -19,6 +19,7 @@ require_once('config.php');
 
 /**
  * site id and MAC address of AP to query
+ * https://github.com/Art-of-WiFi/UniFi-API-client#important-notes
  */
 $site_id = '<enter your site id here>';
 $ap_mac  = '<enter MAC address of Access Point to check>';

examples/ap_upgrade_firmware.php

@@ -11,6 +11,7 @@ require_once('config.php');
 
 /**
  * site id of the AP to update
+ * https://github.com/Art-of-WiFi/UniFi-API-client#important-notes
  */
 $site_id = '<enter your site id here>';
 

examples/execute_custom_api_request.php

@@ -0,0 +1,47 @@
+<?php
+/**
+ * PHP API usage example
+ *
+ * contributed by: Art of WiFi
+ * description: example basic PHP script to execute a custom API request using the
+ *              custom_api_request() function/method
+ */
+
+/**
+ * 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 authorize the device with
+ * https://github.com/Art-of-WiFi/UniFi-API-client#important-notes
+ */
+$site_id = '<enter your site id here>';
+
+/**
+ * parameters
+ */
+$url          = '/api/s/' . $site_id . '/stat/fwupdate/latest-version';
+$request_type = 'GET';
+$payload      = null;
+$return       = 'array';
+
+/**
+ * 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();
+$results          = $unifi_connection->custom_api_request($url, $request_type, $payload, $return);
+
+/**
+ * provide feedback in JSON format or as PHP Object
+ */
+echo json_encode($results, JSON_PRETTY_PRINT);
+//print_r($results);