API client class v1.1.64

- added information to several docblocks - changed handling of request headers, added private property for this - applied changes for improved use of require_once in the README and examples - added `list_sites()` example - *potential breaking changes:* renamed `get_request_type()` and `set_request_type()` functions/methods to `get_request_method()` and `set_request_method()` respectively
Art-of-WiFi · Jan 21, 2021 · bf3446b · bf3446b
1 parent a4998de
commit bf3446b
Show file tree

Hide file tree

Showing 32 changed files with 275 additions and 232 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 ## UniFi Controller API client class
 
-A PHP class that provides access to Ubiquiti's [**UniFi Network Controller**](https://unifi-network.ui.com/) API, versions 4.X.X, 5.X.X and 6.0.X of the UniFi Network Controller software are supported (version 6.0.42 has been confirmed to work) as well as UniFi OS-based controllers (version 5.12.59 has been confirmed to work). This class is used by our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
+A PHP class that provides access to Ubiquiti's [**UniFi Network Controller**](https://unifi-network.ui.com/) API, versions 4.X.X, 5.X.X and 6.0.X of the UniFi Network Controller software are supported (version 6.0.43 has been confirmed to work) as well as UniFi OS-based controllers (version 5.12.59 has been confirmed to work). This class is used by our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
 
 The package can be installed manually or by using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
 
