fixed functions assign_existing_admin() and invite_admin() to support controller versions 5.9 and higher because of changes in controller behavior

added function/method assign_existing_admin()
fixed code for function/method invite_admin()

README.md

@@ -1,12 +1,100 @@
 ## UniFi Controller API client class
 
-A PHP class which provides access to Ubiquiti's **UniFi Controller API**, versions 4.X.X and 5.X.X of the UniFi Controller software are supported (version 5.9.29 has been confirmed to work). It's a standalone version of the class which is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
+A PHP class which provides access to Ubiquiti's [**UniFi SDN Controller API**](https://unifi-sdn.ui.com/), versions 4.X.X and 5.X.X of the UniFi SDN Controller software are supported (version 5.10.5 has been confirmed to work). It's a standalone version of the class which is used in our API browser tool which can be found [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
 
 This class can be installed manually or using composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for easy inclusion in your projects.
 
+## Requirements
+
+- a web server with PHP and cURL modules installed (tested on Apache 2.4 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.2.10 and cURL 7.58.0)
+- network connectivity between this web server and the server and port (normally TCP port 8443) where the UniFi Controller is running
+
+## Installation ##
+
+You can use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client class.
+
+### Composer
+
+The preferred method is via [composer](https://getcomposer.org). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.
+
+Once composer is installed, simply execute this command from the shell in your project directory:
+
+```sh
+composer require art-of-wifi/unifi-api-client
+```
+
+ Or you can manually add the package to your composer.json file:
+
+```javascript
+{
+    "require": {
+        "art-of-wifi/unifi-api-client": "^1.1"
+    }
+}
+```
+
+Finally, be sure to include the autoloader in your code:
+
+```php
+require_once('vendor/autoload.php');
+```
+
+### Git
+
+Execute the following `git` command from the shell in your project directory:
+
+```sh
+git clone https://github.com/Art-of-WiFi/UniFi-API-client.git
+```
+
+When git is done cloning, include the file containing the class like so in your code:
+
+```php
+require_once('path/to/src/Client.php');
+```
+
+### Download the Release
+
+If you prefer not to use composer or git, you can simply [download the package](https://github.com/Art-of-WiFi/UniFi-API-client/archive/master.zip), uncompress the zip file, then include the file containing the class in your code like so:
+
+```php
+require_once('path/to/src/Client.php');
+```
+
+## Example usage
+
+A basic example how to use the class:
+
+```php
+/**
+ * load the class using the composer autoloader
+ */
+require_once('vendor/autoload.php');
+
+/**
+ * initialize the Unifi API connection class, log in to the controller and request the alarms collection
+ * (this example assumes you have already assigned the correct values to the variables used)
+ */
+$unifi_connection = new UniFi_API\Client($controller_user, $controller_password, $controller_url, $site_id, $controller_version, true);
+$login            = $unifi_connection->login();
+$results          = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects
+```
+
+Please refer to the `examples/` directory for some more detailed examples which you can use as a starting point for your own PHP code.
+
+#### IMPORTANT NOTES:
+
+1. In the above example, `$site_id` is the short site "name" (usually 8 characters long) that is visible in the URL when managing the site in the UniFi SDN Controller, for example with this URL:
+
+   `https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard`
+
+   `jl3z2shm` is the short site "name" and the value to assign to $site_id.
+
+2. The last optional parameter that is passed to the constructor in the above example (`true`), enables validation of the controller's SSL certificate which is otherwise **disabled** by default. It is highly recommended to enable this feature in production environments where you have a valid SSL cert installed on the UniFi Controller, and which is associated with the FQDN of the server as used in the `controller_url` parameter. This option was added with API client version 1.1.16.
+
 ## Methods and functions supported
 
-The class currently supports the following functions/methods to get/post/put/delete data through the UniFi Controller API:
+The class currently supports the following functions/methods to get/post/put/delete data through the UniFi Controller API. Please refer to the source code for more details on the functions/methods and their respective parameters.
 
 - login()
 - logout()
@@ -151,96 +239,6 @@ Internal functions, getters/setters:
 - get_last_results_raw()
 - get_last_error_message()
 
-Please refer to the source code for more details on the functions/methods and their parameters.
-
-## Requirements
-
-- a web server with PHP and cURL modules installed (tested on apache2 with PHP Version 5.6.1 and cURL 7.42.1 and with PHP 7.0.7 and cURL 7.37.0)
-- network connectivity between this web server and the server and port (normally TCP port 8443) where the UniFi Controller is running
-
-## Installation ##
-
-You can use [Composer](#composer), [Git](#git) or simply [Download the Release](#download-the-release) to install the API client class.
-
-### Composer
-
-The preferred method is via [composer](https://getcomposer.org). Follow the [installation instructions](https://getcomposer.org/doc/00-intro.md) if you do not already have composer installed.
-
-Once composer is installed, simply execute this command from the shell in your project directory:
-
-```sh
-composer require art-of-wifi/unifi-api-client
-```
-
- Or you can manually add the package to your composer.json file:
-
-```javascript
-{
-    "require": {
-        "art-of-wifi/unifi-api-client": "^1.1"
-    }
-}
-```
-
-Finally, be sure to include the autoloader in your code:
-
-```php
-require_once('vendor/autoload.php');
-```
-
-### Git
-
-Execute the following `git` command from the shell in your project directory:
-
-```sh
-git clone https://github.com/Art-of-WiFi/UniFi-API-client.git
-```
-
-When git is done cloning, include the file containing the class like so in your code:
-
-```php
-require_once('path/to/src/Client.php');
-```
-
-### Download the Release
-
-If you prefer not to use composer or git, you can simply [download the package](https://github.com/Art-of-WiFi/UniFi-API-client/archive/master.zip), uncompress the zip file, then include the file containing the class in your code like so:
-
-```php
-require_once('path/to/src/Client.php');
-```
-
-## Example usage
-
-A basic example how to use the class:
-
-```php
-/**
- * load the class using the composer autoloader
- */
-require_once('vendor/autoload.php');
-
-/**
- * initialize the Unifi API connection class, log in to the controller and request the alarms collection
- * (this example assumes you have already assigned the correct values to the variables used)
- */
-$unifi_connection = new UniFi_API\Client($controller_user, $controller_password, $controller_url, $site_id, $controller_version, true);
-$login            = $unifi_connection->login();
-$results          = $unifi_connection->list_alarms(); // returns a PHP array containing alarm objects
-```
-
-Please refer to the `examples/` directory for some more detailed examples which you can use as a starting point for your own PHP code.
-
-#### IMPORTANT NOTES:
-
-1. The last optional parameter that is passed to the constructor in the above example (`true`), enables validation of the controller's SSL certificate which is otherwise **disabled** by default. It is highly recommended to enable this feature in production environments where you have a valid SSL cert installed on the UniFi Controller, and which is associated with the FQDN of the server as used in the `controller_url` parameter. This option was added with API client version 1.1.16.
-
-2. In the example above, `$site_id` is the 8 character short site "name" which is visible in the URL when managing the site in the UniFi Controller:
-
-   `https://<controller IP address or FQDN>:8443/manage/site/jl3z2shm/dashboard`
-
-   In this case, `jl3z2shm` is the value required for $site_id.
-
 ## Need help or have suggestions?
 
 There is still work to be done to add functionality and further improve the usability of this class, so all suggestions/comments are welcome. Please use the GitHub [issue list](https://github.com/Art-of-WiFi/UniFi-API-client/issues) or the Ubiquiti Community forums (https://community.ubnt.com/t5/UniFi-Wireless/PHP-class-to-access-the-UniFi-controller-API-updates-and/td-p/1512870) to share your suggestions and questions.
@@ -251,10 +249,10 @@ If you would like to contribute code (improvements), please open an issue and in
 
 ## Credits
 
-This class is based on the work done by the following developers:
+This class is based on the initial work 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://dl.ubnt.com/unifi/5.8.24/unifi_sh_api
+- and the API as published by Ubiquiti: https://dl.ubnt.com/unifi/5.9.29/unifi_sh_api
 
 ## Important Disclaimer
 

src/Client.php

@@ -143,26 +143,27 @@ class Client
         }
 
         $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
+        $headers     = substr($content, 0, $header_size);
         $body        = trim(substr($content, $header_size));
-        $code        = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+        $http_code   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 
         curl_close($ch);
 
-        preg_match_all('|Set-Cookie: (.*);|U', substr($content, 0, $header_size), $results);
+        preg_match_all('|Set-Cookie: (.*);|Ui', $headers, $results);
 
         if (isset($results[1])) {
             $this->cookies = implode(';', $results[1]);
             if (!empty($body)) {
-                if (($code >= 200) && ($code < 400)) {
+                if (($http_code >= 200) && ($http_code < 400)) {
                     if (strpos($this->cookies, 'unifises') !== false) {
                         return $this->is_loggedin = true;
                     }
                 }
 
-                if ($code === 400) {
+                if ($http_code === 400) {
                     trigger_error('We have received an HTTP response status: 400. Probably a controller login failure');
 
-                    return $code;
+                    return $http_code;
                 }
             }
         }
@@ -1521,7 +1522,7 @@ class Client
         $this->request_type = 'PUT';
         $json               = json_encode($setting);
         $response           = $this->exec_curl('/api/s/' . $this->site . '/rest/setting/country/' . trim($country_id),
-            'json=' . $json);
+                              'json=' . $json);
 
         return $this->process_response_boolean($response);
     }
@@ -1543,7 +1544,7 @@ class Client
         $this->request_type = 'PUT';
         $json               = json_encode($setting);
         $response           = $this->exec_curl('/api/s/' . $this->site . '/rest/setting/locale/' . trim($locale_id),
-            'json=' . $json);
+                              'json=' . $json);
 
         return $this->process_response_boolean($response);
     }
@@ -1565,7 +1566,7 @@ class Client
         $this->request_type = 'PUT';
         $json               = json_encode($setting);
         $response           = $this->exec_curl('/api/s/' . $this->site . '/rest/setting/snmp/' . trim($snmp_id),
-            'json=' . $json);
+                              'json=' . $json);
 
         return $this->process_response_boolean($response);
     }
@@ -1587,7 +1588,7 @@ class Client
         $this->request_type = 'PUT';
         $json               = json_encode($setting);
         $response           = $this->exec_curl('/api/s/' . $this->site . '/rest/setting/mgmt/' . trim($mgmt_id),
-            'json=' . $json);
+                              'json=' . $json);
 
         return $this->process_response_boolean($response);
     }
