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,100 @@
 ## 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.8.24 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.
 
-## Methods and functions supported
+## Requirements
 
-The class currently supports the following functions/methods to get/post/put/delete data through the UniFi Controller API:
+- 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 ##
+
+You can use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client class.
+
+### Composer
+
+The preferred method is via [composer](https://getcomposer.org). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.
+
+Once composer is installed, simply execute this command from the shell in your project directory:
+
+```sh
+composer require art-of-wifi/unifi-api-client
+```
+
+ Or you can manually add the package to your composer.json file:
+
+```javascript
+{
+    "require": {
+        "art-of-wifi/unifi-api-client": "^1.1"
+    }
+}
+```
+
+Finally, be sure to include the autoloader in your code:
+
+```php
+require_once('vendor/autoload.php');
+```
+
+### Git
+
+Execute the following `git` command from the shell in your project directory:
+
+```sh
+git clone https://github.com/Art-of-WiFi/UniFi-API-client.git
+```
+
+When git is done cloning, include the file containing the class like so in your code:
+
+```php
+require_once('path/to/src/Client.php');
+```
+
+### Download the Release
+
+If you prefer not to use composer or git, you can simply [download the package](https://github.com/Art-of-WiFi/UniFi-API-client/archive/master.zip), uncompress the zip file, then include the file containing the class in your code like so:
+
+```php
+require_once('path/to/src/Client.php');
+```
+
+## Example usage
+
+A basic example how to use the class:
+
+```php
+/**
+ * load the class using the composer autoloader
+ */
+require_once('vendor/autoload.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, true);
+$login            = $unifi_connection->login();
+$results          = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects
+```
+
+Please refer to the `examples/` directory for some more detailed examples which you can use as a starting point for your own PHP code.
+
+#### IMPORTANT NOTES:
+
+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`
+
+   `jl3z2shm` is the short site "name" and the value to assign to $site_id.
+
+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.
+
+## 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()
@@ -24,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()
@@ -38,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()
@@ -139,6 +229,7 @@ The class currently supports the following functions/methods to get/post/put/del
 - upgrade_device_external()
 - start_rolling_upgrade()
 - cancel_rolling_upgrade()
+- cmd_stat()
 
 Internal functions, getters/setters:
 
@@ -150,96 +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.
-
-## 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)
-- network connectivity between this web server and the server and port (normally TCP port 8443) where the UniFi Controller is running
-
-## Installation ##
-
-You can use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client class.
-
-### Composer
-
-The preferred method is via [composer](https://getcomposer.org). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.
-
-Once composer is installed, simply execute this command from the shell in your project directory:
-
-```sh
-composer require art-of-wifi/unifi-api-client
-```
-
- Or you can manually add the package to your composer.json file:
-
-```javascript
-{
-    "require": {
-        "art-of-wifi/unifi-api-client": "^1.1"
-    }
-}
-```
-
-Finally, be sure to include the autoloader in your code:
-
-```php
-require_once('vendor/autoload.php');
-```
-
-### Git
-
-Execute the following `git` command from the shell in your project directory:
-
-```sh
-git clone https://github.com/Art-of-WiFi/UniFi-API-client.git
-```
-
-When git is done cloning, include the file containing the class like so in your code:
-
-```php
-require_once('path/to/src/Client.php');
-```
-
-### Download the Release
-
-If you prefer not to use composer or git, you can simply [download the package](https://github.com/Art-of-WiFi/UniFi-API-client/archive/master.zip), uncompress the zip file, then include the file containing the class in your code like so:
-
-```php
-require_once('path/to/src/Client.php');
-```
-
-## Example usage
-
-A basic example how to use the class:
-
-```php
-/**
- * load the class using the composer autoloader
- */
-require_once('vendor/autoload.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, true);
-$login            = $unifi_connection->login();
-$results          = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects
-```
-
-Please refer to the `examples/` directory for some more detailed examples which you can use as a starting point for your own PHP code.
-
-#### 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:
-
-   `https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard`
-
-   In this case, `jl3z2shm` is the value required for $site_id.
-
 ## 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.
@@ -250,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/README.md

@@ -9,6 +9,17 @@ Then update the contents of your new config.php with your controller details and
 
 Also make sure to update the path for the composer autoloader file (`vendor/autoload.php`) or the file containing the Class itself (`src/Client.php`) in your `require_once()` statement as required.
 
+#### Executing scripts from the CLI
+
+Most of the included example scripts can be run from the CLI or shell as follows after the necessary credentials and parameters have been added or updated:
+
+
+```sh
+$ php list_site_health.php
+```
+
+NOTE: this does require the `php-cli` module to be installed
+
 ### 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.

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);