API client class v1.1.51

- updated README with all getter and setter methods/functions - updated get_cookies() and get_cookie() for consistency - get_cookie() remains for backward compatibility only, should not be used in new code - fix rare cases where the client would end up in a loop, e.g. issuing a request for a site the cached credentials have no access to
API client class v1.1.50
2020-03-19 16:07:31 +01:00 · 2020-02-22 17:19:32 +01:00 · 2020-02-07 08:27:39 +01:00
4 changed files with 265 additions and 187 deletions
--- 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 SDN Controller**](https://unifi-sdn.ui.com/) API, versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.12.35 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 in 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 SDN Controller**](https://unifi-sdn.ui.com/) API, versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.12.66 has been confirmed to work) as well as UbiOS-based controllers (version 5.12.59 has been confirmed to work). This class is used in 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 using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.

@@ -9,11 +9,11 @@ The package can be installed manually or using composer/[packagist](https://pack
 - 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.24 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

-## UniFi OS Support
+## UbiOS 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 UbiOS-based controllers (UniFi Dream Machine Pro) has been added as of version 1.1.47. The class automatically detects UbiOS 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 UbiOS-based controller.

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

 ## Installation

@@ -100,7 +100,7 @@ Please refer to the `examples/` directory for some more detailed examples which

 ## 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.
+The class currently supports the following functions/methods to GET/POST/PUT/DELETE data through the UniFi Controller API. Please refer to the comments in the source code for more details on the functions/methods and their respective parameters.

 - login()
 - logout()
@@ -242,15 +242,28 @@ The class currently supports the following functions/methods to GET/POST/PUT/DEL
 - cancel_rolling_upgrade()
 - cmd_stat()

-Internal functions, getters/setters:
+Other functions, getters/setters:

 - set_debug()
 - get_debug()
 - set_site()
 - get_site()
- get_cookie() (renamed from getcookie())
+- set_cookies()
+- get_cookies()
+- get_cookie() (renamed from getcookie(), deprecated but still available, use get_cookies() instead)
 - get_last_results_raw()
 - get_last_error_message()
+- set_request_type()
+- get_request_type()
+- set_ssl_verify_peer()
+- get_ssl_verify_peer()
+- set_ssl_verify_host()
+- get_ssl_verify_host()
+- set_connection_timeout()
+- get_connection_timeout()
+- set_is_unifi_os()
+- get_is_unifi_os()
+

 ## Need help or have suggestions?

--- a/examples/block_list.php
+++ b/examples/block_list.php
@@ -47,7 +47,7 @@ $unifi_connection = new UniFi_API\Client($controlleruser, $controllerpassword, $
 $set_debug_mode   = $unifi_connection->set_debug($debug);
 $loginresults     = $unifi_connection->login(); // always true regardless of site id

-foreach ($macs_to_block as &$mac) {
+foreach ($macs_to_block as $mac) {
    // block_result is always true even if mac address does not exist :(
    $block_result = $unifi_connection->block_sta($mac);

--- a/examples/test_connection.php
+++ b/examples/test_connection.php
@@ -17,7 +17,7 @@ require_once('config.php');
 * Check whether the cURL module supports SSL
 */
 if (!curl_version()['features'] & CURL_VERSION_SSL) {
-    print 'SSL is not supported with this cURL installation!' . PHP_EOL;
+    print PHP_EOL . 'SSL is not supported with this cURL installation!' . PHP_EOL;
 }

 /**
@@ -25,44 +25,48 @@ if (!curl_version()['features'] & CURL_VERSION_SSL) {
 */
 $ch = curl_init();

-/**
- * Set the required cURL options
- */
-curl_setopt($ch, CURLOPT_URL, $controllerurl);
-curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
-curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
-curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
+if (is_resource($ch)) {
+    /**
+     * If we have a resource, we proceed and set the required cURL options
+     */
+    curl_setopt($ch, CURLOPT_URL, $controllerurl);
+    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
+    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
+    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);

-/**
- * This cURL option can have a value of 0-6
- * see this URL for more details:
- * http://php.net/manual/en/function.curl-setopt.php
- * 0 is the default value and is used by the PHP API client class
- */
-curl_setopt($ch, CURLOPT_SSLVERSION, 0);
+    /**
+     * This cURL option can have a value of 0-6
+     * see this URL for more details:
+     * http://php.net/manual/en/function.curl-setopt.php
+     * 0 is the default value and is used by the PHP API client class
+     */
+    curl_setopt($ch, CURLOPT_SSLVERSION, 0);

-/**
- * Be more verbose
- */
-curl_setopt($ch, CURLOPT_VERBOSE, true);
+    /**
+     * Be more verbose
+     */
+    curl_setopt($ch, CURLOPT_VERBOSE, true);

-/**
- * $results contains the output as returned by the cURL request,
- * returns true when successful, else returns false
- */
-print 'verbose output from the cURL request:' . PHP_EOL;
-$results = curl_exec($ch);
+    /**
+     * $results contains the output as returned by the cURL request,
+     * returns true when successful, else returns false
+     */
+    print PHP_EOL . 'verbose output from the cURL request:' . PHP_EOL;
+    $results = curl_exec($ch);

-print PHP_EOL . 'curl_getinfo output:' . PHP_EOL;
-print_r(curl_getinfo($ch));
+    print PHP_EOL . 'curl_getinfo output:' . PHP_EOL;
+    print_r(curl_getinfo($ch));

-/**
- * If we receive a cURL error, output it before the results
- */
-if (curl_errno($ch)) {
-    print PHP_EOL . 'cURL error: ' . curl_error($ch) . PHP_EOL;
+    /**
+     * If we receive a cURL error, output it before the results
+     */
+    if (curl_errno($ch)) {
+        print PHP_EOL . 'cURL error: ' . curl_error($ch) . PHP_EOL;
+    }
+
+    print PHP_EOL . '$results:' . PHP_EOL;
+    print_r($results);
+    print PHP_EOL;
+} else {
+    print PHP_EOL . 'ERROR: cURL could not be initialized!' . PHP_EOL;
 }
-
-print PHP_EOL . '$results:' . PHP_EOL;
-print_r($results);
-print PHP_EOL;
--- a/src/Client.php
+++ b/src/Client.php
@@ -84,7 +84,6 @@ class Client

        $this->check_base_url();
        $this->check_site($this->site);
-        $this->update_unificookie();
    }

    /**
@@ -126,90 +125,100 @@ class Client
            return true;
        }

+        if ($this->update_unificookie()) {
+            $this->is_loggedin = true;
+
+            return true;
+        }
+
        /**
-         * check whether we have a "regular" controller or one based on UniFi OS
+         * first we check whether we have a "regular" controller or one based on UniFi OS
         */
-        if (!($ch = $this->get_curl_resource())) {
-            trigger_error('$ch as returned by get_curl_resource() is not a resource');
+        $ch = $this->get_curl_resource();
+        curl_setopt($ch, CURLOPT_HEADER, true);
+        curl_setopt($ch, CURLOPT_POST, true);
+        curl_setopt($ch, CURLOPT_NOBODY, true);
+        curl_setopt($ch, CURLOPT_URL, $this->baseurl . '/');
+
+        /**
+         * execute the cURL request and get the HTTP response code
+         */
+        curl_exec($ch);
+        $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+
+        if (curl_errno($ch)) {
+            trigger_error('cURL error: ' . curl_error($ch));
+        }
+
+        if ($http_code === 200) {
+            $this->is_unifi_os = true;
+            curl_setopt($ch, CURLOPT_REFERER, $this->baseurl . '/login');
+            curl_setopt($ch, CURLOPT_URL, $this->baseurl . '/api/auth/login');
        } else {
-            curl_setopt($ch, CURLOPT_HEADER, true);
-            curl_setopt($ch, CURLOPT_POST, true);
-            curl_setopt($ch, CURLOPT_NOBODY, true);
-            curl_setopt($ch, CURLOPT_URL, $this->baseurl . '/');
+            curl_setopt($ch, CURLOPT_REFERER, $this->baseurl . '/login');
+            curl_setopt($ch, CURLOPT_URL, $this->baseurl . '/api/login');
+        }

-            /**
-             * execute the cURL request and get the HTTP response code
-             */
-            curl_exec($ch);
-            $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+        curl_setopt($ch, CURLOPT_NOBODY, false);
+        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['username' => $this->user, 'password' => $this->password]));
+        curl_setopt($ch, CURLOPT_HTTPHEADER, ['content-type: application/json; charset=utf-8']);

-            if (curl_errno($ch)) {
-                trigger_error('cURL error: ' . curl_error($ch));
-            }
+        /**
+         * execute the cURL request and get the HTTP response code
+         */
+        $content   = curl_exec($ch);
+        $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

-            if ($http_code === 200) {
-                $this->is_unifi_os = true;
-            }
+        if (curl_errno($ch)) {
+            trigger_error('cURL error: ' . curl_error($ch));
+        }

-            if ($this->is_unifi_os) {
-                curl_setopt($ch, CURLOPT_REFERER, $this->baseurl . '/login');
-                curl_setopt($ch, CURLOPT_URL, $this->baseurl . '/api/auth/login');
-            } else {
-                curl_setopt($ch, CURLOPT_REFERER, $this->baseurl . '/login');
-                curl_setopt($ch, CURLOPT_URL, $this->baseurl . '/api/login');
-            }
+        if ($this->debug) {
+            print PHP_EOL . '<pre>';
+            print PHP_EOL . '-----------LOGIN-------------' . PHP_EOL;
+            print_r(curl_getinfo($ch));
+            print PHP_EOL . '----------RESPONSE-----------' . PHP_EOL;
+            print $content;
+            print PHP_EOL . '-----------------------------' . PHP_EOL;
+            print '</pre>' . PHP_EOL;
+        }

-            curl_setopt($ch, CURLOPT_NOBODY, false);
-            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['username' => $this->user, 'password' => $this->password]));
-            curl_setopt($ch, CURLOPT_HTTPHEADER, ['content-type: application/json; charset=utf-8']);
+        /**
+         * based on the HTTP response code we either trigger an error or
+         * extract the cookie from the headers
+         */
+        if ($http_code === 400 || $http_code === 401) {
+            trigger_error("We received the following HTTP response status: $http_code. Probably a controller login failure");

-            /**
-             * execute the cURL request and get the HTTP response code
-             */
-            $content   = curl_exec($ch);
-            $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+            return $http_code;
+        }

-            if (curl_errno($ch)) {
-                trigger_error('cURL error: ' . curl_error($ch));
-            }
+        $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
+        $headers     = substr($content, 0, $header_size);
+        $body        = trim(substr($content, $header_size));

-            if ($this->debug) {
-                print PHP_EOL . '<pre>';
-                print PHP_EOL . '-----------LOGIN-------------' . PHP_EOL;
-                print_r(curl_getinfo($ch));
-                print PHP_EOL . '----------RESPONSE-----------' . PHP_EOL;
-                print $content;
-                print PHP_EOL . '-----------------------------' . PHP_EOL;
-                print '</pre>' . PHP_EOL;
-            }
+        curl_close($ch);

-            /**
-             * based on the HTTP response code we either trigger an error or
-             * extract the cookie from the headers
-             */
-            if ($http_code === 400) {
-                trigger_error('We received an HTTP response status: 400. Probably a controller login failure');
-
-                return $http_code;
-            }
-
-            $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
-            $headers     = substr($content, 0, $header_size);
-            $body        = trim(substr($content, $header_size));
-
-            curl_close($ch);
-
-            if ($http_code >= 200 && $http_code < 400 && !empty($body)) {
-                preg_match_all('|Set-Cookie: (.*);|Ui', $headers, $results);
-                if (isset($results[1])) {
-                    $this->cookies = implode(';', $results[1]);
+        /**
+         * we are good to extract the cookies
+         */
+        if ($http_code >= 200 && $http_code < 400 && !empty($body)) {
+            preg_match_all('|Set-Cookie: (.*);|Ui', $headers, $results);
+            if (isset($results[1])) {
+                $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) {
                    /**
-                     * accept cookies from UniFi OS or from regular UNiFI controllers
+                     * update the cookie value in $_SESSION['unificookie'], if it exists
                     */
-                    if (strpos($this->cookies, 'unifises') !== false || strpos($this->cookies, 'TOKEN') !== false) {
-                        return $this->is_loggedin = true;
+                    if (isset($_SESSION['unificookie'])) {
+                        $_SESSION['unificookie'] = $this->cookies;
                    }
+
+                    return $this->is_loggedin = true;
                }
            }
        }
@@ -228,13 +237,42 @@ class Client
            return false;
        }

+        /**
+         * prepare cURL
+         */
+        $ch = $this->get_curl_resource();
+        curl_setopt($ch, CURLOPT_HEADER, true);
+        curl_setopt($ch, CURLOPT_POST, true);
+
+        /**
+         * constuct HTTP request headers as required
+         */
+        $headers = ['Content-Length: 0'];
        if ($this->is_unifi_os) {
-            $logout_url = '/api/auth/logout';
+            $logout_path = '/api/auth/logout';
+            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
+
+            $csrf_token = $this->extract_csrf_token_from_cookie();
+            if ($csrf_token) {
+                $headers[] = 'x-csrf-token: ' . $csrf_token;
+            }
        } else {
-            $logout_url = '/logout';
+            $logout_path = '/logout';
        }

-        $this->exec_curl($logout_url, []);
+        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
+        curl_setopt($ch, CURLOPT_URL, $this->baseurl . $logout_path);
+
+        /**
+         * execute the cURL request to logout
+         */
+        $logout = curl_exec($ch);
+
+        if (curl_errno($ch)) {
+            trigger_error('cURL error: ' . curl_error($ch));
+        }
+
+        curl_close($ch);

        $this->is_loggedin = false;
        $this->cookies     = '';
@@ -3656,8 +3694,8 @@ class Client
    }

    /**
-     * Get Cookie from UniFi controller
-     * --------------------------------
+     * Get Cookie from UniFi controller (singular and plural)
+     * ------------------------------------------------------
     * returns the UniFi controller cookie
     *
     * NOTES:
@@ -3677,12 +3715,22 @@ class Client
        return $this->cookies;
    }

+    public function get_cookies()
+    {
+        if (!$this->is_loggedin) {
+            return false;
+        }
+
+        return $this->cookies;
+    }
+
    /******************************************************************
     * other getter/setter functions/methods from here, use with care!
     ******************************************************************/
-    public function get_cookies()
+
+    public function set_cookies($cookies_value)
    {
-        return $this->cookies;
+        $this->cookies = $cookies_value;
    }

    public function get_request_type()
@@ -3690,21 +3738,6 @@ class Client
        return $this->request_type;
    }