@@ -1609,7 +1610,7 @@ class Client
         $this->request_type = 'PUT';
         $json               = json_encode($setting);
         $response           = $this->exec_curl('/api/s/' . $this->site . '/rest/setting/guest_access/' . trim($guest_access_id),
-            'json=' . $json);
+                              'json=' . $json);
 
         return $this->process_response_boolean($response);
     }
@@ -1631,7 +1632,7 @@ class Client
         $this->request_type = 'PUT';
         $json               = json_encode($setting);
         $response           = $this->exec_curl('/api/s/' . $this->site . '/rest/setting/ntp/' . trim($ntp_id),
-            'json=' . $json);
+                              'json=' . $json);
 
         return $this->process_response_boolean($response);
     }
@@ -1653,7 +1654,7 @@ class Client
         $this->request_type = 'PUT';
         $json               = json_encode($setting);
         $response           = $this->exec_curl('/api/s/' . $this->site . '/rest/setting/connectivity/' . trim($connectivity_id),
-            'json=' . $json);
+                              'json=' . $json);
 
         return $this->process_response_boolean($response);
     }
@@ -1700,14 +1701,14 @@ class Client
      * optional parameter <enable_sso>     = boolean, whether or not SSO will be allowed for the new admin
      *                                       default value is true which enables the SSO capability
      * optional parameter <readonly>       = boolean, whether or not the new admin will have readonly
