added Arr::random()

Author: codemasher

src/Arr.php

@@ -13,6 +13,10 @@
 
 use function array_key_first;
 use function array_key_last;
+use function array_keys;
+use function count;
+use function random_int;
+use const PHP_VERSION_ID;
 
 /**
  * Array functions
@@ -51,4 +55,32 @@ public static function last(array $array):mixed{
 		return $array[array_key_last($array)];
 	}
 
+	/**
+	 * Returns a random element of the given array, `null` if the given array is empty.
+	 *
+	 * @see \random_int() - PHP <= 8.1
+	 * @see \Random\Randomizer::pickArrayKeys() - PHP >= 8.2
+	 *
+	 * @param array<string|int, mixed> $array
+	 *
+	 * @noinspection PhpFullyQualifiedNameUsageInspection
+	 */
+	public static function random(array $array):mixed{
+
+		if($array === []){
+			return null;
+		}
+
+		if(PHP_VERSION_ID >= 80200){
+			$key = (new \Random\Randomizer(new \Random\Engine\Secure))->pickArrayKeys($array, 1)[0];
+		}
+		else{
+			// array_rand() is not cryptographically secure
+			$keys = array_keys($array);
+			$key  = $keys[random_int(0, (count($keys) - 1))];
+		}
+
+		return $array[$key];
+	}
+
 }

tests/ArrTest.php

@@ -0,0 +1,51 @@
+<?php
+/**
+ * ArrTest.php
+ *
+ * @created      25.06.2025
+ * @author       smiley <smiley@chillerlan.net>
+ * @copyright    2025 smiley
+ * @license      MIT
+ */
+declare(strict_types = 1);
+
+namespace chillerlan\UtilitiesTest;
+
+use chillerlan\Utilities\Arr;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(Arr::class)]
+final class ArrTest extends TestCase{
+
+	private const testArray = [
+		'one'   => 1,
+		'two'   => 2,
+		'three' => 3,
+		'four'  => 4,
+		'five'  => 5,
+	];
+
+	#[Test]
+	public function first():void{
+		$first = Arr::first(self::testArray);
+
+		$this::assertSame(1, $first);
+	}
+
+	#[Test]
+	public function last():void{
+		$last = Arr::last(self::testArray);
+
+		$this::assertSame(5, $last);
+	}
+
+	#[Test]
+	public function random():void{
+		$random = Arr::random(self::testArray);
+
+		$this::assertContains($random, self::testArray);
+	}
+
+}