Allow filtering by multiple MAC addresses in `list_devices()`

[sgrodzicki]

stat/device can be filtered by POST-ing multiple MAC addresses like so:

{"macs":["mac1","mac2"]}

In my opinion, it also makes the API more readable, as we always get a list of devices in the response (even if we pass on a single MAC address).

I have maintained backward compatibility by detecting when a string is passed and added a corresponding deprecation message. Also, strtolower is no longer needed as this endpoint is case-insensitive.

[malle-pietje]

Thanks for the PR. I am a bit hesitant though, to introduce a breaking change like this. Maybe we can come up with an approach that works both for a string and an array, while also satisfying IDEs based on the docblocks? Let me think about that.

[malle-pietje]

Maybe simply changing the docblock to this will work:

    /**
     * Fetch UniFi devices
     *
     * @param array|string $device_macs optional, array containing the MAC addresses (strings) of the devices to filter by,
     *                                  may also be a 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
     */

We can also leave out the trigger_error() if the method works fine for both cases. Simply add to the comment that passing an array is preferred.

[sgrodzicki]

Sounds good to me. In that case simply casting to array does the trick. Changes in e3f7f426ea93113cbacf043736363c4185682515.

[malle-pietje]

Thanks, let me run some tests to validate behaviour.:thumbsup:

[sgrodzicki]

Thanks, let me run some tests to validate behaviour.👍

To help you out a bit this is the expected behaviour:

PHP	JSON	API
null	{"macs":[]}	All devices
[]	{"macs":[]}	All devices
'mac1'	{"macs":["mac1"]}	Only mac1
['mac1']	{"macs":["mac1"]}	Only mac1
['mac1', 'mac2']	{"macs":["mac1","mac2"]}	Only mac1 & mac2

[malle-pietje]

Merged with this release: https://github.com/Art-of-WiFi/UniFi-API-client/releases/tag/v1.1.82

Thanks!