-     *                                       permissions, default value is true which gives the new admin
+     *                                       permissions, default value is false which gives the new admin
-     *                                       administrator permissions
+     *                                       Administrator permissions
      * optional parameter <device_adopt>   = boolean, whether or not the new admin will have permissions to
-     *                                       adopt devices, default value is false. Only applies when readonly
+     *                                       adopt devices, default value is false. With versions < 5.9.X this only applies
-     *                                       is true.
+     *                                       when readonly is true.
      * optional parameter <device_restart> = boolean, whether or not the new admin will have permissions to
-     *                                       restart devices, default value is false. Only applies when readonly
+     *                                       restart devices, default value is false. With versions < 5.9.X this only applies
-     *                                       is true.
+     *                                       when readonly is true.
      *
      * NOTES:
      * - after issuing a valid request, an invite will be sent to the email address provided
@@ -1732,25 +1733,72 @@ class Client
             return false;
         }
 
-        $json = ['name' => trim($name), 'email' => trim($email), 'for_sso' => $enable_sso, 'cmd' => 'invite-admin'];
+        $permissions = [];
+        $json        = ['name' => trim($name), 'email' => trim($email), 'for_sso' => $enable_sso, 'cmd' => 'invite-admin', 'role' => 'admin'];
+
         if ($readonly) {
             $json['role'] = 'readonly';
-            $permissions  = [];
-            if ($device_adopt) {
-                $permissions[] = "API_DEVICE_ADOPT";
-            }
-
-            if ($device_restart) {
-                $permissions[] = "API_DEVICE_RESTART";
-            }
-
-            if (count($permissions) > 0) {
-                $json['permissions'] = $permissions;
-            }
         }
 
