shortened several property names

minor improvements
removed non-compliant header suffix
2021-03-22 11:58:20 +01:00 · 2021-03-22 11:52:44 +01:00 · 2021-03-21 16:08:55 +01:00 · 2021-03-21 16:03:05 +01:00 · 2021-01-24 18:09:38 +01:00 · 2021-01-24 17:58:23 +01:00
2 changed files with 322 additions and 235 deletions
--- a/README.md
+++ b/README.md
@@ -4,6 +4,7 @@ A PHP class that provides access to Ubiquiti's [**UniFi Network Controller**](ht

 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.

+
 ## Requirements

 - a server with PHP, version 5.5.0 or higher, and the PHP cURL module installed (tested on Apache 2.4 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.2.24 and cURL 7.58.0)
@@ -17,10 +18,12 @@ Support for UniFi OS-based controllers (UniFi Dream Machine Pro or Cloud Key Gen

 Please test all methods you plan on using thoroughly before using the API Client with UniFi OS devices in a production environment.

+
 ## Installation

 Use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client class.

+
 ### Composer

 The preferred installation method is through [composer](https://getcomposer.org). Follow these [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.
@@ -47,6 +50,7 @@ Finally, be sure to include the autoloader in your code:
 require_once 'vendor/autoload.php';
 ```

+
 ### Git

 Execute the following `git` command from the shell in your project directory:
@@ -61,6 +65,7 @@ When git is done cloning, include the file containing the class like so in your
 require_once 'path/to/src/Client.php';
 ```

+
 ### Download the Release

 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:
@@ -69,6 +74,7 @@ If you prefer not to use composer or git, simply [download the package](https://
 require_once 'path/to/src/Client.php';
 ```

+
 ## Example usage

 A basic example how to use the class:
@@ -90,6 +96,7 @@ $results          = $unifi_connection->list_alarms(); // returns a PHP array con

 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:

 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 Network Controller. For example with this URL:
@@ -98,7 +105,8 @@ Please refer to the `examples/` directory for some more detailed examples which

   `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 that is associated with the FQDN in the `controller_url` parameter. This option was added with API client version 1.1.16.
+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 that is associated with the FQDN in the `controller_url` parameter. This option was added with API client version 1.1.16.
+

 ## Functions/methods supported

@@ -156,6 +164,7 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
 - list_current_channels()
 - list_dashboard()
 - list_devices()
+- list_device_name_mappings()
 - list_dpi_stats()
 - list_dynamicdns()
 - list_events()
@@ -247,6 +256,7 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
 - stat_speedtest_results()
 - stat_sta_sessions_latest()
 - stat_status()
+- stat_full_status()
 - stat_sysinfo()
 - stat_voucher()
 - stat_monthly_aps()
@@ -287,10 +297,12 @@ Other functions, getters/setters:

 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.

+
 ## Contribute

 If you would like to contribute code (improvements), please open an issue and include your code there or else create a pull request.

+
 ## Credits

 This class is based on the initial work by the following developers:
@@ -302,6 +314,7 @@ and the API as published by Ubiquiti:

 - https://dl.ui.com/unifi/6.0.41/unifi_sh_api

+
 ## Important Disclaimer

 Many of the functions in this API client class are not officially supported by UBNT and as such, may not be supported in future versions of the UniFi Controller API.
--- a/src/Client.php
+++ b/src/Client.php
@@ -12,7 +12,7 @@ namespace UniFi_API;
 *
 * @package UniFi_Controller_API_Client_Class
 * @author  Art of WiFi <info@artofwifi.net>
- * @version Release: 1.1.64
+ * @version Release: 1.1.70
 * @license This class is subject to the MIT license that is bundled with this package in the file LICENSE.md
 * @example This directory in the package repository contains a collection of examples:
 *          https://github.com/Art-of-WiFi/UniFi-API-client/tree/master/examples
@@ -20,27 +20,27 @@ namespace UniFi_API;
 class Client
 {
    /**
-     * protected and private properties
+     * private and protected properties
     */
+    private $class_version        = '1.1.70';
    protected $baseurl            = 'https://127.0.0.1:8443';
    protected $user               = '';
    protected $password           = '';
    protected $site               = 'default';
    protected $version            = '6.0.43';
    protected $debug              = false;
+    protected $ssl_verify_peer    = false;
+    protected $ssl_verify_host    = false;
    protected $is_loggedin        = false;
    protected $is_unifi_os        = false;
    protected $exec_retries       = 0;
-    protected $class_version         = '1.1.64';
-    private $cookies                 = '';
-    private $headers                 = [];
-    private $request_method          = 'GET';
-    private $request_methods_allowed = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
-    private $connect_timeout         = 10;
-    private $last_results_raw        = null;
-    private $last_error_message      = null;
-    private $curl_ssl_verify_peer    = false;
-    private $curl_ssl_verify_host    = false;
+    protected $cookies            = '';
+    protected $headers            = [];
+    protected $method             = 'GET';
+    protected $methods_allowed    = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
+    protected $connect_timeout    = 10;
+    protected $last_results_raw   = null;
+    protected $last_error_message = null;

    /**
     * Construct an instance of the UniFi API client class
@@ -80,8 +80,8 @@ class Client
        }

        if ((boolean) $ssl_verify === true) {
-            $this->curl_ssl_verify_peer = true;
-            $this->curl_ssl_verify_host = 2;
+            $this->ssl_verify_peer = true;
+            $this->ssl_verify_host = 2;
        }
    }

@@ -116,7 +116,7 @@ class Client
    public function login()
    {
        /**
-         * if already logged in we skip the login process
+         * skip the login process if already logged in
         */
        if ($this->is_loggedin === true) {
            return true;
@@ -129,7 +129,7 @@ class Client
        }

        /**
-         * first we check whether we have a "regular" controller or one based on UniFi OS,
+         * check whether this is a "regular" controller or one based on UniFi OS,
         * prepare cURL and options
         */
        if (!($ch = $this->get_curl_resource())) {
@@ -156,14 +156,17 @@ class Client
        }

        /**
-         * we now proceed with the actual login
+         * prepare the actual login
         */
        $curl_options = [
            CURLOPT_NOBODY     => false,
            CURLOPT_POSTFIELDS => json_encode(['username' => $this->user, 'password' => $this->password]),
-            CURLOPT_HTTPHEADER => ['content-type: application/json'],
+            CURLOPT_HTTPHEADER => [
+                'content-type: application/json',
+                'Expect:'
+            ],
            CURLOPT_REFERER    => $this->baseurl . '/login',
-            CURLOPT_URL        => $this->baseurl . '/api/login'
+            CURLOPT_URL        => $this->baseurl . '/api/login',
        ];

        /**
@@ -197,43 +200,21 @@ class Client
        }

        /**
-         * based on the HTTP response code we either trigger an error or
-         * extract the cookie from the headers
+         * based on the HTTP response code trigger an error
         */
        if ($http_code === 400 || $http_code === 401) {
-            trigger_error("We received the following HTTP response status: $http_code. Probably a controller login failure");
+            trigger_error("HTTP response status received: $http_code. Probably a controller login failure");

            return $http_code;
        }

-        $response_header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
-        $response_headers     = substr($response, 0, $response_header_size);
-        $response_body        = trim(substr($response, $response_header_size));
-
        curl_close($ch);

        /**
-         * we are good to extract the cookies
+         * extract the cookies
         */
-        if ($http_code >= 200 && $http_code < 400 && !empty($response_body)) {
-            preg_match_all('|Set-Cookie: (.*);|Ui', $response_headers, $results);
-            if (array_key_exists(1, $results)) {
-                $this->cookies = implode(';', $results[1]);
-
-                /**
-                 * accept cookies from regular UniFi controllers or from UniFi OS
-                 */
-                if (strpos($this->cookies, 'unifises') !== false || strpos($this->cookies, 'TOKEN') !== false) {
-                    /**
-                     * update the cookie value in $_SESSION['unificookie'], if it exists
-                     */
-                    if (isset($_SESSION['unificookie'])) {
-                        $_SESSION['unificookie'] = $this->cookies;
-                    }
-
-                    return $this->is_loggedin = true;
-                }
-            }
+        if ($http_code >= 200 && $http_code < 400) {
+            return $this->is_loggedin;
        }

        return false;
@@ -261,7 +242,11 @@ class Client
        /**
         * constuct HTTP request headers as required
         */
-        $this->headers = ['content-length: 0'];
+        $this->headers = [
+            'content-length: 0',
+            'Expect:'
+        ];
+
        $logout_path   = '/logout';
        if ($this->is_unifi_os) {
            $logout_path = '/api/auth/logout';
@@ -312,21 +297,21 @@ class Client
        $payload = ['cmd' => 'authorize-guest', 'mac' => strtolower($mac), 'minutes' => intval($minutes)];

        /**
-         * if we have received values for up/down/megabytes/ap_mac we append them to the payload array to be submitted
+         * append received values for up/down/megabytes/ap_mac to the payload array to be submitted
         */
-        if (!is_null($up)) {
+        if (!empty($up)) {
            $payload['up'] = intval($up);
        }

-        if (!is_null($down)) {
+        if (!empty($down)) {
            $payload['down'] = intval($down);
        }

-        if (!is_null($megabytes)) {
+        if (!empty($megabytes)) {
            $payload['bytes'] = intval($megabytes);
        }

-        if (!is_null($ap_mac)) {
+        if (!empty($ap_mac) && filter_var($ap_mac, FILTER_VALIDATE_MAC)) {
            $payload['ap_mac'] = strtolower($ap_mac);
        }

@@ -423,7 +408,6 @@ class Client

        if (!empty($note)) {
            $new_user['note']  = $note;
-            $new_user['noted'] = true;
        }

        if (!empty($is_guest) && is_bool($is_guest)) {
@@ -449,8 +433,8 @@ class Client
     */
    public function set_sta_note($user_id, $note = null)
    {
-        $noted   = empty($note) ? false : true;
-        $payload = ['note' => $note, 'noted' => $noted];
+        //$noted   = empty($note) ? false : true;
+        $payload = ['note' => $note];

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/upd/user/' . trim($user_id), $payload);
    }
@@ -1109,7 +1093,7 @@ class Client
            return false;
        }

-        $this->request_method = 'PUT';
+        $this->method = 'PUT';
        $payload = [
            '_id'         => $client_id,
            'use_fixedip' => $use_fixedip
@@ -1165,7 +1149,7 @@ class Client
     */
    public function edit_usergroup($group_id, $site_id, $group_name, $group_dn = -1, $group_up = -1)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';
        $payload = [
            '_id'               => $group_id,
            'name'              => $group_name,
@@ -1185,7 +1169,7 @@ class Client
     */
    public function delete_usergroup($group_id)
    {
-        $this->request_method = 'DELETE';
+        $this->method = 'DELETE';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/usergroup/' . trim($group_id));
    }
@@ -1193,7 +1177,7 @@ class Client
    /**
     * Fetch AP groups
     *
-     * @return array returns an array containing the current AP groups on success
+     * @return array  containing the current AP groups on success
     */
    public function list_apgroups()
    {
@@ -1225,7 +1209,7 @@ class Client
     */
    public function edit_apgroup($group_id, $group_name, $device_macs)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';
        $payload = [
            '_id'            => $group_id,
            'attr_no_delete' => false,
@@ -1244,7 +1228,7 @@ class Client
     */
    public function delete_apgroup($group_id)
    {
-        $this->request_method = 'DELETE';
+        $this->method = 'DELETE';

        return $this->fetch_results_boolean('/v2/api/site/' . $this->site . '/apgroups/' . trim($group_id));
    }
@@ -1255,7 +1239,7 @@ class Client
     * @param  string $group_id optional, _id value of the single firewall group to list
     * @return array            containing the current firewall groups or the selected firewall group on success
     */
-    public function list_firewallgroups($group_id = null)
+    public function list_firewallgroups($group_id = '')
    {
        return $this->fetch_results('/api/s/' . $this->site . '/rest/firewallgroup/' . trim($group_id));
    }
@@ -1298,7 +1282,7 @@ class Client
            return false;
        }

-        $this->request_method = 'PUT';
+        $this->method = 'PUT';
        $payload = [
            '_id'           => $group_id,
            'name'          => $group_name,
@@ -1318,7 +1302,7 @@ class Client
     */
    public function delete_firewallgroup($group_id)
    {
-        $this->request_method = 'DELETE';
+        $this->method = 'DELETE';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/firewallgroup/' . trim($group_id));
    }
@@ -1525,7 +1509,7 @@ class Client
     */
    public function set_site_country($country_id, $payload)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/country/' . trim($country_id), $payload);
    }
@@ -1544,7 +1528,7 @@ class Client
     */
    public function set_site_locale($locale_id, $payload)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/locale/' . trim($locale_id), $payload);
    }
@@ -1560,7 +1544,7 @@ class Client
     */
    public function set_site_snmp($snmp_id, $payload)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/snmp/' . trim($snmp_id), $payload);
    }
@@ -1576,7 +1560,7 @@ class Client
     */
    public function set_site_mgmt($mgmt_id, $payload)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/mgmt/' . trim($mgmt_id), $payload);
    }
@@ -1592,7 +1576,7 @@ class Client
     */
    public function set_site_guest_access($guest_access_id, $payload)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/guest_access/' . trim($guest_access_id), $payload);
    }
@@ -1608,7 +1592,7 @@ class Client
     */
    public function set_site_ntp($ntp_id, $payload)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/ntp/' . trim($ntp_id), $payload);
    }
@@ -1624,7 +1608,7 @@ class Client
     */
    public function set_site_connectivity($connectivity_id, $payload)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/setting/connectivity/' . trim($connectivity_id), $payload);
    }
@@ -1792,8 +1776,8 @@ class Client
    /**
     * Fetch controller status
     *
-     * NOTES: in order to get useful results (e.g. controller version) you can call get_last_results_raw()
-     * immediately after this method. Login not required.
+     * NOTES:
+     * login not required
     *
     * @return bool true upon success (controller is online)
     */
@@ -1802,6 +1786,36 @@ class Client
        return $this->fetch_results_boolean('/status', null, false);
    }

+    /**
+     * Fetch full controller status
+     *
+     * NOTES:
+     * login not required
+     *
+     * @return bool|array  staus array upon success, false upon failure
+     */
+    public function stat_full_status()
+    {
+        $this->fetch_results_boolean('/status', null, false);
+
+        return json_decode($this->get_last_results_raw());
+    }
+
+    /**
+     * Fetch device name mappings
+     *
+     * NOTES:
+     * login not required
+     *
+     * @return bool|array  mappings array upon success, false upon failure
+     */
+    public function list_device_name_mappings()
+    {
+        $this->fetch_results_boolean('/dl/firmware/bundles.json', null, false);
+
+        return json_decode($this->get_last_results_raw());
+    }
+
    /**
     * Fetch self
     *
@@ -1820,7 +1834,7 @@ class Client
     */
    public function stat_voucher($create_time = null)
    {
-        $payload = trim($create_time) != null ? ['create_time' => intval($create_time)] : [];
+        $payload = isset($create_time) ? ['create_time' => intval($create_time)] : [];

        return $this->fetch_results('/api/s/' . $this->site . '/stat/voucher', $payload);
    }
@@ -1833,7 +1847,7 @@ class Client
     */
    public function stat_payment($within = null)
    {
-        $path_suffix = $within != null ? '?within=' . intval($within) : '';
+        $path_suffix = isset($within) ? '?within=' . intval($within) : '';

        return $this->fetch_results('/api/s/' . $this->site . '/stat/payment' . $path_suffix);
    }
@@ -1849,7 +1863,7 @@ class Client
    public function create_hotspotop($name, $x_password, $note = null)
    {
        $payload = ['name' => $name, 'x_password' => $x_password];
-        if (!is_null($note)) {
+        if (!isset($note)) {
            $payload['note'] = trim($note);
        }

@@ -2130,7 +2144,7 @@ class Client
            return false;
        }

-        $this->request_method = 'PUT';
+        $this->method = 'PUT';
        $payload      = ['disabled' => $disable];

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/device/' . trim($ap_id), $payload);
@@ -2154,7 +2168,7 @@ class Client
            return false;
        }

-        $this->request_method = 'PUT';
+        $this->method = 'PUT';
        $payload      = ['led_override' => $override_mode];

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/device/' . trim($device_id), $payload);
@@ -2288,7 +2302,7 @@ class Client
            '_id'               => $section_id
        ];

-        return $this->fetch_results_boolean('/api/s/' . $this->site . '/set/setting/guest_access', $payload);
+        return $this->fetch_results_boolean('/api/s/' . $this->site . '/set/setting/guest_access/' . $section_id, $payload);
    }

    /**
@@ -2298,9 +2312,13 @@ class Client
     *                               object/array structured in the same manner as is returned by list_settings() for the "guest_access" section.
     * @return bool                  true on success
     */
-    public function set_guestlogin_settings_base($payload)
+    public function set_guestlogin_settings_base($payload, $section_id = '')
    {
-        return $this->fetch_results_boolean('/api/s/' . $this->site . '/set/setting/guest_access', $payload);
+        if (!empty($section_id)) {
+            $section_id = '/' . $section_id;
+        }
+
+        return $this->fetch_results_boolean('/api/s/' . $this->site . '/set/setting/guest_access' . $section_id, $payload);
    }

    /**
@@ -2430,7 +2448,7 @@ class Client
     */
    public function set_dynamicdns($dynamicdns_id, $payload)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/dynamicdns/' . trim($dynamicdns_id), $payload);
    }
@@ -2468,7 +2486,7 @@ class Client
     */
    public function set_networksettings_base($network_id, $payload)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/networkconf/' . trim($network_id), $payload);
    }
@@ -2481,7 +2499,7 @@ class Client
     */
    public function delete_network($network_id)
    {
-        $this->request_method = 'DELETE';
+        $this->method = 'DELETE';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/networkconf/' . trim($network_id));
    }
@@ -2579,7 +2597,7 @@ class Client
     */
    public function set_wlansettings_base($wlan_id, $payload)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/wlanconf/' . trim($wlan_id), $payload);
    }
@@ -2632,7 +2650,7 @@ class Client
     */
    public function delete_wlan($wlan_id)
    {
-        $this->request_method = 'DELETE';
+        $this->method = 'DELETE';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/wlanconf/' . trim($wlan_id));
    }
@@ -2894,7 +2912,7 @@ class Client
     */
    public function set_device_settings_base($device_id, $payload)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/device/' . trim($device_id), $payload);
    }
