API client class v1.1.83

- added a 'accept: application/json' header to the login requests
- re-added support for cookies when working with a UniFi OS-based controller

README.md

@@ -2,8 +2,8 @@
 
 A PHP class that provides access to Ubiquiti's [**UniFi Network Controller**](https://unifi-network.ui.com/) API.
 
-UniFi Network Controller software versions 4.X.X, 5.X.X, 6.X.X, and 7.X.X (version 7.2.93 has been confirmed to work)
-are supported as well as UniFi OS-based controllers. This class is used by our API browser tool which can be found
+UniFi Network Controller software versions 4.X.X, 5.X.X, 6.X.X, 7.X.X, and 8.X.X (version **8.0.21** has been confirmed to work)
+are supported as well as Network Applications on **UniFi OS-based consoles**. This class is used by our API browser tool which can be found
 [here](https://github.com/Art-of-WiFi/UniFi-API-browser).
 
 The package can be installed manually or by using
@@ -13,13 +13,12 @@ easy inclusion in your projects.
 ## Requirements
 
 - a server with:
-  - PHP 5.5.0 or higher 
+  - PHP 5.5.0 or higher (soon this requirement will be raised to PHP **7.4**)
   - PHP json and PHP cURL modules
   - tested on Apache 2.4 with PHP 5.6.1 and cURL 7.42.1 and with PHP 7.4.9 and cURL 7.68.0
 - direct network connectivity between this server and the host and port (usually TCP port 8443 or port 443 for 
   UniFi OS) where the UniFi Controller is running
-- you must use **accounts with local access**, not UniFi Cloud accounts, to access the UniFi Controller API 
-  through this class
+- you must use **accounts with local access** to access the UniFi Controller API through this class, do not use UniFi Cloud accounts and do not enable 2FA on the accounts that you use with this class
 
 ## UniFi OS Support
 
@@ -31,15 +30,14 @@ Support for UniFi OS-based controllers has been added as of version 1.1.47:
 - UniFi Cloud Key Gen2 Plus (UCK G2 Plus), firmware version 2.0.24 or higher
 - UniFi Cloud Console, details [here](https://help.ui.com/hc/en-us/articles/4415364143511)
 
-The class automatically detects UniFi OS-based controllers and adjusts URLs and several functions/methods accordingly.
+The class automatically detects UniFi OS consoles and adjusts the URLs and several functions/methods accordingly.
+
 If your own code implements strict validation of the URL that is passed to the constructor, please adapt your
 logic to allow URLs without a port suffix or with port 443 when working with a UniFi OS-based controller.
 
 > **IMPORTANT NOTE**: cookies are no longer supported with UniFi OS-based controllers. If your application code does use cookies,
   they will be ignored automatically when working with UniFi OS-based controllers.
 
-Please test all methods you plan on using thoroughly before using the API Client with
-UniFi OS devices in a production environment.
 
 ## Installation
 

src/Client.php

@@ -13,7 +13,7 @@ namespace UniFi_API;
  *
  * @package UniFi_Controller_API_Client_Class
  * @author  Art of WiFi <info@artofwifi.net>
- * @version Release: 1.1.81
+ * @version Release: 1.1.83
  * @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
@@ -25,7 +25,7 @@ class Client
      *
      * NOTE: do **not** modify the values here, instead use the constructor or the getter and setter functions/methods
      */
-    const CLASS_VERSION             = '1.1.81';
+    const CLASS_VERSION             = '1.1.83';
     protected $baseurl              = 'https://127.0.0.1:8443';
     protected $user                 = '';
     protected $password             = '';
@@ -101,7 +101,7 @@ class Client
         /**
          * if $_SESSION['unificookie'] is set, do not log out here except when this is a UniFi OS-based controller
          */
-        if (isset($_SESSION['unificookie']) && !$this->is_unifi_os) {
+        if (isset($_SESSION['unificookie'])) {
             return;
         }
 
@@ -161,6 +161,7 @@ class Client
             CURLOPT_POST       => true,
             CURLOPT_POSTFIELDS => json_encode(['username' => $this->user, 'password' => $this->password]),
             CURLOPT_HTTPHEADER => [
+                'accept: application/json',
                 'content-type: application/json',
                 'Expect:',
             ],
@@ -247,6 +248,7 @@ class Client
         ];
 
         $logout_path = '/logout';
+
         if ($this->is_unifi_os) {
             $logout_path                         = '/api/auth/logout';
             $curl_options[CURLOPT_CUSTOMREQUEST] = 'POST';
@@ -1408,17 +1410,16 @@ class Client
     /**
      * Fetch UniFi devices
      *
-     * @param array|string $device_mac optional, the MAC address of a single UniFi device for which the call must be made
-     * @return array|false an array containing known UniFi device objects (or a single device when using the <device_mac>
+     * @param array|string $device_macs optional, array containing the MAC addresses (lowercase strings) of the devices
+     *                                  to filter by, may also be a (lowercase) string containing a single MAC address
+     * @return array|false an array containing known UniFi device objects (optionally filtered by the <device_macs>
      *                     parameter), false upon error
      */
-    public function list_devices($device_mac = null)
+    public function list_devices($device_macs = [])
     {
-        if (is_string($device_mac)) {
-            $device_mac = strtolower(trim($device_mac));
-        }
+        $payload = ['macs' => (array) $device_macs];
 
-        return $this->fetch_results('/api/s/' . $this->site . '/stat/device/' . $device_mac);
+        return $this->fetch_results('/api/s/' . $this->site . '/stat/device', $payload);
     }
 
     /**
@@ -3953,6 +3954,7 @@ class Client
              * add empty Expect header to prevent cURL from injecting an "Expect: 100-continue" header
              */
             $this->curl_headers = [
+                'accept: application/json',
                 'content-type: application/json',
                 'Expect:',
             ];