-    public function get_ssl_verify_peer()
-    {
-        return $this->curl_ssl_verify_peer;
-    }
-
-    public function get_ssl_verify_host()
-    {
-        return $this->curl_ssl_verify_host;
-    }
-
-    public function set_cookies($cookies_value)
-    {
-        $this->cookies = $cookies_value;
-    }
-
    public function set_request_type($request_type)
    {

@@ -3717,19 +3750,9 @@ class Client
        return true;
    }

-    public function set_connection_timeout($timeout)
+    public function get_ssl_verify_peer()
    {
-        $this->connect_timeout = $timeout;
-    }
-
-    public function set_last_results_raw($last_results)
-    {
-        $this->last_results_raw = $last_results;
-    }
-
-    public function set_last_error_message($last_error_message)
-    {
-        $this->last_error_message = $last_error_message;
+        return $this->curl_ssl_verify_peer;
    }

    /**
@@ -3747,6 +3770,11 @@ class Client
        return true;
    }

+    public function get_ssl_verify_host()
+    {
+        return $this->curl_ssl_verify_host;
+    }
+
    /**
     * set the value for cURL option CURLOPT_SSL_VERIFYHOST, should be 0/false or 2
     * https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html
@@ -3762,6 +3790,42 @@ class Client
        return true;
    }

+    public function get_is_unifi_os()
+    {
+        return $this->is_unifi_os;
+    }
+
+    public function set_is_unifi_os($is_unifi_os)
+    {
+        if (!in_array($is_unifi_os, [0, false, 1, true])) {
+            return false;
+        }
+
+        $this->is_unifi_os = $is_unifi_os;
+
+        return true;
+    }
+
+    public function set_connection_timeout($timeout)
+    {
+        $this->connect_timeout = $timeout;
+    }
+
+    public function get_connection_timeout()
+    {
+        return $this->connect_timeout;
+    }
+
+    public function set_last_results_raw($last_results)
+    {
+        $this->last_results_raw = $last_results;
+    }
+
+    public function set_last_error_message($last_error_message)
+    {
+        $this->last_error_message = $last_error_message;
+    }
+
    /****************************************************************
     * internal (private and protected) functions from here:
     ****************************************************************/