@@ -3001,7 +3019,7 @@ class Client
     */
    public function set_radius_account_base($account_id, $payload)
    {
-        $this->request_method = 'PUT';
+        $this->method = 'PUT';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/account/' . trim($account_id), $payload);
    }
@@ -3017,7 +3035,7 @@ class Client
     */
    public function delete_radius_account($account_id)
    {
-        $this->request_method = 'DELETE';
+        $this->method = 'DELETE';

        return $this->fetch_results_boolean('/api/s/' . $this->site . '/rest/account/' . trim($account_id));
    }
@@ -3057,6 +3075,32 @@ class Client
        return $this->fetch_results_boolean('/api/s/' . $this->site . '/set/setting/element_adopt', $payload);
    }

+    /**
+     * List device states
+     *
+     * NOTE:
+     * this function returns a partial implementation of the codes listed here
+     * https://help.ui.com/hc/en-us/articles/205231710-UniFi-UAP-Status-Meaning-Definitions
+     *
+     * @return array containing translations of UniFi device "state" values to humanized form
+     */
+    public function list_device_states()
+    {
+        $device_states = [
+            0  => 'offline',
+            1  => 'connected',
+            2  => 'pending adoption',
+            4  => 'updating',
+            5  => 'provisioning',
+            6  => 'unreachable',
+            7  => 'adopting',
+            9  => 'adoption error',
+            11 => 'isolated'
+        ];
+
+        return $device_states;
+    }
+
    /**
     * Custom API request
     *
@@ -3064,15 +3108,15 @@ class Client
     * Only use this method when you fully understand the behavior of the UniFi controller API. No input validation is performed, to be used with care!
     *
     * @param  string       $path           suffix of the URL (following the port number) to pass request to, *must* start with a "/" character
-     * @param  string       $request_method optional, HTTP request type, can be GET (default), POST, PUT, PATCH, or DELETE
+     * @param  string       $method optional, HTTP request type, can be GET (default), POST, PUT, PATCH, or DELETE
     * @param  object|array $payload        optional, stdClass object or associative array containing the payload to pass
     * @param  string       $return         optional, string; determines how to return results, when "boolean" the method must return a
     *                                      boolean result (true/false) or "array" when the method must return an array
     * @return bool|array                   returns results as requested, returns false on incorrect parameters
     */
