various tweaks and an addition

- more relaxed handling of $site in set_site(), now we only issue an error message when provided (short) site name is probably incorrect and debug mode is
true
- added test_connection.php, a command line script which can be used to quickly test the connection to your controller with various cURL options which you can
quickly change

README.md

@@ -6,7 +6,7 @@ This PHP class provides access to Ubiquiti's **UniFi Controller API**. Versions
 
 If you'd like to support further development of this PHP API client class, please use the PayPal donate button below. All donations go to the project maintainer.
 
-[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=M7TVNVX3Z44VN)
+[![Donate](https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=M7TVNVX3Z44VN)
 
 ## Methods and functions supported
 
@@ -113,13 +113,6 @@ Internal functions, getters/setters:
 
 Please refer to the source code for more details on each function/method and it's parameters.
 
-## Credits
-
-This class is largely based on the work done 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://www.ubnt.com/downloads/unifi/5.5.20/unifi_sh_api
-
 ## Requirements
 
 - a web server with PHP and cURL modules installed (tested on apache2 with PHP Version 5.6.1 and cURL 7.42.1)
@@ -133,7 +126,7 @@ You can use **Composer**, **Git** or simply **Download the Release**
 
 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 your project directory:
+Once composer is installed, simply execute this command from the shell in your project directory:
 
 ```sh
 composer require art-of-wifi/unifi-api-client
@@ -183,7 +176,7 @@ require_once('vendor/autoload.php');
  */
 $unifi_connection = new UniFi_API\Client($controller_user, $controller_password, $controller_url, $site_id, $controller_version);
 $login            = $unifi_connection->login();
-$results          = $unifi_connection->list_alarms(); // returns an PHP array containing alarm objects
+$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.
@@ -198,12 +191,19 @@ 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 improve the usability of this class, so all suggestions/comments are welcome. Please use the github [issue](https://github.com/Art-of-WiFi/UniFi-API-client/issues) list 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 ideas.
+There is still work to be done to add functionality and improve the usability of this class, so all suggestions/comments are welcome. Please use the github [issue](https://github.com/Art-of-WiFi/UniFi-API-client/issues) list 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 ideas/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 largely based on the work done 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://www.ubnt.com/downloads/unifi/5.5.20/unifi_sh_api
+
 ## Important Disclaimer
 
 Many of these functions are not officially supported by UBNT and as such, may not be supported in future versions of the UniFi controller API.

examples/test_connection.php

@@ -0,0 +1,67 @@
+<?php
+/**
+ * Test the connection to your UniFi controller
+ *
+ * contributed by: Art of WiFi
+ * description: PHP script to check/debug the connection to your controller using PHP and cURL
+ */
+
+/**
+ * Include the config file (place your credentials etc. there if not already present),
+ * see the config.template.php file for an example.
+ * (will only be used here to get the URL to the controller)
+ */
+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;
+}
+
+/**
+ * create cURL resource
+ */
+$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);
+
+/**
+ * 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);
+
+/**
+ * $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);
+
+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;
+}
+
+print PHP_EOL . '$results:' . PHP_EOL;
+print_r($results);
+print PHP_EOL;

src/Client.php

@@ -24,17 +24,16 @@ class Client
     /**
      * private properties
      */
-    private $user;
-    private $password;
-    private $baseurl      = 'https://127.0.0.1:8443';
-    private $site         = 'default';
-    private $version      = '5.4.16';
-    private $debug        = false;
-    private $is_loggedin  = false;
-    private $cookies      = '';
-    private $request_type = 'POST';
-    private $last_results_raw;
-    private $last_error_message;
+    private $baseurl            = 'https://127.0.0.1:8443';
+    private $site               = 'default';
+    private $version            = '5.4.16';
+    private $debug              = false;
+    private $is_loggedin        = false;
+    private $cookies            = '';
+    private $request_type       = 'POST';
+    private $connect_timeout    = 10;
+    private $last_results_raw   = null;
+    private $last_error_message = null;
 
     function __construct($user, $password, $baseurl = '', $site = '', $version = '')
     {
@@ -60,7 +59,7 @@ class Client
         }
 
         if (strlen($this->site) !== 8 && $this->site !== 'default' && $this->debug) {
-            error_log('The provided short site name is probably incorrect');
+            error_log('The provided (short) site name is probably incorrect');
         }
     }
 
@@ -97,7 +96,12 @@ class Client
         curl_setopt($ch, CURLOPT_URL, $this->baseurl.'/api/login');
         curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['username' => $this->user, 'password' => $this->password]));
 
-        if (($content = curl_exec($ch)) === false) {
+        /**
+         * execute the cURL request
+         */
+        $content = curl_exec($ch);
+
+        if (curl_errno($ch)) {
             trigger_error('cURL error: '.curl_error($ch));
         }
 
@@ -159,7 +163,6 @@ class Client
      * Set site
      * --------
      * modify the private property site, returns the new (short) site name
-     * returns the new short name, or false if string length is incorrect or not 'default'
      * required parameter <site> = string; must be the short site name of a site to which the
      *                             provided credentials have access
      *
@@ -168,13 +171,12 @@ class Client
      */
     public function set_site($site)
     {
-        if (strlen($site) === 8 || $site === 'default') {
-            $this->site = $site;
-
-            return $this->site;
-        } else {
-            return false;
+        if (strlen($site) !== 8 && $site !== 'default' && $this->debug) {
+            error_log('The provided (short) site name is probably incorrect');
         }
+
+        $this->site = $site;
+        return $this->site;
     }
 
     /**
@@ -209,15 +211,13 @@ class Client
     /**
      * Get last raw results
      * --------------------
-     * returns the raw results of the last method called in PHP stdClass Object format by default, returns false if not set
-     * optional parameter <return_json> = boolean; true will return the results in "pretty printed" json format
-     *
-     * NOTE:
-     * this method can be used to get the full error as returned by the controller
+     * returns the raw results of the last method called, returns false if unavailable
+     * optional parameter <return_json> = boolean; true will return the results in "pretty printed" json format,
+     *                                    PHP stdClass Object format is returned by default
      */
     public function get_last_results_raw($return_json = false)
     {
-        if ($this->last_results_raw != null) {
+        if ($this->last_results_raw !== null) {
             if ($return_json) {
                 return json_encode($this->last_results_raw, JSON_PRETTY_PRINT);
             }
@@ -231,11 +231,11 @@ class Client
     /**
      * Get last error message
      * ----------------------
-     * returns the error message of the last method called in PHP stdClass Object format, returns false if not set
+     * returns the error message of the last method called in PHP stdClass Object format, returns false if unavailable
      */
     public function get_last_error_message()
     {
-        if (isset($this->last_error_message)) {
+        if ($this->last_error_message  !== null) {
             return $this->last_error_message;
         }
 
@@ -1884,7 +1884,12 @@ class Client
             }
         }
 
-        if (($content = curl_exec($ch)) === false) {
+        /**
+         * execute the cURL request
+         */
+        $content = curl_exec($ch);
+
+        if (curl_errno($ch)) {
             trigger_error('cURL error: '.curl_error($ch));
         }
 
@@ -1892,9 +1897,10 @@ class Client
          * has the session timed out?
          */
         $httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
-        $strerr   = '{ "data" : [ ] , "meta" : { "msg" : "api.err.LoginRequired" , "rc" : "error"}}';
 
-        if ($httpcode == 401 && strcmp($content, $strerr) == 0) {
+        $json_decoded_content = json_decode($content, true);
+
+        if ($httpcode == 401 && isset($json_decoded_content['meta']['msg']) && $json_decoded_content['meta']['msg'] === 'api.err.LoginRequired') {
             if ($this->debug) {
                 error_log('cURL debug: Needed reconnect to UniFi Controller');
             }
@@ -1960,6 +1966,7 @@ class Client
         curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
         curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
         curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+        curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $this->connect_timeout);
 
         if ($this->debug) {
             curl_setopt($ch, CURLOPT_VERBOSE, true);