completed merge of #258 , contributed by @mvarian

Merge branch 'main' of github.com:Art-of-WiFi/UniFi-API-client into main
merge #258 and review
2024-12-19 10:55:53 +01:00 · 2024-12-19 10:39:33 +01:00 · 2024-12-19 10:39:10 +01:00 · 2024-11-24 11:58:49 +01:00 · 2024-11-15 10:33:11 +01:00 · 2024-11-15 10:31:10 +01:00
2 changed files with 185 additions and 164 deletions
--- a/README.md
+++ b/README.md
@@ -2,16 +2,19 @@

 A PHP class that provides access to Ubiquiti's [**UniFi Network Application**](https://unifi-network.ui.com/) API.

-UniFi Network Application software versions 5.X.X, 6.X.X, 7.X.X, and 8.X.X (version **8.5.2** has been confirmed to
-work) are supported as well as Network Applications on **UniFi OS-based consoles** (UniFi OS **4.0.20** has been
-confirmed to work).
-
 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
 composer/[packagist](https://packagist.org/packages/art-of-wifi/unifi-api-client) for
-easy inclusion in your projects.
+easy inclusion in your projects. See the [installation instructions](#Installation) below for more details.
+
+## Supported Versions
+
+| Software                             | Versions                                            |
+|--------------------------------------|-----------------------------------------------------|
+| UniFi Network Application/controller | 5.X.X, 6.X.X, 7.X.X, 8.X.X (**8.5.6 is confirmed**) |
+| UniFi OS                             | 3.X, 4.X (**4.1.15 is confirmed**)                  |


 ## Requirements
@@ -29,17 +32,19 @@ easy inclusion in your projects.

 ## UniFi OS Support

-Support for UniFi OS-based controllers has been added as of version 1.1.47. These devices have been verified to work:
+Support for UniFi OS-based controllers has been added as of version 1.1.47. These devices/services have been verified
+to work:
 - UniFi Dream Router (UDR)
 - UniFi Dream Machine (UDM)
 - UniFi Dream Machine Pro (UDM PRO)
 - UniFi Cloud Key Gen2 (UCK G2), firmware version 2.0.24 or higher
 - 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)
 - UniFi Express (UX)
 - UniFi Dream Wall (UDW)
 - UniFi Cloud Gateway Ultra (UCG-Ultra)
+- UniFi CloudKey Enterprise (CK-Enterprise)
 - UniFi Enterprise Fortress Gateway (EFG)
+- Official UniFi Hosting, details [here](https://help.ui.com/hc/en-us/articles/4415364143511)

 The class automatically detects UniFi OS consoles and adjusts the URLs and several functions/methods accordingly.

--- a/src/Client.php
+++ b/src/Client.php
@@ -20,7 +20,7 @@ namespace UniFi_API;
 class Client
 {
    /** Constants. */
-    const CLASS_VERSION        = '1.1.100';
+    const CLASS_VERSION        = '1.1.102';
    const CURL_METHODS_ALLOWED = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
    const DEFAULT_CURL_METHOD  = 'GET';

@@ -40,6 +40,7 @@ class Client
    protected bool   $is_unifi_os                = false;
    protected int    $exec_retries               = 0;
    protected string $cookies                    = '';
+    protected int    $cookies_created_at         = 0;
    protected        $last_results_raw           = null;
    protected string $last_error_message         = '';
    protected bool   $curl_ssl_verify_peer       = false;
@@ -120,12 +121,12 @@ class Client
     */
    public function __destruct()
    {
-        /** if $_SESSION[$this->unificookie_name] is set, do not log out here */
+        /** If $_SESSION[$this->unificookie_name] is set, do not log out here. */
        if (isset($_SESSION[$this->unificookie_name])) {
            return;
        }

-        /** log out, if needed */
+        /** Log out, if needed. */
        if ($this->is_logged_in) {
            $this->logout();
        }
@@ -140,7 +141,7 @@ class Client
     */
    public function login()
    {
-        /** skip the login process if already logged in */
+        /** Skip the login process if already logged in. */
        if ($this->update_unificookie()) {
            $this->is_logged_in = true;
        }
@@ -149,7 +150,7 @@ class Client
            return true;
        }

-        /** prepare cURL and options to check whether this is a "regular" controller or one based on UniFi OS */
+        /** Prepare cURL and options to check whether this is a "regular" controller or one based on UniFi OS. */
        $ch = $this->get_curl_handle();

        $curl_options = [
@@ -158,7 +159,7 @@ class Client

        curl_setopt_array($ch, $curl_options);

-        /** execute the cURL request and get the HTTP response code */
+        /** Execute the cURL request and get the HTTP response code. */
        curl_exec($ch);

        $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
@@ -167,7 +168,7 @@ class Client
            trigger_error('cURL error: ' . curl_error($ch));
        }

-        /** prepare the actual login */
+        /** Prepare the actual login. */
        $curl_options = [
            CURLOPT_POST       => true,
            CURLOPT_POSTFIELDS => json_encode(['username' => $this->user, 'password' => $this->password]),
@@ -176,7 +177,7 @@ class Client
            CURLOPT_URL        => $this->baseurl . '/api/login',
        ];

-        /** specific to UniFi OS-based controllers */
+        /** Specific to UniFi OS-based controllers. */
        if ($http_code === 200) {
            $this->is_unifi_os         = true;
            $curl_options[CURLOPT_URL] = $this->baseurl . '/api/auth/login';
@@ -184,7 +185,7 @@ class Client

        curl_setopt_array($ch, $curl_options);

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

@@ -202,7 +203,7 @@ class Client
            print '</pre>' . PHP_EOL;
        }

-        /** based on the HTTP response code trigger an error */
+        /** Based on the HTTP response code trigger an error. */
        if ($http_code >= 400) {
            trigger_error("HTTP response status received: $http_code. Probably a controller login failure");

@@ -211,7 +212,7 @@ class Client

        curl_close($ch);

-        /** check the HTTP response code */
+        /** Check the HTTP response code. */
        if ($http_code >= 200) {
            $this->is_logged_in = true;

@@ -228,7 +229,7 @@ class Client
     */
    public function logout(): bool
    {
-        /** prepare cURL and options */
+        /** Prepare cURL and options. */
        $ch = $this->get_curl_handle();

        $curl_options = [
@@ -250,7 +251,7 @@ class Client

        curl_setopt_array($ch, $curl_options);

-        /** execute the cURL request to logout */
+        /** Execute the cURL request to logout. */
        curl_exec($ch);

        if (curl_errno($ch)) {
@@ -260,8 +261,9 @@ class Client

        curl_close($ch);

-        $this->is_logged_in = false;
-        $this->cookies      = '';
+        $this->is_logged_in       = false;
+        $this->cookies            = '';
+        $this->cookies_created_at = 0;
        return true;
    }

@@ -281,7 +283,7 @@ class Client
     *                            authorization for the client device
     * @return bool true upon success
     */
-    public function authorize_guest(string $mac, int $minutes, int $up = null, int $down = null, int $megabytes = null, string $ap_mac = null): bool
+    public function authorize_guest(string $mac, int $minutes, ?int $up = null, ?int $down = null, ?int $megabytes = null, ?string $ap_mac = null): bool
    {
        $payload = ['cmd' => 'authorize-guest', 'mac' => strtolower($mac), 'minutes' => $minutes];

@@ -389,12 +391,12 @@ class Client
     *                    success, else returns false
     */
    public function create_user(
-        string $mac,
-        string $user_group_id,
-        string $name = null,
-        string $note = null,
-        bool   $is_guest = null,
-        bool   $is_wired = null
+        string  $mac,
+        string  $user_group_id,
+        ?string $name = null,
+        ?string $note = null,
+        ?bool   $is_guest = null,
+        ?bool   $is_wired = null
    )
    {
        $new_user = ['mac' => strtolower($mac), 'usergroup_id' => $user_group_id];
@@ -465,7 +467,7 @@ class Client
     *                            'airtime_avg', 'latency_avg', 'latency_min', 'latency_max'
     * @return array|bool returns an array of 5-minute stats objects for the current site
     */
-    public function stat_5minutes_site(int $start = null, int $end = null, array $attribs = null)
+    public function stat_5minutes_site(?int $start = null, ?int $end = null, ?array $attribs = null)
    {
        $end     = empty($end) ? time() * 1000 : $end;
        $start   = empty($start) ? $end - (12 * 3600 * 1000) : $start;
@@ -489,7 +491,7 @@ class Client
     * @param array|null $attribs optional, array of attributes to collect.
     * @return array|bool returns an array of hourly stats objects for the current site
     */
-    public function stat_hourly_site(int $start = null, int $end = null, array $attribs = null)
+    public function stat_hourly_site(?int $start = null, ?int $end = null, ?array $attribs = null)
    {
        $end     = empty($end) ? time() * 1000 : $end;
        $start   = empty($start) ? $end - (7 * 24 * 3600 * 1000) : $start;
@@ -510,7 +512,7 @@ class Client
     * @param array|null $attribs optional, array of attributes to collect.
     * @return array|bool returns an array of daily stats objects for the current site
     */
-    public function stat_daily_site(int $start = null, int $end = null, array $attribs = null)
+    public function stat_daily_site(?int $start = null, ?int $end = null, ?array $attribs = null)
    {
        $end     = empty($end) ? (time() - (time() % 3600)) * 1000 : $end;
        $start   = empty($start) ? $end - (52 * 7 * 24 * 3600 * 1000) : $start;
@@ -531,7 +533,7 @@ class Client
     * @param array|null $attribs optional, array of attributes to collect.
     * @return array|bool returns an array of monthly stats objects for the current site
     */
-    public function stat_monthly_site(int $start = null, int $end = null, array $attribs = null)
+    public function stat_monthly_site(?int $start = null, ?int $end = null, ?array $attribs = null)
    {
        $end     = empty($end) ? (time() - (time() % 3600)) * 1000 : $end;
        $start   = empty($start) ? $end - (52 * 7 * 24 * 3600 * 1000) : $start;
@@ -578,7 +580,7 @@ class Client
     *                       'ng-rx_bytes',
     * @return array|bool returns an array of 5-minute stats objects
     */
-    public function stat_5minutes_aps(int $start = null, int $end = null, string $mac = null, array $attribs = null)
+    public function stat_5minutes_aps(?int $start = null, ?int $end = null, ?string $mac = null, ?array $attribs = null)
    {
        $end     = empty($end) ? time() * 1000 : $end;
        $start   = empty($start) ? $end - (12 * 3600 * 1000) : $start;
@@ -606,7 +608,7 @@ class Client
     * @param array|null $attribs optional, array of attributes to collect, default: (bytes, num_sta, time).
     * @return array|bool returns an array of hourly stats objects
     */
-    public function stat_hourly_aps(int $start = null, int $end = null, string $mac = null, array $attribs = null)
+    public function stat_hourly_aps(?int $start = null, ?int $end = null, ?string $mac = null, ?array $attribs = null)
    {
        $end     = empty($end) ? (time() * 1000) : $end;
        $start   = empty($start) ? $end - (7 * 24 * 3600 * 1000) : $start;
@@ -634,7 +636,7 @@ class Client
     * @param array|null $attribs optional, array of attributes to collect, default: (bytes, num_sta, time).
     * @return array|bool returns an array of daily stats objects
     */
-    public function stat_daily_aps(int $start = null, int $end = null, string $mac = null, array $attribs = null)
+    public function stat_daily_aps(?int $start = null, ?int $end = null, ?string $mac = null, ?array $attribs = null)
    {
        $end     = empty($end) ? time() * 1000 : $end;
        $start   = empty($start) ? $end - (7 * 24 * 3600 * 1000) : $start;
@@ -662,7 +664,7 @@ class Client
     * @param array|null $attribs optional, array of attributes to collect, default: (bytes, num_sta, time).
     * @return array|bool returns an array of monthly stats objects
     */
-    public function stat_monthly_aps(int $start = null, int $end = null, string $mac = null, array $attribs = null)
+    public function stat_monthly_aps(?int $start = null, ?int $end = null, ?string $mac = null, ?array $attribs = null)
    {
        $end     = empty($end) ? time() * 1000 : $end;
        $start   = empty($start) ? $end - (52 * 7 * 24 * 3600 * 1000) : $start;
@@ -694,7 +696,7 @@ class Client
     *                            default value is ['rx_bytes', 'tx_bytes', 'time']
     * @return array|bool returns an array of 5-minute stats objects
     */
-    public function stat_5minutes_user(string $mac = null, int $start = null, int $end = null, array $attribs = null)
+    public function stat_5minutes_user(?string $mac = null, ?int $start = null, ?int $end = null, ?array $attribs = null)
    {
        $end     = empty($end) ? time() * 1000 : $end;
        $start   = empty($start) ? $end - (12 * 3600 * 1000) : $start;
@@ -720,7 +722,7 @@ class Client
     * @param array|null $attribs array containing attributes (strings) to be returned
     * @return array|bool returns an array of hourly stats objects
     */
-    public function stat_hourly_user(string $mac = null, int $start = null, int $end = null, array $attribs = null)
+    public function stat_hourly_user(?string $mac = null, ?int $start = null, ?int $end = null, ?array $attribs = null)
    {
        $end     = empty($end) ? time() * 1000 : $end;
        $start   = empty($start) ? $end - (7 * 24 * 3600 * 1000) : $start;
@@ -750,7 +752,7 @@ class Client
     * @param array|null $attribs array containing attributes (strings) to be returned
     * @return array|bool returns an array of daily stats objects
     */
-    public function stat_daily_user(string $mac = null, int $start = null, int $end = null, array $attribs = null)
+    public function stat_daily_user(?string $mac = null, ?int $start = null, ?int $end = null, ?array $attribs = null)
    {
        $end     = empty($end) ? time() * 1000 : $end;
        $start   = empty($start) ? $end - (7 * 24 * 3600 * 1000) : $start;
@@ -780,7 +782,7 @@ class Client
     * @return array|bool returns an array of monthly stats objects
     * @see stat_5minutes_user() for details on attribs
     */
-    public function stat_monthly_user(string $mac = null, int $start = null, int $end = null, array $attribs = null)
+    public function stat_monthly_user(?string $mac = null, ?int $start = null, ?int $end = null, ?array $attribs = null)
    {
        $end     = empty($end) ? time() * 1000 : $end;
        $start   = empty($start) ? $end - (13 * 7 * 24 * 3600 * 1000) : $start;
@@ -810,7 +812,7 @@ class Client
     *                            default is ['time', 'mem', 'cpu', 'loadavg_5']
     * @return array|bool returns an array of 5-minute stats objects for the gateway belonging to the current site
     */
-    public function stat_5minutes_gateway(int $start = null, int $end = null, array $attribs = null)
+    public function stat_5minutes_gateway(?int $start = null, ?int $end = null, ?array $attribs = null)
    {
        $end     = empty($end) ? time() * 1000 : $end;
        $start   = empty($start) ? $end - (12 * 3600 * 1000) : $start;
@@ -831,7 +833,7 @@ class Client
     * @param array|null $attribs array containing attributes (strings) to be returned
     * @return array|bool returns an array of hourly stats objects for the gateway belonging to the current site
     */
-    public function stat_hourly_gateway(int $start = null, int $end = null, array $attribs = null)
+    public function stat_hourly_gateway(?int $start = null, ?int $end = null, ?array $attribs = null)
    {
        $end     = empty($end) ? time() * 1000 : $end;
        $start   = empty($start) ? $end - (7 * 24 * 3600 * 1000) : $start;
@@ -852,7 +854,7 @@ class Client
     * @param array|null $attribs array containing attributes (strings) to be returned
     * @return array|bool returns an array of hourly stats objects for the gateway belonging to the current site
     */
-    public function stat_daily_gateway(int $start = null, int $end = null, array $attribs = null)
+    public function stat_daily_gateway(?int $start = null, ?int $end = null, ?array $attribs = null)
    {
        $end     = empty($end) ? (time() - (time() % 3600)) * 1000 : $end;
        $start   = empty($start) ? $end - (52 * 7 * 24 * 3600 * 1000) : $start;
@@ -873,7 +875,7 @@ class Client
     * @param array|null $attribs array containing attributes (strings) to be returned
     * @return array|bool returns an array of monthly stats objects for the gateway belonging to the current site
     */
-    public function stat_monthly_gateway(int $start = null, int $end = null, array $attribs = null)
+    public function stat_monthly_gateway(?int $start = null, ?int $end = null, ?array $attribs = null)
    {
        $end     = empty($end) ? (time() - (time() % 3600)) * 1000 : $end;
        $start   = empty($start) ? $end - (52 * 7 * 24 * 3600 * 1000) : $start;
@@ -892,7 +894,7 @@ class Client
     * @param int|null $end optional, Unix timestamp in milliseconds
     * @return array|bool returns an array of speed test result objects
     */
-    public function stat_speedtest_results(int $start = null, int $end = null)
+    public function stat_speedtest_results(?int $start = null, ?int $end = null)
    {
        $end     = empty($end) ? time() * 1000 : $end;
        $start   = empty($start) ? $end - (24 * 3600 * 1000) : $start;
@@ -912,7 +914,7 @@ class Client
     * @param int|null $limit optional, maximum number of events to return, defaults to 10000
     * @return array|bool returns an array of IPS/IDS event objects
     */
-    public function stat_ips_events(int $start = null, int $end = null, int $limit = null)
+    public function stat_ips_events(?int $start = null, ?int $end = null, ?int $limit = null)
    {
        $end     = empty($end) ? time() * 1000 : $end;
        $start   = empty($start) ? $end - (24 * 3600 * 1000) : $start;
@@ -935,7 +937,7 @@ class Client
     *                      value is 'all'
     * @return array|bool returns an array of login session objects for all devices or a single device
     */
-    public function stat_sessions(int $start = null, int $end = null, string $mac = null, string $type = 'all')
+    public function stat_sessions(?int $start = null, ?int $end = null, ?string $mac = null, string $type = 'all')
    {
        if (!in_array($type, ['all', 'guest', 'user'])) {
            return false;
@@ -961,7 +963,7 @@ class Client
     * @param int|null $limit optional, maximum number of sessions to get (default value is 5)
     * @return array|bool returns an array of login session objects for all devices or a single device
     */
-    public function stat_sta_sessions_latest(string $mac, int $limit = null)
+    public function stat_sta_sessions_latest(string $mac, ?int $limit = null)
    {
        $limit   = empty($limit) ? 5 : $limit;
        $payload = ['mac' => strtolower($mac), '_limit' => $limit, '_sort' => '-assoc_time'];
@@ -978,7 +980,7 @@ class Client
     * @param int|null $end optional, Unix timestamp in milliseconds
     * @return array|bool returns an array of authorization objects
     */
-    public function stat_auths(int $start = null, int $end = null)
+    public function stat_auths(?int $start = null, ?int $end = null)
    {
        $end     = empty($end) ? time() : $end;
        $start   = empty($start) ? $end - (7 * 24 * 3600) : $start;
@@ -1025,7 +1027,7 @@ class Client
     * @return array|bool returns an array of online client device objects, or in case of a single device request, returns a
     *                    single client device object, false upon error
     */
-    public function list_clients(string $mac = null)
+    public function list_clients(?string $mac = null)
    {
        if (is_string($mac)) {
            $mac = strtolower(trim($mac));
@@ -1081,7 +1083,7 @@ class Client
     * @param string|null $fixed_ip optional, IP address, value of client device's fixed_ip field
     * @return array|bool returns an array containing a single object with attributes of the updated client on success
     */
-    public function edit_client_fixedip(string $client_id, bool $use_fixedip, string $network_id = null, string $fixed_ip = null)
+    public function edit_client_fixedip(string $client_id, bool $use_fixedip, ?string $network_id = null, ?string $fixed_ip = null)
    {
        $this->curl_method = 'PUT';

@@ -1208,11 +1210,11 @@ class Client
     * Create AP group
     *
     * @param string $group_name name to assign to the AP group
-     * @param array $device_macs optional, array containing the MAC addresses (strings) of the APs to add to the new
+     * @param array|null $device_macs optional, array containing the MAC addresses (strings) of the APs to add to the new
     *                            group
     * @return array|bool containing a single object with attributes of the new AP group on success
     */
-    public function create_apgroup(string $group_name, array $device_macs = [])
+    public function create_apgroup(string $group_name, ?array $device_macs = [])
    {
        $payload = ['device_macs' => $device_macs, 'name' => $group_name];

@@ -1258,10 +1260,10 @@ class Client
    /**
     * Fetch firewall groups (using REST)
     *
-     * @param string $group_id optional, _id value of the single firewall group to list
+     * @param string|null $group_id optional, _id value of the single firewall group to list
     * @return array|bool containing the current firewall groups or the selected firewall group on success
     */
-    public function list_firewallgroups(string $group_id = '')
+    public function list_firewallgroups(?string $group_id = '')
    {
        return $this->fetch_results('/api/s/' . $this->site . '/rest/firewallgroup/' . trim($group_id));
    }
@@ -1271,12 +1273,12 @@ class Client
     *
     * @param string $group_name name to assign to the firewall group
     * @param string $group_type firewall group type; valid values are address-group, ipv6-address-group, port-group
-     * @param array $group_members array containing the members of the new group (IPv4 addresses, IPv6 addresses or
+     * @param array|null $group_members array containing the members of the new group (IPv4 addresses, IPv6 addresses or
     *                              port numbers)
     *                              (default is an empty array)
     * @return array|bool containing a single object with attributes of the new firewall group on success
     */
-    public function create_firewallgroup(string $group_name, string $group_type, array $group_members = [])
+    public function create_firewallgroup(string $group_name, string $group_type, ?array $group_members = [])
    {
        if (!in_array($group_type, ['address-group', 'ipv6-address-group', 'port-group'])) {
            return false;
@@ -1431,7 +1433,7 @@ class Client
     * @param array|null $macs optional, an array of the MAC address(es) of the device(s) to tag with the new tag
     * @return bool return true on success
     */
-    public function create_tag(string $name, array $macs = null): bool
+    public function create_tag(string $name, ?array $macs = null): bool
    {
        $payload = ['name' => $name];

@@ -2038,7 +2040,7 @@ class Client
     * @param int|null $create_time optional, create time of the vouchers to fetch in Unix timestamp in seconds
     * @return array|bool containing hotspot voucher objects
     */
-    public function stat_voucher(int $create_time = null)
+    public function stat_voucher(?int $create_time = null)
    {
        $payload = isset($create_time) ? ['create_time' => $create_time] : [];

@@ -2051,7 +2053,7 @@ class Client
     * @param int|null $within optional, number of hours to go back to fetch payments
     * @return array|bool containing hotspot payments
     */
-    public function stat_payment(int $within = null)
+    public function stat_payment(?int $within = null)
    {
        $path_suffix = isset($within) ? '?within=' . $within : '';

@@ -2063,10 +2065,10 @@ class Client
     *
     * @param string $name name for the hotspot operator
     * @param string $x_password clear text password for the hotspot operator
-     * @param string $note optional, note to attach to the hotspot operator
+     * @param string|null $note optional, note to attach to the hotspot operator
     * @return bool true upon success
     */
-    public function create_hotspotop(string $name, string $x_password, string $note = ''): bool
+    public function create_hotspotop(string $name, string $x_password, ?string $note = null): bool
    {
        $payload = ['name' => $name, 'x_password' => $x_password];
        if (!empty($note)) {
@@ -2106,9 +2108,9 @@ class Client
        int    $count = 1,
        int    $quota = 0,
        string $note = '',
-        int    $up = null,
-        int    $down = null,
-        int    $megabytes = null
+        ?int   $up = null,
+        ?int   $down = null,
+        ?int   $megabytes = null
    )
    {
        $payload = [
@@ -2191,7 +2193,7 @@ class Client
     *                           only to be combined with a "by_app" value for $type
     * @return array|bool containing filtered DPI stats
     */
-    public function list_dpi_stats_filtered(string $type = 'by_cat', array $cat_filter = null)
+    public function list_dpi_stats_filtered(string $type = 'by_cat', ?array $cat_filter = null)
    {
        if (!in_array($type, ['by_cat', 'by_app'])) {
            return false;
@@ -2836,23 +2838,23 @@ class Client
     * @return bool true on success
     */
    public function create_wlan(
-        string $name,
-        string $x_passphrase,
-        string $usergroup_id,
-        string $wlangroup_id,
-        bool   $enabled = true,
-        bool   $hide_ssid = false,
-        bool   $is_guest = false,
-        string $security = 'open',
-        string $wpa_mode = 'wpa2',
-        string $wpa_enc = 'ccmp',
-        bool   $vlan_enabled = null,
-        string $vlan_id = null,
-        bool   $uapsd_enabled = false,
-        bool   $schedule_enabled = false,
-        array  $schedule = [],
-        array  $ap_group_ids = null,
-        array  $payload = []
+        string  $name,
+        string  $x_passphrase,
+        string  $usergroup_id,
+        string  $wlangroup_id,
+        bool    $enabled = true,
+        bool    $hide_ssid = false,
+        bool    $is_guest = false,
+        string  $security = 'open',
+        string  $wpa_mode = 'wpa2',
+        string  $wpa_enc = 'ccmp',
+        ?bool   $vlan_enabled = null,
+        ?string $vlan_id = null,
+        bool    $uapsd_enabled = false,
+        bool    $schedule_enabled = false,
+        array   $schedule = [],
+        ?array  $ap_group_ids = null,
+        array   $payload = []
    ): bool
    {
        $payload = array_merge($payload, [
@@ -3020,7 +3022,7 @@ class Client
     *                       counted, by default all alarms are counted
     * @return array|bool containing the alarm count
     */
-    public function count_alarms(bool $archived = null)
+    public function count_alarms(?bool $archived = null)
    {
        $path_suffix = $archived === false ? '?archived=false' : null;

@@ -3278,11 +3280,11 @@ class Client
     * @return bool|array                 containing a single object for the newly created account upon success, else returns false
     */
    public function create_radius_account(
-        string $name,
-        string $x_password,
-        int    $tunnel_type = null,
-        int    $tunnel_medium_type = null,
-        string $vlan = null
+        string  $name,
+        string  $x_password,
+        ?int    $tunnel_type = null,
+        ?int    $tunnel_medium_type = null,
+        ?string $vlan = null
    )
    {
        $tunnel_type_values        = [null, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
@@ -3397,7 +3399,7 @@ class Client
     *                    The returned array also contains the page number and size, and the total number of entries
     *                    available.
     */
-    public function get_system_log(string $class = 'device-alert', int $start = null, int $end = null, int $page_number = 0, int $page_size = 100, array $custom_payload = [])
+    public function get_system_log(string $class = 'device-alert', ?int $start = null, ?int $end = null, int $page_number = 0, int $page_size = 100, array $custom_payload = [])
    {
        $end   = empty($end) ? time() * 1000  : $end;
        $start = empty($start) ? $end - (7 * 24 * 3600 * 1000) : $start;
@@ -3506,7 +3508,7 @@ class Client
     * @param string|null $mac optional, the MAC address of a single device for which the call must be made
     * @return array|bool containing known device objects (or a single device when using the <mac> parameter)
     */
-    public function list_aps(string $mac = null)
+    public function list_aps(?string $mac = null)
    {
        trigger_error(
            'Function list_aps() has been deprecated, use list_devices() instead.',
@@ -3599,7 +3601,18 @@ class Client
     ****************************************************************/

    /**
-     * Modify the private property $site
+     * Get the version of the Class.
+     *
+     * @return string semver compatible version of this class
+     *                https://semver.org/
+     */
+    public function get_class_version(): string
+    {
+        return self::CLASS_VERSION;
+    }
+
+    /**
+     * Modify the private property $site.
     *
     * @note this method is useful to switch between sites
     * @param string $site must be the short site name of a site to which the
@@ -3615,7 +3628,7 @@ class Client
    }

    /**
-     * Get the private property $site
+     * Get the private property $site.
     *
     * @return string the current (short) site name
     */
@@ -3625,7 +3638,7 @@ class Client
    }

    /**
-     * Set debug mode
+     * Set debug mode.
     *
     * @param bool $enable true enables debug mode, false disables debug mode
     * @return bool false when a non-boolean parameter was passed
@@ -3638,7 +3651,7 @@ class Client
    }

    /**
-     * Get the private property $debug
+     * Get the private property $debug.
     *
     * @return bool the current boolean value for $debug
     */
@@ -3648,7 +3661,7 @@ class Client
    }

    /**
-     * Get last raw results
+     * Get last raw results.
     *
     * @param boolean $return_json true returns the results in "pretty printed" JSON format,
     *                             false returns PHP stdClass Object format (default)
@@ -3668,7 +3681,7 @@ class Client
    }

    /**
-     * Get the last error message
+     * Get the last error message.
     *
     * @return string the error message of the last method called in PHP stdClass Object format, an empty string when
     *                none available
@@ -3679,7 +3692,7 @@ class Client
    }

    /**
-     * Get Cookie from UniFi controller (singular and plural)
+     * Get Cookie from UniFi controller (singular and plural for backward compatibility).
     *
     * @note When the results from this method are stored in $_SESSION[$this->unificookie_name], the Class initially
     *       does not log in to the controller when a subsequent request is made using a new instance.
@@ -3701,28 +3714,28 @@ class Client
    }

    /**
-     * Get the version of the Class
+     * Get the Unix timestamp of the latest cookie creation.
     *
-     * @return string semver compatible version of this class
-     *                https://semver.org/
+     * @return int
     */
-    public function get_class_version(): string
+    public function get_cookies_created_at(): int
    {
-        return self::CLASS_VERSION;
+        return $this->cookies_created_at;
    }

    /**
-     * Set value for the private property $cookies
+     * Set the value for the private property $cookies and update $cookies_created_at timestamp.
     *
     * @param string $cookies_value new value for $cookies
     */
    public function set_cookies(string $cookies_value)
    {
-        $this->cookies = $cookies_value;
+        $this->cookies            = $cookies_value;
+        $this->cookies_created_at = time();
    }

    /**
-     * Get the current value of the private property $unificookie_name
+     * Get the current value of the private property $unificookie_name.
     *
     * @return string current value of $unificookie_name
     */
@@ -3732,7 +3745,7 @@ class Client
    }

    /**
-     * Get current request method
+     * Get current request method.
     *
     * @return string request type
     */
@@ -3742,7 +3755,7 @@ class Client
    }

    /**
-     * Set request method
+     * Set request method.
     *
     * @param string $curl_method a valid HTTP request method
     * @return bool whether the request was successful or not
@@ -3759,7 +3772,7 @@ class Client
    }

    /**
-     * Get value for cURL option CURLOPT_SSL_VERIFYPEER
+     * Get value for cURL option CURLOPT_SSL_VERIFYPEER.
     *
     * https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html
     *
@@ -3771,7 +3784,7 @@ class Client
    }

    /**
-     * Set value for cURL option CURLOPT_SSL_VERIFYPEER
+     * Set value for cURL option CURLOPT_SSL_VERIFYPEER.
     *
     * https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html
     *
@@ -3786,7 +3799,7 @@ class Client
    }

    /**
-     * Get value for cURL option CURLOPT_SSL_VERIFYHOST
+     * Get value for cURL option CURLOPT_SSL_VERIFYHOST.
     *
     * https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html
     *
@@ -3798,7 +3811,7 @@ class Client
    }

    /**
-     * Set value for cURL option CURLOPT_SSL_VERIFYHOST
+     * Set value for cURL option CURLOPT_SSL_VERIFYHOST.
     *
     * https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html
     *
@@ -3817,7 +3830,7 @@ class Client
    }

    /**
-     * Is current controller UniFi OS-based
+     * Is the current controller UniFi OS-based?
     *
     * @return bool whether the current controller is UniFi OS-based or not
     */
@@ -3827,7 +3840,7 @@ class Client
    }

    /**
-     * Set value for private property $is_unifi_os
+     * Set value for private property $is_unifi_os.
     *
     * @param bool $is_unifi_os the new value
     * @return bool whether the request was successful or not
@@ -3840,7 +3853,7 @@ class Client
    }

    /**
-     * Set value for the private property $connect_timeout
+     * Set value for the private property $connect_timeout.
     *
     * @param int $timeout new value for $connect_timeout in seconds
     * @return bool whether the request was successful or not
@@ -3853,7 +3866,7 @@ class Client
    }

    /**
-     * Get the current value of the private property $connect_timeout
+     * Get the current value of the private property $connect_timeout.
     *
     * @return int current value of $connect_timeout
     */
@@ -3863,7 +3876,7 @@ class Client
    }

    /**
-     * Set value for the private property $request_timeout
+     * Set value for the private property $request_timeout.
     *
     * @param int $timeout new value for $request_timeout in seconds
     * @return bool whether the request was successful or not
@@ -3876,7 +3889,7 @@ class Client
    }

    /**
-     * Get the current value of the private property $request_timeout
+     * Get the current value of the private property $request_timeout.
     *
     * @return int current value of $request_timeout
     */
@@ -3886,7 +3899,7 @@ class Client
    }

    /**
-     * Set value for the private property $curl_http_version
+     * Set value for the private property $curl_http_version.
     *
     * @note As of cURL version 7.62.0 the default value is CURL_HTTP_VERSION_2TLS which may cause issues,
     *       this method allows you to set the value to CURL_HTTP_VERSION_1_1 when needed.
@@ -3903,7 +3916,7 @@ class Client
    }

    /**
-     * Get current value of the private property $curl_http_version
+     * Get current value of the private property $curl_http_version.
     *
     * @return int the current value of $request_timeout, can be CURL_HTTP_VERSION_1_1 int(2) or
     *             CURL_HTTP_VERSION_2TLS int(4)
@@ -3919,11 +3932,9 @@ class Client
     ****************************************************************/

    /**
-     * Fetch results
+     * Fetch results; execute the cURL request and return results.
     *
-     * Execute the cURL request and return results
-     *
-     * @param string $path request path
+     * @param string|null $path request path
     * @param object|array|null $payload optional, PHP associative array or stdClass Object, payload to pass with the
     *                                   request
     * @param boolean $boolean optional, whether the method should return a boolean result, else return
@@ -3932,13 +3943,13 @@ class Client
     * @return bool|array returns an array with the "data" array on success, else returns false
     */
    protected function fetch_results(
-        string $path,
-               $payload = null,
-        bool   $boolean = false,
-        bool   $login_required = true
+        ?string $path,
+                $payload = null,
+        bool    $boolean = false,
+        bool    $login_required = true
    )
    {
-        /** guard clause to check if logged in when needed */
+        /** Guard clause to check if logged in when needed. */
        if ($login_required && !$this->is_logged_in) {
            return false;
        }
@@ -3961,7 +3972,7 @@ class Client

                if ($response->meta->rc === 'error') {
                    /**
-                     * an error occurred:
+                     * An error occurred:
                     * set $this->set last_error_message if the returned error message is available
                     */
                    if (isset($response->meta->msg)) {
@@ -3973,7 +3984,7 @@ class Client
                }
            }

-            /** to deal with a response coming from the new v2 API */
+            /** Deal with a response coming from the new v2 API. */
            if (strpos($path, '/v2/api/') === 0) {
                if (isset($response->errorCode)) {
                    if (isset($response->message)) {
@@ -3994,9 +4005,7 @@ class Client
    }

    /**
-     * Fetch results where output should be boolean (true/false)
-     *
-     * execute the cURL request and return a boolean value
+     * Fetch results where output should be boolean (true/false); execute the cURL request and return a boolean value.
     *
     * @param string $path request path
     * @param object|array|null $payload optional, PHP associative array or stdClass Object, payload to pass with the
@@ -4010,7 +4019,7 @@ class Client
    }

    /**
-     * Capture the latest JSON error when $this->debug is true
+     * Capture the latest JSON error when $this->debug is true.
     *
     * @return bool true upon success, false upon failure
     */
@@ -4051,7 +4060,7 @@ class Client
                    break;
            }

-            /** check whether we have PHP >= 7.0.0 */
+            /** Check whether we have PHP >= 7.0.0. */
            if (defined('JSON_ERROR_INVALID_PROPERTY_NAME') && defined('JSON_ERROR_UTF16')) {
                switch (json_last_error()) {
                    case JSON_ERROR_INVALID_PROPERTY_NAME:
@@ -4072,7 +4081,7 @@ class Client
    }

    /**
-     * Validate the submitted base URL
+     * Validate the submitted base URL.
     *
     * @param string $baseurl the base URL to validate
     * @return bool true if base URL is a valid URL, else returns false
@@ -4089,7 +4098,7 @@ class Client
    }

    /**
-     * Check the (short) site name
+     * Check the (short) site name.
     *
     * @param string $site the (short) site name to check
     * @return bool true if (short) site name is valid, else returns false
@@ -4106,14 +4115,15 @@ class Client
    }

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

            /** if the cookie contains a JWT, this is a UniFi OS controller */
            if (strpos($this->cookies, 'TOKEN') !== false) {
@@ -4127,7 +4137,7 @@ class Client
    }

    /**
-     * Add a cURL header containing the CSRF token from the TOKEN in our Cookie string
+     * Add a cURL header containing the CSRF token from the TOKEN in our Cookie string.
     *
     * @return void
     */
@@ -4158,7 +4168,7 @@ class Client
    }

    /**
-     * Callback function for cURL to extract and store cookies as needed
+     * Callback function for cURL to extract and store cookies as needed.
     *
     * @param object|resource $ch the cURL instance (type hinting is unavailable for cURL resources)
     * @param string $header_line the response header line number
@@ -4173,16 +4183,18 @@ class Client
                $cookie_crumbs = explode(';', $cookie);
                foreach ($cookie_crumbs as $cookie_crumb) {
                    if (strpos($cookie_crumb, 'unifises') !== false) {
-                        $this->cookies      = $cookie_crumb;
-                        $this->is_logged_in = true;
-                        $this->is_unifi_os  = false;
+                        $this->cookies            = $cookie_crumb;
+                        $this->cookies_created_at = time();
+                        $this->is_logged_in       = true;
+                        $this->is_unifi_os        = false;
                        break;
                    }

                    if (strpos($cookie_crumb, 'TOKEN') !== false) {
-                        $this->cookies      = $cookie_crumb;
-                        $this->is_logged_in = true;
-                        $this->is_unifi_os  = true;
+                        $this->cookies            = $cookie_crumb;
+                        $this->cookies_created_at = time();
+                        $this->is_logged_in       = true;
+                        $this->is_unifi_os        = true;
                        break;
                    }
                }
@@ -4193,7 +4205,7 @@ class Client
    }

    /**
-     * Execute the cURL request
+     * Execute the cURL request.
     *
     * @param string $path path for the request
     * @param object|array|null $payload optional, payload to pass with the request
@@ -4218,7 +4230,7 @@ class Client
            CURLOPT_URL => $url,
        ];

-        /** when a payload is passed */
+        /** When a payload is passed. */
        $json_payload = '';
        if (!empty($payload)) {
            $json_payload                     = json_encode($payload, JSON_UNESCAPED_SLASHES);
@@ -4226,8 +4238,8 @@ class Client


            /**
-             * should not use GET (the default request type) or DELETE when passing a payload,
-             * switch to POST instead
+             * Should not use GET (the default request type) or DELETE when passing a payload,
+             * switch to POST instead.
             */
            if ($this->curl_method === 'GET' || $this->curl_method === 'DELETE') {
                $this->curl_method = 'POST';
@@ -4257,19 +4269,19 @@ class Client

        curl_setopt_array($ch, $curl_options);

-        /** execute the cURL request */
+        /** Execute the cURL request. */
        $response = curl_exec($ch);

        if (curl_errno($ch)) {
            trigger_error('cURL error: ' . curl_error($ch));
        }

-        /** get the HTTP response code */
+        /** Get the HTTP response code. */
        $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

        /**
-         * an HTTP response code 401 (Unauthorized) indicates the Cookie/Token has expired in which case
-         * re-login is required
+         * An HTTP response code 401 (Unauthorized) indicates the Cookie/Token has expired, in which case
+         * re-login is required.
         */
        if ($http_code === 401) {
            if ($this->debug) {
@@ -4277,21 +4289,25 @@ class Client
            }

            if ($this->exec_retries === 0) {
-                /** explicitly clear the expired Cookie/Token, update other properties and log out before logging in again */
+                /**
+                 * Explicitly clear the expired Cookie/Token, update other properties and log out before logging in
+                 * again.
+                 */
                if (isset($_SESSION[$this->unificookie_name])) {
                    $_SESSION[$this->unificookie_name] = '';
                }

-                $this->is_logged_in = false;
-                $this->cookies      = '';
+                $this->is_logged_in       = false;
+                $this->cookies            = '';
+                $this->cookies_created_at = 0;
                $this->exec_retries++;

                curl_close($ch);

-                /** then login again */
+                /** Login again. */
                $this->login();

-                /** when re-login was successful, execute the same cURL request again */
+                /** When the re-login was successful, execute the same cURL request again. */
                if ($this->is_logged_in) {
                    if ($this->debug) {
                        error_log(__FUNCTION__ . ': re-logged in, calling exec_curl again');
@@ -4328,14 +4344,14 @@ class Client

        curl_close($ch);

-        /** set the method back to the default value, just in case */
+        /** Set the method back to the default value, just in case. */
        $this->curl_method = self::DEFAULT_CURL_METHOD;

        return $response;
    }

    /**
-     * Create and return a new cURL handle
+     * Create and return a new cURL handle.
     *
     * @return object|resource CurlHandle object with PHP 8.* and higher, or a resource for lower PHP versions
     */
Author	SHA1	Message	Date
malle-pietje	d722d7b843	completed merge of #258 , contributed by @mvarian	2024-12-19 10:55:53 +01:00
malle-pietje	3cf7b4d173	Merge branch 'main' of github.com:Art-of-WiFi/UniFi-API-client into main merge #258 and review	2024-12-19 10:39:33 +01:00
Michael Varian	6b230753a0	Fix for implicit null declarations resulting in PHP 8.4+ warnings (#258 ) Merge #258	2024-12-19 10:39:10 +01:00
malle-pietje	97510ec5ec	prepared new version number	2024-11-24 11:58:49 +01:00
malle-pietje	9726378e3c	bumped version to 1.1.101	2024-11-15 10:33:11 +01:00
malle-pietje	494375f8b5	- added a private property $cookies_created_at to store the timestamp when the cookies were created/updated. - added a getter method get_cookies_created_at() to return the timestamp when the cookies were created/updated. This information can be useful to determine how old the cookies are. - minor comments clean up	2024-11-15 10:31:10 +01:00
malle-pietje	3dbc24daca	further tweaks	2024-11-04 13:43:57 +01:00
malle-pietje	93d1d8ec3f	tweaked hyperlink	2024-11-04 13:38:18 +01:00
malle-pietje	b8620f7672	changed link to hyperlink	2024-11-04 13:37:01 +01:00
malle-pietje	1e2e709d4a	inserted link to installation instructions	2024-11-04 13:34:41 +01:00
malle-pietje	472d2eaa68	restructured and updated supported versions info	2024-11-04 13:32:34 +01:00