-        $json     = json_encode($json);
+        if ($device_adopt) {
-        $response = $this->exec_curl('/api/s/' . $this->site . '/cmd/sitemgr', 'json=' . $json);
+            $permissions[] = "API_DEVICE_ADOPT";
+        }
+
+        if ($device_restart) {
+            $permissions[] = "API_DEVICE_RESTART";
+        }
+
+        $json['permissions'] = $permissions;
+        $json                = json_encode($json);
+        $response            = $this->exec_curl('/api/s/' . $this->site . '/cmd/sitemgr', 'json=' . $json);
+
+        return $this->process_response_boolean($response);
+    }
+
+    /**
+     * Assign an existing admin to the current site
+     * --------------------------------------------
+     * returns true on success
+     * required parameter <admin_id>       = 24 char string; _id of the admin user to assign, can be obtained using the
+     *                                       list_all_admins() method/function
+     * optional parameter <readonly>       = boolean, whether or not the new admin will have readonly
+     *                                       permissions, default value is false which gives the new admin
+     *                                       Administrator permissions
+     * optional parameter <device_adopt>   = boolean, whether or not the new admin will have permissions to
+     *                                       adopt devices, default value is false. With versions < 5.9.X this only applies
+     *                                       when readonly is true.
+     * optional parameter <device_restart> = boolean, whether or not the new admin will have permissions to
+     *                                       restart devices, default value is false. With versions < 5.9.X this only applies
+     *                                       when readonly is true.
+     */
+    public function assign_existing_admin(
+        $admin_id,
+        $readonly       = false,
+        $device_adopt   = false,
+        $device_restart = false
+    ) {
+        if (!$this->is_loggedin) {
+            return false;
+        }
+
+        $permissions = [];
+        $json        = ['cmd' => 'grant-admin', 'admin' => trim($admin_id), 'role' => 'admin'];
+
+        if ($readonly) {
+            $json['role'] = 'readonly';
+        }
+
+        if ($device_adopt) {
+            $permissions[] = "API_DEVICE_ADOPT";
+        }
+
+        if ($device_restart) {
+            $permissions[] = "API_DEVICE_RESTART";
+        }
+
+        $json['permissions'] = $permissions;
+        $json                = json_encode($json);
+        $response            = $this->exec_curl('/api/s/' . $this->site . '/cmd/sitemgr', 'json=' . $json);
 
         return $this->process_response_boolean($response);
     }
@@ -1759,7 +1807,7 @@ class Client
      * Revoke an admin
      * ---------------
      * returns true on success
-     * required parameter <admin_id> = id of the admin to revoke which can be obtained using the
+     * required parameter <admin_id> = id of the admin to revoke, can be obtained using the
      *                                 list_all_admins() method/function
      *
      * NOTES:
@@ -1771,7 +1819,7 @@ class Client
             return false;
         }
 
-        $json     = json_encode(['admin' => $admin_id, 'cmd' => 'revoke-admin']);
+        $json     = json_encode(['cmd' => 'revoke-admin', 'admin' => $admin_id]);
         $response = $this->exec_curl('/api/s/' . $this->site . '/cmd/sitemgr', 'json=' . $json);
 
         return $this->process_response_boolean($response);
@@ -3721,9 +3769,9 @@ class Client
         return $this->curl_ssl_verify_host;
     }
 
-    public function set_cookies($cookie_value)
+    public function set_cookies($cookies_value)
     {
-        $this->cookies = $cookie_value;
+        $this->cookies = $cookies_value;
     }
 
     public function set_request_type($request_type)