@@ -13,13 +13,13 @@ The package can be installed manually or by using composer/[packagist](https://p
 
 ## UniFi OS Support
 
-Support for UniFi OS-based controllers (UniFi Dream Machine Pro) has been added as of version 1.1.47. The class automatically detects UniFi OS devices and adjusts URLs and several functions/methods accordingly. If your own code applies strict validation of the URL that is passed to the constructor, please adapt your logic to allow URLs without a port suffix when dealing with a UniFi OS-based controller.
+Support for UniFi OS-based controllers (UniFi Dream Machine Pro or Cloud Key Gen2/Cloud Key Gen2 Plus with firmware version 2.0.24 or higher) has been added as of version 1.1.47. The class automatically detects UniFi OS devices and adjusts URLs and several functions/methods accordingly. If your own code applies strict validation of the URL that is passed to the constructor, please adapt your logic to allow URLs without a port suffix when dealing with a UniFi OS-based controller.
 
 Please test all methods you plan on using thoroughly before using the API Client with UniFi OS devices in a production environment.
 
 ## Installation
 
-You can use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client class.
+Use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client class.
 
 ### Composer
 
@@ -31,7 +31,7 @@ Once composer is installed, simply execute this command from the shell in your p
 composer require art-of-wifi/unifi-api-client
 ```
 
- Or you can manually add the package to your composer.json file:
+ Or manually add the package to your composer.json file:
 
 ```javascript
 {
@@ -44,7 +44,7 @@ composer require art-of-wifi/unifi-api-client
 Finally, be sure to include the autoloader in your code:
 
 ```php
-require_once('vendor/autoload.php');
+require_once 'vendor/autoload.php';
 ```
 
 ### Git
@@ -58,15 +58,15 @@ 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');
+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:
+If you prefer not to use composer or git, 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');
+require_once 'path/to/src/Client.php';
 ```
 
 ## Example usage
@@ -77,7 +77,7 @@ A basic example how to use the class:
 /**
  * load the class using the composer autoloader
  */
-require_once('vendor/autoload.php');
+require_once 'vendor/autoload.php';
 
 /**
  * initialize the Unifi API connection class, log in to the controller and request the alarms collection
@@ -88,7 +88,7 @@ $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.
+Please refer to the `examples/` directory for some more detailed examples which can be used as a starting point for your own PHP code.
 
 #### IMPORTANT NOTES:
 
@@ -269,15 +269,15 @@ Other functions, getters/setters:
 - get_is_unifi_os()
 - get_last_error_message()
 - get_last_results_raw()
-- get_request_type()
+- get_request_method()
 - get_site()
 - get_ssl_verify_host()
 - get_ssl_verify_peer()
 - set_connection_timeout()
 - set_cookies()
 - set_debug()
 - set_is_unifi_os()
-- set_request_type()
+- set_request_method()
 - set_site()
 - set_ssl_verify_host()
 - set_ssl_verify_peer()

diff --git a/examples/ap_scanning_state.php b/examples/ap_scanning_state.php
@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to fetch an Access Point's scanning state/results
+ * description:    example basic PHP script to fetch an Access Point's scanning state/results
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * site id and MAC address of AP to query

diff --git a/examples/ap_upgrade_firmware.php b/examples/ap_upgrade_firmware.php
@@ -3,11 +3,11 @@
  * PHP API usage example
  *
  * contributed by: @4oo4
- * description: example script to upgrade device firmware (can be scheduled with systemd/cron)
- *              to the most current version
+ * description:    example script to upgrade device firmware (can be scheduled with systemd/cron)
+ *                 to the most current version
  */
-require_once('vendor/autoload.php');
-require_once('config.php');
+require_once 'vendor/autoload.php';
+require_once 'config.php';
 
 /**
  * site id of the AP to update

diff --git a/examples/auth_guest_basic.php b/examples/auth_guest_basic.php
@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example PHP script to perform a basic auth of a guest device
+ * description:    example PHP script to perform a basic auth of a guest device
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * the MAC address of the device to authorize

diff --git a/examples/auth_guest_with_note.php b/examples/auth_guest_with_note.php
@@ -3,21 +3,21 @@
  * 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,
- *              this requires the device to be connected to the WLAN/LAN at moment of
- *              authorization
+ * description:    example basic PHP script to auth a guest device and attach a note to it,
+ *                 this requires the device to be connected to the WLAN/LAN at moment of
+ *                 authorization
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * the MAC address of the device to authorize

diff --git a/examples/block_list.php b/examples/block_list.php
@@ -3,27 +3,26 @@
  * 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
+ * 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');
+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');
+require_once 'config.php';
 $debug = false;
 
 /**

diff --git a/examples/change_super_mgmt.php b/examples/change_super_mgmt.php
@@ -3,22 +3,22 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to modify the super_mgmt settings for UniFi controller and output results
- *              in json format
+ * description:    example basic PHP script to modify the super_mgmt settings for UniFi controller and output results
+ *                 in json format
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+require_once 'vendor/autoload.php';
 
 /**
  * UniFi controller credentials and the site to use, in this case since we are modifying global settings you can select
  * any site here that is available on the UniFi controller
  *
  * NOTE: in this case you need to enter Super Administrator account credentials in config.php
  */
-require_once('config.php');
+require_once 'config.php';
 $site_id = 'default';
 $debug   = false;
 

diff --git a/examples/change_wlan_password.php b/examples/change_wlan_password.php
@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to change the WPA2 password/PSK of a WLAN, returns true on success
+ * description:    example basic PHP script to change the WPA2 password/PSK of a WLAN, returns true on success
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * The site to which the WLAN you want to modify belongs

diff --git a/examples/config.template.php b/examples/config.template.php
@@ -1,10 +1,8 @@
 <?php
 /**
- * Copyright (c) 2017, Art of WiFi
- *
- * This file is subject to the MIT license that is bundled
- * with this package in the file LICENSE.md
+ * Copyright (c) 2021, Art of WiFi
  *
+ * This file is subject to the MIT license that is bundled with this package in the file LICENSE.md
  */
 
 /**

diff --git a/examples/create_site.php b/examples/create_site.php
@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to create a new site, returns true upon success
+ * description:    example basic PHP script to create a new site, returns true upon success
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * the site to use to log in to the controller

diff --git a/examples/create_voucher.php b/examples/create_voucher.php
@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to create a set of vouchers, returns an array containing the newly created vouchers
+ * description:    example basic PHP script to create a set of vouchers, returns an array containing the newly created vouchers
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * minutes the voucher is valid after activation (expiration time)

diff --git a/examples/delete_site.php b/examples/delete_site.php
@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to delete a site, returns true upon success
+ * description:    example basic PHP script to delete a site, returns true upon success
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * the site to use to log in to the controller

diff --git a/examples/disable_device.php b/examples/disable_device.php
@@ -3,19 +3,19 @@
  * PHP API usage example
  *
  * contributed by: Art of WiFi
- * description: example basic PHP script to disable/enable a device, returns true upon success
+ * description:    example basic PHP script to disable/enable a device, returns true upon success
  */
 
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * the 24 character id of the device to disable/enable

diff --git a/examples/disable_switch_port.php b/examples/disable_switch_port.php
@@ -12,13 +12,13 @@
 /**
  * using the composer autoloader
  */
-require_once('vendor/autoload.php');
+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');
+require_once 'config.php';
 
 /**
  * the site to use to log in to the controller