@@ -3921,13 +3985,12 @@ class Client
    }

    /**
-     * Update the unificookie
+     * Update the unificookie if sessions are enabled
     */
    private function update_unificookie()
    {
-        if (isset($_SESSION['unificookie']) && !empty($_SESSION['unificookie'])) {
+        if (session_status() === PHP_SESSION_ACTIVE && isset($_SESSION['unificookie']) && !empty($_SESSION['unificookie'])) {
            $this->cookies = $_SESSION['unificookie'];
-            $this->is_loggedin = true;

            /**
             * if we have a JWT in our cookie we know we're dealing with a UniFi OS controller
@@ -4039,48 +4102,45 @@ class Client
            }

            /**
-             * has the Cookie/Token expired? If so, we need to login again.
+             * an HTTP response code 401 (Unauthorized) indicates the Cookie/Token has expired in which case
+             * we need to login again.
             */
            $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
-
            if ($http_code == 401) {
-                $json_decoded_content = json_decode($content, true);
-
-                if (isset($json_decoded_content['meta']['msg']) && $json_decoded_content['meta']['msg'] === 'api.err.LoginRequired') {
-                    if ($this->debug) {
-                        error_log('cURL debug: needed to reconnect to UniFi controller');
-                    }
-
-                    /**
-                     * explicitly clear the expired Cookie/Token now
-                     */
-                    if (isset($_SESSION['unificookie'])) {
-                        $_SESSION['unificookie'] = '';
-                    }
-
-                    /**
-                     * then login again
-                     */
-                    $this->login();
-
-                    /**
-                     * when login was successful, execute the same command again
-                     */
-                    if ($this->is_loggedin) {
-                        curl_close($ch);
-
-                        /**
-                         * setup the cookie for the user within $_SESSION, if $_SESSION['unificookie'] does not exist
-                         */
-                        if (!isset($_SESSION['unificookie']) && session_status() != PHP_SESSION_DISABLED) {
-                            $_SESSION['unificookie'] = $this->cookies;
-                        }
-
-                        return $this->exec_curl($path, $payload);
-                    }
+                if ($this->debug) {
+                    error_log('cURL debug: needed to reconnect to UniFi controller');
                }

-                unset($json_decoded_content);
+                /**
+                 * explicitly clear the expired Cookie/Token and logging out before logging in again
+                 */
+                if (isset($_SESSION['unificookie'])) {
+                    $_SESSION['unificookie'] = '';
+                }
+
+                $this->is_loggedin = false;
+
+                /**
+                 * then login again
+                 */
+                $this->login();
+
+                /**
+                 * when login was successful, execute the same cURL request again
+                 */
+                if ($this->is_loggedin) {
+                    $content = curl_exec($ch);
+                    if (curl_errno($ch)) {
+                        trigger_error('cURL error: ' . curl_error($ch));
+                        curl_close($ch);
+
+                        return false;
+                    }
+                } else {
+                    curl_close($ch);
+
+                    return false;
+                }
            }

            if ($this->debug) {
@@ -4109,6 +4169,7 @@ class Client
            $this->request_type = 'GET';

            return $content;
+
        }

        return false;