-    public function custom_api_request($path, $request_method = 'GET', $payload = null, $return = 'array')
+    public function custom_api_request($path, $method = 'GET', $payload = null, $return = 'array')
    {
-        if (!in_array($request_method, $this->request_methods_allowed)) {
+        if (!in_array($method, $this->methods_allowed)) {
            return false;
        }

@@ -3080,7 +3124,7 @@ class Client
            return false;
        }

-        $this->request_method = $request_method;
+        $this->method = $method;

        if ($return === 'array') {
            return $this->fetch_results($path, $payload);
@@ -3322,10 +3366,6 @@ class Client
        return $this->class_version;
    }

-    /******************************************************************
-     * other getter/setter functions/methods from here, use with care!
-     ******************************************************************/
-
    /**
     * Set value for the private property $cookies
     *
@@ -3341,25 +3381,25 @@ class Client
     *
     * @return string request type
     */
-    public function get_request_method()
+    public function get_method()
    {
-        return $this->request_method;
+        return $this->method;
    }

    /**
     * Set request method
     *
-     * @param  string $request_method a valid HTTP request method
+     * @param  string $method a valid HTTP request method
     * @return bool           whether request was successful or not
     */
-    public function set_request_method($request_method)
+    public function set_method($method)
    {

-        if (!in_array($request_method, $this->request_methods_allowed)) {
+        if (!in_array($method, $this->methods_allowed)) {
            return false;
        }

-        $this->request_method = $request_method;
+        $this->method = $method;

        return true;
    }
@@ -3369,11 +3409,11 @@ class Client
     *
     * https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html
     *
-     * @return bool value of private property $curl_ssl_verify_peer (cURL option CURLOPT_SSL_VERIFYPEER)
+     * @return bool value of private property $ssl_verify_peer (cURL option CURLOPT_SSL_VERIFYPEER)
     */
    public function get_ssl_verify_peer()
    {
-        return $this->curl_ssl_verify_peer;
+        return $this->ssl_verify_peer;
    }

    /**
@@ -3389,7 +3429,7 @@ class Client
            return false;
        }

-        $this->curl_ssl_verify_peer = $ssl_verify_peer;
+        $this->ssl_verify_peer = $ssl_verify_peer;

        return true;
    }
@@ -3399,11 +3439,11 @@ class Client
     *
     * https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html
     *
-     * @return bool value of private property $curl_ssl_verify_peer (cURL option CURLOPT_SSL_VERIFYHOST)
+     * @return bool value of private property $ssl_verify_peer (cURL option CURLOPT_SSL_VERIFYHOST)
     */
    public function get_ssl_verify_host()
    {
-        return $this->curl_ssl_verify_host;
+        return $this->ssl_verify_host;
    }

    /**
@@ -3419,7 +3459,7 @@ class Client
            return false;
        }

-        $this->curl_ssl_verify_host = $ssl_verify_host;
+        $this->ssl_verify_host = $ssl_verify_host;

        return true;
    }
@@ -3472,7 +3512,7 @@ class Client
    }

    /****************************************************************
-     * internal (private and protected) functions from here:
+     * private and protected functions from here:
     ****************************************************************/

    /**
@@ -3490,15 +3530,18 @@ class Client
    protected function fetch_results($path, $payload = null, $boolean = false, $login_required = true)
    {
        /**
-         * guard clause to check if we are logged in when needed
+         * guard clause to check if logged in when needed
         */
        if ($login_required && !$this->is_loggedin) {
            return false;
        }

-        $response = json_decode($this->exec_curl($path, $payload));
+        $this->last_results_raw = $this->exec_curl($path, $payload);
+
+        if (is_string($this->last_results_raw)) {
+            $response = json_decode($this->last_results_raw);
            $this->catch_json_last_error();
-        $this->last_results_raw = $response;
+
            if (isset($response->meta->rc)) {
                if ($response->meta->rc === 'ok') {
                    $this->last_error_message = null;
@@ -3509,7 +3552,7 @@ class Client
                    return true;
                } elseif ($response->meta->rc === 'error') {
                    /**
-                 * we have an error:
+                     * an error occurred:
                     * set $this->set last_error_message if the returned error message is available
                     */
                    if (isset($response->meta->msg)) {
@@ -3532,7 +3575,10 @@ class Client
                            trigger_error('Debug: Last error message: ' . $this->last_error_message);
                        }
                    }
-            } else {
+
+                    return false;
+                }
+
                return $response;
            }
        }
@@ -3560,12 +3606,12 @@ class Client
     *
     * @return bool returns true upon success, false upon failure
     */
-    private function catch_json_last_error()
+    protected function catch_json_last_error()
    {
        if ($this->debug) {
            switch (json_last_error()) {
                case JSON_ERROR_NONE:
-                    // JSON is valid, no error has occurred and we return true early
+                    // JSON is valid, no error has occurred and return true early
                    return true;
                case JSON_ERROR_DEPTH:
                    $error = 'The maximum stack depth has been exceeded';
@@ -3603,7 +3649,7 @@ class Client
                    $error = 'Malformed UTF-16 characters, possibly incorrectly encoded';
                    break;
                default:
-                    // we have an unknown error
+                    // an unknown error occurred
                    $error = 'Unknown JSON error occurred';
                    break;
            }
@@ -3622,7 +3668,7 @@ class Client
     * @param  string $baseurl the base URL to validate
     * @return bool            true if base URL is a valid URL, else returns false
     */
-    private function check_base_url($baseurl)
+    protected function check_base_url($baseurl)
    {
        if (!filter_var($baseurl, FILTER_VALIDATE_URL) || substr($baseurl, -1) === '/') {
            trigger_error('The URL provided is incomplete, invalid or ends with a / character!');
@@ -3639,7 +3685,7 @@ class Client
     * @param  string $site the (short) site name to check
     * @return bool         true if (short) site name is valid, else returns false
     */
-    private function check_site($site)
+    protected function check_site($site)
    {
        if ($this->debug && preg_match("/\s/", $site)) {
            trigger_error('The provided (short) site name may not contain any spaces');
@@ -3650,21 +3696,18 @@ class Client
        return true;
    }

-    /**
-     */
-
    /**
     * Update the unificookie if sessions are enabled
     *
     * @return bool true when unificookie was updated, else returns false
     */
-    private function update_unificookie()
+    protected function update_unificookie()
    {
        if (session_status() === PHP_SESSION_ACTIVE && isset($_SESSION['unificookie']) && !empty($_SESSION['unificookie'])) {
            $this->cookies = $_SESSION['unificookie'];

            /**
-             * if we have a JWT in our cookie we know we're dealing with a UniFi OS controller
+             * if the cookie contains a JWT this is a UniFi OS controller
             */
            if (strpos($this->cookies, 'TOKEN') !== false) {
                $this->is_unifi_os = true;
@@ -3677,33 +3720,61 @@ class Client
    }

    /**
-     * Add a header containing the CSRF token from our Cookie string
+     * Add a cURL header containing the CSRF token from the TOKEN in our Cookie string
     *
     * @return bool true upon success or false when unable to extract the CSRF token
     */
-    private function create_x_csrf_token_header()
+    protected function create_x_csrf_token_header()
    {
-        if (!empty($this->cookies)) {
+        if (!empty($this->cookies) && strpos($this->cookies, 'TOKEN') !== false) {
            $cookie_bits = explode('=', $this->cookies);
-            if (!empty($cookie_bits) && array_key_exists(1, $cookie_bits)) {
-                $jwt = $cookie_bits[1];
-            } else {
-                return false;
+            if (empty($cookie_bits) || !array_key_exists(1, $cookie_bits)) {
+                return;
            }

-            $jwt_components = explode('.', $jwt);
-            if (!empty($jwt_components) && array_key_exists(1, $jwt_components)) {
-                $jwt_payload = $jwt_components[1];
-            } else {
-                return false;
+            $jwt_components = explode('.', $cookie_bits[1]);
+            if (empty($jwt_components) || !array_key_exists(1, $jwt_components)) {
+                return;
            }

-            $this->headers[] = 'x-csrf-token: ' . json_decode(base64_decode($jwt_payload))->csrfToken;
-
-            return true;
+            $this->headers[] = 'x-csrf-token: ' . json_decode(base64_decode($jwt_components[1]))->csrfToken;
+        }
    }

-        return false;
+    /**
+     * Callback function for cURL to extract and store cookies as needed
+     *
+     * @param  object|resource $ch          the cURL instance
+     * @param  int             $header_line the response header line number
+     * @return int                          length of the header line
+     */
+    protected function response_header_callback($ch, $header_line) {
+        if (strpos($header_line, 'unifises') !== false || strpos($header_line, 'TOKEN') !== false) {
+            $cookie = trim(str_replace(['set-cookie: ', 'Set-Cookie: '], '', $header_line));
+
+            if (!empty($cookie)) {
+                $cookie_crumbs = explode(';', $cookie);
+                foreach ($cookie_crumbs as $cookie_crumb) {
+                    if (strpos($cookie_crumb, 'unifises') !== false) {
+                        $this->cookies     = $cookie_crumb;
+                        $this->is_loggedin = true;
+                        $this->is_unifi_os = false;
+
+                        break;
+                    }
+
+                    if (strpos($cookie_crumb, 'TOKEN') !== false) {
+                        $this->cookies     = $cookie_crumb;
+                        $this->is_loggedin = true;
+                        $this->is_unifi_os = true;
+
+                        break;
+                    }
+                }
+            }
+        }
+
+        return strlen($header_line);
    }

    /**
@@ -3711,60 +3782,61 @@ class Client
     *
     * @param  string            $path    path for the request
     * @param  object|array      $payload optional, payload to pass with the request
-     * @return bool|array            response returned by the controller API, false upon error
+     * @return bool|array|string          response returned by the controller API, false upon error
     */
    protected function exec_curl($path, $payload = null)
    {
-        if (!in_array($this->request_method, $this->request_methods_allowed)) {
-            trigger_error('an invalid HTTP request type was used: ' . $this->request_method);
-        }
-
-        if (!($ch = $this->get_curl_resource())) {
-            trigger_error('$ch as returned by get_curl_resource() is not a resource');
+        if (!in_array($this->method, $this->methods_allowed)) {
+            trigger_error('an invalid HTTP request type was used: ' . $this->method);

            return false;
        }

-        $json_payload = '';
+        if (!($ch = $this->get_curl_resource())) {
+            trigger_error('get_curl_resource() did not return a resource');
+
+            return false;
+        }
+
+        $this->headers = [];
+        $url = $this->baseurl . $path;

        if ($this->is_unifi_os) {
            $url = $this->baseurl . '/proxy/network' . $path;
-        } else {
-            $url = $this->baseurl . $path;
        }

-        /**
-         * prepare cURL options
-         */
        $curl_options = [
            CURLOPT_URL => $url
        ];

        /**
-         * what we do when a payload is passed
+         * when a payload is passed
         */
-        if (!is_null($payload)) {
+        $json_payload  = '';
+        if (!empty($payload)) {
            $json_payload = json_encode($payload, JSON_UNESCAPED_SLASHES);
-            $curl_options[CURLOPT_POST]       = true;
            $curl_options[CURLOPT_POSTFIELDS] = $json_payload;

+            /**
+             * add empty Expect header to prevent cURL from injecting an "Expect: 100-continue" header
+             */
            $this->headers = [
                'content-type: application/json',
-                'content-length: ' . strlen($json_payload)
+                'Expect:'
            ];

            /**
-             * we shouldn't be using GET (the default request type) or DELETE when passing a payload,
+             * should not use GET (the default request type) or DELETE when passing a payload,
             * switch to POST instead
             */
-            if ($this->request_method === 'GET' || $this->request_method === 'DELETE') {
-                $this->request_method = 'POST';
+            if ($this->method === 'GET' || $this->method === 'DELETE') {
+                $this->method = 'POST';
            }
        }

-        switch ($this->request_method) {
+        switch ($this->method) {
            case 'POST':
-                $curl_options[CURLOPT_CUSTOMREQUEST] = 'POST';
+                $curl_options[CURLOPT_POST] = true;
                break;
            case 'DELETE':
                $curl_options[CURLOPT_CUSTOMREQUEST] = 'DELETE';
@@ -3777,7 +3849,7 @@ class Client
                break;
        }

-        if ($this->is_unifi_os && $this->request_method !== 'GET') {
+        if ($this->is_unifi_os && $this->method !== 'GET') {
            $this->create_x_csrf_token_header();
        }

@@ -3802,7 +3874,7 @@ class Client

        /**
         * an HTTP response code 401 (Unauthorized) indicates the Cookie/Token has expired in which case
-         * we need to login again.
+         * re-login is required
         */
        if ($http_code == 401) {
            if ($this->debug) {
@@ -3818,6 +3890,7 @@ class Client
                }

                $this->is_loggedin = false;
+                $this->cookies     = '';
                $this->exec_retries++;
                curl_close($ch);

@@ -3853,10 +3926,9 @@ class Client
            print $url . PHP_EOL;
            if (empty($json_payload)) {
                print 'empty payload';
-            } else {
-                print $json_payload;
            }

+            print $json_payload;
            print PHP_EOL . '----------RESPONSE-----------' . PHP_EOL;
            print $response;
            print PHP_EOL . '-----------------------------' . PHP_EOL;
@@ -3866,9 +3938,9 @@ class Client
        curl_close($ch);

        /**
-         * set request_method value back to default, just in case
+         * set method back to default value, just in case
         */
-        $this->request_method = 'GET';
+        $this->method = 'GET';

        return $response;
    }
@@ -3876,18 +3948,20 @@ class Client
    /**
     * Create a new cURL resource and return a cURL handle
     *
-     * @return object|bool cURL handle upon success, false upon failure
+     * @return object|bool|resource cURL handle upon success, false upon failure
     */
    protected function get_curl_resource()
    {
        $ch = curl_init();
        if (is_object($ch) || is_resource($ch)) {
            $curl_options = [
-                CURLOPT_SSL_VERIFYPEER => $this->curl_ssl_verify_peer,
-                CURLOPT_SSL_VERIFYHOST => $this->curl_ssl_verify_host,
+                CURLOPT_PROTOCOLS      => CURLPROTO_HTTPS | CURLPROTO_HTTP,
+                CURLOPT_SSL_VERIFYPEER => $this->ssl_verify_peer,
+                CURLOPT_SSL_VERIFYHOST => $this->ssl_verify_host,
                CURLOPT_CONNECTTIMEOUT => $this->connect_timeout,
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_ENCODING       => '',
+                CURLOPT_HEADERFUNCTION => [$this, 'response_header_callback'],
            ];

            if ($this->debug) {
Author	SHA1	Message	Date
malle-pietje	665fed93e2	shortened several property names	2021-03-22 11:58:20 +01:00
malle-pietje	36c0fecaff	minor improvements	2021-03-22 11:52:44 +01:00
malle-pietje	474578a9d5	removed non-compliant header suffix	2021-03-21 16:08:55 +01:00
malle-pietje	5281db56de	API client class v1.1.69 - added list_device_states() function/method, as suggested by @hoerter - implemented fix to prevent cURL from sending an `Expect: 100-continue` header with each POST request - implemented a callback function with the CURLOPT_HEADERFUNCTION option to process the response headers after each request and extract the Cookie contents - general cleanup	2021-03-21 16:03:05 +01:00
malle-pietje	021d01ba86	API client class v1.1.68 - fixed a bug that was introduced with 1.1.67 and would only occur in certain corner cases	2021-01-24 18:09:38 +01:00
malle-pietje	caf838abb9	API client class v1.1.67 - fixed a bug where the request headers for subsequent function calls within the same Client instance would not always be cleared	2021-01-24 17:58:23 +01:00
malle-pietje	aa778c9b7b	API client class v1.1.66 - simplified code based on Scrutinizer reports	2021-01-24 14:21:26 +01:00
malle-pietje	0e9ee66cef	updated README to include new functions/methods	2021-01-23 11:44:12 +01:00
malle-pietje	721ba7d084	API client class v1.1.65 - applied minor improvements based on Scrutinizer reports - applied minor changes to `authorize_guest()` to further improve handling of 0/null/empty values passed - restricted protocols to be used by cURL to only allow http and https for improved security - added methods/functions `list_device_name_mappings()` and `stat_full_status()`	2021-01-23 11:41:52 +01:00