From d5b2f4b96cc5b58c9afe5e7fd87b62ed3a6bb474 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Danijel=20Gali=C4=87?=
Date: Mon, 29 Jun 2026 13:30:37 +0200
Subject: [PATCH 01/36] Update README to reflect changes for the new `develop`
branch policies
**Details:**
- Added badges for PHPStan, PHPUnit, and Codecov to enhance visibility of CI/CD and coverage metrics.
- Updated branch references from `master` to `develop` across badges and URLs.
- Clarified the purpose of the `develop` branch, emphasizing its role as the primary staging area for integration and preparation of releases.
- Highlighted the branch's instability, lack of backward compatibility, and unsuitability for production use.
- Provided details on Composer usage for internal testing purposes.
- This update aligns documentation with the current workflow and branch management practices.
---
README.md | 109 ++++++++++++++++++++----------------------------------
1 file changed, 40 insertions(+), 69 deletions(-)
diff --git a/README.md b/README.md
index 90539d0..337a548 100644
--- a/README.md
+++ b/README.md
@@ -22,46 +22,25 @@
/>
+[](https://github.com/The-FireHub-Project/Runtime/actions/workflows/PHPStan.yml)
+[](https://github.com/The-FireHub-Project/Runtime/actions/workflows/PHPUnit.yml)
+[](https://app.codecov.io/gh/The-FireHub-Project/Runtime/tree/develop)
+
@@ -73,55 +52,47 @@ It contains no domain logic, no business rules, and no framework coupling. Its r
---
-## Repository Purpose
+## Development Branch
-This repository provides a lightweight PHP runtime abstraction layer that wraps native PHP functionality into clean, consistent, and deterministic APIs.
+⚠️ **This is the `develop` branch**
-Its purpose is to reduce boilerplate and standardize common execution patterns across the FireHub ecosystem by offering ergonomic helper classes for arrays, strings, files, environment access, and other low-level runtime operations.
+- Unstable
+- APIs may change without notice
+- Not intended for production use
-It is strictly focused on execution-level concerns and does not contain domain logic, business rules, or framework-level orchestration. It exists to improve developer productivity while preserving native PHP behavior and ensuring zero framework coupling.
+## Branch Purpose
-## Security
+The `develop` branch is the **primary integration branch** for all ongoing development.
-For security reporting and guidelines, please refer to our [SECURITY.md](https://github.com/The-FireHub-Project/.github/blob/master/.github/SECURITY.md) file.
+It serves as the staging area where:
+- Feature branches are merged
+- Bug fixes are integrated
+- Experimental work is stabilized
+- Code is prepared for upcoming releases
-## Community
+All **release branches** are created **from `develop`**.
-
-
-
+## Stability Guarantee
-- Be sure to review the [Code of Conduct](https://github.com/The-FireHub-Project/.github/blob/master/.github/CODE_OF_CONDUCT.md).
-- Read a [Contributing](https://github.com/The-FireHub-Project/.github/blob/master/.github/CONTRIBUTING.md) file to see how you can contribute to this project.
-- Read our [Security policy](https://github.com/The-FireHub-Project/.github/blob/master/.github/SECURITY.md) file to see how you can report a vulnerability.
-- Review the project [Governance model](https://github.com/The-FireHub-Project/.github/blob/master/.github/GOVERNANCE.md), including roles, decision-making, RFC process, and releases.
+❌ No backward compatibility guarantee
+❌ APIs may change without notice
+❌ Behavior may be incomplete or inconsistent
+❌ Breaking changes are expected
-## Support
+This branch is intended **only for contributors and advanced testers**.
-
@@ -52,47 +52,55 @@ It contains no domain logic, no business rules, and no framework coupling. Its r
---
-## Development Branch
+## Runtime Wrapper Core – Development Branch
-⚠️ **This is the `develop` branch**
+⚠️ **This is the `development` branch**
- Unstable
- APIs may change without notice
- Not intended for production use
-## Branch Purpose
+### Related
-The `develop` branch is the **primary integration branch** for all ongoing development.
+- Target Release: **v0.0.0**
+- Repository: FireHub Runtime Foundation
-It serves as the staging area where:
-- Feature branches are merged
-- Bug fixes are integrated
-- Experimental work is stabilized
-- Code is prepared for upcoming releases
+### Pull request
-All **release branches** are created **from `develop`**.
+
-## Stability Guarantee
+## Branch Purpose
-❌ No backward compatibility guarantee
-❌ APIs may change without notice
-❌ Behavior may be incomplete or inconsistent
-❌ Breaking changes are expected
+Establish the initial PHP runtime wrapper layer by introducing the core utility classes that provide clean, consistent, and deterministic abstractions over native PHP functionality.
-This branch is intended **only for contributors and advanced testers**.
+## Architectural Goal
-## Composer Usage (Not Recommended)
+Create a lightweight, dependency-free execution layer that standardizes interaction with PHP built-in functions while maintaining predictable behavior, high performance, and a consistent API across the FireHub ecosystem.
-For internal testing only:
+## Core Concept
-```json
-{
- "require": {
- "the-firehub-project/runtime": "dev-develop"
- }
-}
-```
-⚠️ Never use dev-develop in production.
+Native PHP functionality exposed through expressive, type-safe wrapper classes, providing a unified runtime API without introducing framework coupling or altering PHP semantics.
## Authors and Contributors
From e22b301bf23b6c2e657f9c80715739e68b6bff17 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Danijel=20Gali=C4=87?=
Date: Thu, 9 Jul 2026 13:57:50 +0200
Subject: [PATCH 04/36] Update `CITATION.cff` files to correct Packagist URLs
Detailed description:
Standardized and corrected the `value` field for the `type: other` entries in `CITATION.cff` files across multiple directories (`Runtime`, `PHPStan-Rules`, `Testing`, and `Core-Standard`). Ensured consistency in referencing Packagist package URLs.
---
CITATION.cff | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/CITATION.cff b/CITATION.cff
index a215e68..0fec1e8 100644
--- a/CITATION.cff
+++ b/CITATION.cff
@@ -37,4 +37,4 @@ identifiers:
value: "https://github.com/The-FireHub-Project/Runtime"
description: The GitHub URL of this version.
- type: other
- value: "packagist:the-firehub-project/runtime"
+ value: "packagist:the-firehub-project/runtime"
\ No newline at end of file
From 1a425e104a36e2540e7771bffe82757b5a19f5d0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Danijel=20Gali=C4=87?=
Date: Mon, 13 Jul 2026 10:41:13 +0200
Subject: [PATCH 05/36] Add array runtime utilities, testing suite, and CI
setup for FireHub Runtime Core
**Details:**
- **Features:** Added new `Arr\Access`, `Arr\Inspection`, and `Arr\Pointer` utility classes for runtime-level array operations. These include methods for key/value access, inspection, and pointer manipulation.
- **Testing:** Developed comprehensive unit tests for `Arr` utilities using PHPUnit 10+ features and enhanced code coverage tracking through Codecov.
- **Setup:** Introduced `.phpstan.neon` and `phpunit.xml` configurations.
- **CI:** Added Codecov integration and GitHub workflows to ensure test coverage and repository health.
- **Other:** Updated `.gitattributes` for export-ignore and added `CountableClass` test stub and array data providers for testing scenarios.
---
.gitattributes | 2 +
.github/codecov.yaml | 11 +
.github/workflows/Codecov.yml | 22 ++
.github/workflows/PHPStan.yml | 18 ++
.github/workflows/PHPUnit.yml | 18 ++
phpstan.neon | 6 +
phpunit.xml | 16 +
src/Arr/Access.php | 371 ++++++++++++++++++++++++
src/Arr/Inspection.php | 172 +++++++++++
src/Arr/Pointer.php | 213 ++++++++++++++
src/Exception/EmptyArrayException.php | 33 +++
src/Exception/InvalidRangeException.php | 33 +++
src/Module.php | 40 +++
tests/DataProviders/ArrDataProvider.php | 67 +++++
tests/Stubs/CountableClass.php | 35 +++
tests/Unit/Arr/AccessTest.php | 297 +++++++++++++++++++
tests/Unit/Arr/InspectionTest.php | 163 +++++++++++
tests/Unit/Arr/PointerTest.php | 55 ++++
18 files changed, 1572 insertions(+)
create mode 100644 .github/codecov.yaml
create mode 100644 .github/workflows/Codecov.yml
create mode 100644 .github/workflows/PHPStan.yml
create mode 100644 .github/workflows/PHPUnit.yml
create mode 100644 phpstan.neon
create mode 100644 phpunit.xml
create mode 100644 src/Arr/Access.php
create mode 100644 src/Arr/Inspection.php
create mode 100644 src/Arr/Pointer.php
create mode 100644 src/Exception/EmptyArrayException.php
create mode 100644 src/Exception/InvalidRangeException.php
create mode 100644 src/Module.php
create mode 100644 tests/DataProviders/ArrDataProvider.php
create mode 100644 tests/Stubs/CountableClass.php
create mode 100644 tests/Unit/Arr/AccessTest.php
create mode 100644 tests/Unit/Arr/InspectionTest.php
create mode 100644 tests/Unit/Arr/PointerTest.php
diff --git a/.gitattributes b/.gitattributes
index 1e7bf2f..655489b 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -9,6 +9,8 @@
/.editorconfig export-ignore
/.gitattributes export-ignore
/.gitignore export-ignore
+/phpstan.neon export-ignore
+/phpunit.xml export-ignore
# Explicit text file types
*.php text
diff --git a/.github/codecov.yaml b/.github/codecov.yaml
new file mode 100644
index 0000000..c72c2c3
--- /dev/null
+++ b/.github/codecov.yaml
@@ -0,0 +1,11 @@
+coverage:
+ status:
+ project:
+ default:
+ target: 70%
+
+component_management:
+ default_rules:
+ statuses:
+ - type: project
+ target: auto
\ No newline at end of file
diff --git a/.github/workflows/Codecov.yml b/.github/workflows/Codecov.yml
new file mode 100644
index 0000000..1d2e0f8
--- /dev/null
+++ b/.github/workflows/Codecov.yml
@@ -0,0 +1,22 @@
+name: Code Coverage
+
+on:
+ pull_request:
+ branches:
+ - master
+ - develop
+ - 'release/v*'
+
+permissions: read-all
+
+jobs:
+ build:
+ uses: The-FireHub-Project/.github/.github/workflows/Codecov.yml@master
+ with:
+ phpVersion: '8.5'
+ phpExtensions: ${{ vars.PHP_EXTENSIONS }}
+ tools: "phpunit:13.x"
+ suites: '["unit"]'
+ secrets:
+ GH_TOKEN: ${{ secrets.GH_TOKEN }}
+ CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
\ No newline at end of file
diff --git a/.github/workflows/PHPStan.yml b/.github/workflows/PHPStan.yml
new file mode 100644
index 0000000..62e061a
--- /dev/null
+++ b/.github/workflows/PHPStan.yml
@@ -0,0 +1,18 @@
+name: PHPStan
+
+on:
+ pull_request:
+
+permissions: read-all
+
+jobs:
+ build:
+ uses: The-FireHub-Project/.github/.github/workflows/RunCommandOnMatrix.yml@master
+ with:
+ title: "Run PHPStan"
+ phpVersions: ${{ vars.PHP_VERSIONS }}
+ phpExtensions: ${{ vars.PHP_EXTENSIONS }}
+ tools: "phpstan:2.x"
+ command: "phpstan analyse"
+ secrets:
+ GH_TOKEN: ${{ secrets.GH_TOKEN }}
\ No newline at end of file
diff --git a/.github/workflows/PHPUnit.yml b/.github/workflows/PHPUnit.yml
new file mode 100644
index 0000000..3d8ae28
--- /dev/null
+++ b/.github/workflows/PHPUnit.yml
@@ -0,0 +1,18 @@
+name: PHPUnit
+
+on:
+ pull_request:
+
+permissions: read-all
+
+jobs:
+ build:
+ uses: The-FireHub-Project/.github/.github/workflows/RunCommandOnMatrix.yml@master
+ with:
+ title: "Run PHPUnit"
+ phpVersions: ${{ vars.PHP_VERSIONS }}
+ phpExtensions: ${{ vars.PHP_EXTENSIONS }}
+ tools: "phpunit:13.x"
+ command: "phpunit"
+ secrets:
+ GH_TOKEN: ${{ secrets.GH_TOKEN }}
\ No newline at end of file
diff --git a/phpstan.neon b/phpstan.neon
new file mode 100644
index 0000000..d0e5c9b
--- /dev/null
+++ b/phpstan.neon
@@ -0,0 +1,6 @@
+includes:
+ - vendor/the-firehub-project/phpstan-rules/src/Config/base.neon
+
+parameters:
+ paths:
+ - src/
\ No newline at end of file
diff --git a/phpunit.xml b/phpunit.xml
new file mode 100644
index 0000000..27667c4
--- /dev/null
+++ b/phpunit.xml
@@ -0,0 +1,16 @@
+
+
+
+
+ tests/Unit
+
+
+
+
+ src
+
+
+
\ No newline at end of file
diff --git a/src/Arr/Access.php b/src/Arr/Access.php
new file mode 100644
index 0000000..1cf5a06
--- /dev/null
+++ b/src/Arr/Access.php
@@ -0,0 +1,371 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.5
+ * @package Runtime
+ */
+
+namespace FireHub\Runtime\Arr;
+
+use FireHub\Runtime\Module;
+use FireHub\Runtime\Exception\ {
+ EmptyArrayException, InvalidRangeException
+};
+
+use function array_column;
+use function array_find;
+use function array_find_key;
+use function array_first;
+use function array_key_exists;
+use function array_key_first;
+use function array_key_last;
+use function array_keys;
+use function array_last;
+use function array_rand;
+use function array_search;
+use function array_values;
+
+/**
+ * ## PHP Array Runtime Wrapper Utility - Access
+ *
+ * The Access class provides lightweight, deterministic wrappers for accessing and retrieving data from PHP arrays.
+ *
+ * It contains common runtime operations for locating values, extracting keys, retrieving columns, and navigating
+ * array elements while preserving native PHP behavior and performance.
+ *
+ * This component is part of the FireHub Runtime layer and provides a consistent API for array access operations
+ * without introducing domain logic, framework coupling, or additional abstraction overhead.
+ * @since 1.0.0
+ */
+final class Access extends Module {
+
+ /**
+ * ### Checks if the given key or index exists in the array
+ *
+ * Returns true if the given key is set in the array.
+ * Key can be any value possible for an array index.
+ * @since 1.0.0
+ *
+ * @param array-key $key
+ * Key to check.
+ *
+ * @param array $array
+ * An array with keys to check.
+ *
+ *
+ * @return bool True if the key exists in an array, false otherwise.
+ *
+ * @note Method will search for the keys in the first dimension only.
+ * Nested keys in multidimensional arrays will not be found.
+ */
+ public static function keyExists (int|string $key, array $array):bool {
+
+ return array_key_exists($key, $array);
+
+ }
+
+ /**
+ * ### Searches the array for a given value and returns the first corresponding key if successful
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array
+ * Array to search.
+ *
+ * @param mixed $value
+ * The searched value.
+ * If $value is a string, the comparison is done in a case-sensitive manner.
+ *
+ *
+ * @return TKey|false The key for value if it is found in the array, false otherwise.
+ *
+ * @warning This method may return Boolean false but may also return a non-Boolean value which evaluates to false.
+ * Read the section on Booleans for more information.
+ * Use the === operator for testing the return value of this function.
+ */
+ public static function search (array $array, mixed $value):int|string|false {
+
+ return array_search($value, $array, true);
+
+ }
+
+ /**
+ * ### Return the values from a single column in the input array
+ *
+ * Returns the values from a single column of the $array, identified by the $key.
+ *
+ * Optionally, an argument key may be provided to $index the values in the returned array by the values from the
+ * index argument column of the input array.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TIndex of null|array-key
+ * @template TArray of array
+ *
+ * @param array $array
+ * A multidimensional array (record set) from which to pull a column of values.
+ * If an array of objects is provided, then public properties can be directly pulled.
+ * In order for protected or private properties to be pulled, the class must implement both the __get() and
+ * __isset() magic methods.
+ *
+ * @param TKey $key
+ * The column of values to return.
+ * This value may be an integer key of the column you wish to retrieve, or it may be a string key name for an
+ * associative array or property name.
+ * It may also be null to return complete arrays or objects (this is useful together with $index to reindex the
+ * array).
+ *
+ * @param TIndex $index [optional]
+ * The column to use as the index/keys for the returned array.
+ * This value may be the integer key of the column, or it may be the string key name.
+ * The value is cast as usual for array keys.
+ *
+ *
+ * @return ($index is null ? list : array) Array of values representing a single column
+ * from the input array.
+ */
+ public static function column (array $array, int|string $key, null|int|string $index = null):array {
+
+ return array_column($array, $key, $index);
+
+ }
+
+ /**
+ * ### Get the first item from an array
+ *
+ * Get the first item of the given $array without affecting the internal array pointer.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array
+ * An array.
+ *
+ *
+ * @return null|TValue First item from $array or null if an array is empty.
+ */
+ public static function first (array $array):mixed {
+
+ return array_first($array);
+
+ }
+
+ /**
+ * ### Get the last item from an array
+ *
+ * Get the last item of the given $array without affecting the internal array pointer.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array
+ * An array.
+ *
+ *
+ * @return null|TValue Last item from $array or null if an array is empty.
+ */
+ public static function last (array $array):mixed {
+
+ return array_last($array);
+
+ }
+
+ /**
+ * ### Get the first key from an array
+ *
+ * Get the first key of the given $array without affecting the internal array pointer.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array
+ * An array.
+ *
+ *
+ * @return null|TKey First key from $array or null if an array is empty.
+ */
+ public static function firstKey (array $array):null|int|string {
+
+ return array_key_first($array);
+
+ }
+
+ /**
+ * ### Get the last key from an array
+ *
+ * Get the last key of the given $array without affecting the internal array pointer.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array
+ * An array.
+ *
+ *
+ * @return null|TKey Last key from $array or null if an array is empty.
+ */
+ public static function lastKey (array $array):null|int|string {
+
+ return array_key_last($array);
+
+ }
+
+ /**
+ * ### Return all the keys or a subset of the keys for an array
+ *
+ * Returns the keys, numeric, and string, from the $array.
+ * If a $filter is specified, then only the keys for that value are returned.
+ * Otherwise, all the keys from the array are returned.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ *
+ * @param array $array
+ * An array containing keys to return.
+ *
+ * @param mixed $filter [optional]
+ * If specified, then only keys containing these values are returned.
+ *
+ *
+ * @return list An array of all the keys in the input.
+ */
+ public static function keys (array $array, mixed $filter = null):array {
+
+ return $filter !== null
+ ? array_keys($array, $filter, true)
+ : array_keys($array);
+
+ }
+
+ /**
+ * ### Return all the values from an array
+ *
+ * Returns all the values from the array and indexes the array numerically.
+ * @since 1.0.0
+ *
+ * @template TValue
+ *
+ * @param array $array
+ * The array.
+ *
+ *
+ * @return list An indexed array of values.
+ */
+ public static function values (array $array):array {
+
+ return array_values($array);
+
+ }
+
+ /**
+ * ### Returns the first element satisfying a callback function
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array
+ * The array that should be searched.
+ *
+ * @param callable(TValue, TKey):bool $callback
+ * The callback function to call to check each element.
+ *
+ *
+ * @return null|TValue The value of the first element for which the callback returns true, null otherwise.
+ */
+ public static function find (array $array, callable $callback):mixed {
+
+ return array_find($array, $callback);
+
+ }
+
+ /**
+ * ### Returns the key of the first element satisfying a callback function
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array
+ * The array that should be searched.
+ *
+ * @param callable(TValue, TKey):bool $callback
+ * The callback function to call to check each element.
+ *
+ *
+ * @return null|TKey The key of the first element for which the callback returns true, null otherwise.
+ */
+ public static function findKey (array $array, callable $callback):null|int|string {
+
+ return array_find_key($array, $callback);
+
+ }
+
+ /**
+ * ### Pick one or more random keys out of an array
+ *
+ * Picks one or more random entries out of an array and returns the key (or keys) of the random entries.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ *
+ * @param non-empty-array $array
+ * The input array.
+ *
+ * @param positive-int $number [optional]
+ * Specifies how many entries should be picked.
+ *
+ *
+ * @throws \FireHub\Runtime\Exception\EmptyArrayException If the input array is empty.
+ * @throws \FireHub\Runtime\Exception\InvalidRangeException If the number of requested random keys is less than
+ * one or exceeds the available array size.
+ *
+ * @return ($number is int<2, max> ? list : TKey) When picking only one entry, the method returns the key
+ * for a random entry.
+ * Otherwise, an array of keys for the random entries is returned.
+ *
+ * @caution This function doesn't generate cryptographically secure values and mustn't be used for cryptographic
+ * purposes, or purposes that require returned values to be unguessable.
+ */
+ public static function random (array $array, int $number = 1):int|string|array {
+
+ if ($array === []) throw new EmptyArrayException;
+
+ if ($number < 1) {
+ throw new InvalidRangeException(
+ 'The number of requested random keys must be greater than zero.',
+ [
+ 'value' => $number,
+ 'minimum' => 1,
+ ]
+ );
+ }
+
+ if ($number > $maximum = count($array)) {
+ throw new InvalidRangeException(
+ 'The number of requested random keys exceeds the available array size.',
+ [
+ 'value' => $number,
+ 'maximum' => $maximum,
+ ]
+ );
+ }
+
+ /** @var ($number is int<2, max> ? list : TKey) */
+ return array_rand($array, $number);
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Arr/Inspection.php b/src/Arr/Inspection.php
new file mode 100644
index 0000000..3c87277
--- /dev/null
+++ b/src/Arr/Inspection.php
@@ -0,0 +1,172 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.4
+ * @package Runtime
+ */
+
+namespace FireHub\Runtime\Arr;
+
+use FireHub\Runtime\Module;
+use Countable;
+
+use const COUNT_NORMAL;
+use const COUNT_RECURSIVE;
+
+use function array_all;
+use function array_any;
+use function array_count_values;
+use function array_is_list;
+use function count;
+use function in_array;
+
+/**
+ * ### PHP Array Runtime Wrapper Utility - Inspection
+ *
+ * This class is part of the FireHub Runtime layer and provides a lightweight, deterministic wrapper over native PHP
+ * functionality for its respective domain.
+ *
+ * It is designed to reduce boilerplate, standardize common runtime operations, and improve developer ergonomics
+ * through a consistent and expressive API while preserving native PHP behavior and performance.
+ *
+ * This component contains no domain logic, no framework coupling, and no business rules.
+ * @since 1.0.0
+ */
+final class Inspection extends Module {
+
+ /**
+ * ### Checks if all array elements satisfy a callback function
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array
+ * The array that should be searched.
+ *
+ * @param callable(TValue, TKey):bool $callback
+ * The callback function to call to check each element.
+ *
+ *
+ * @return bool True if callback returns true for all elements, false otherwise.
+ */
+ public static function all (array $array, callable $callback):bool {
+
+ return array_all($array, $callback);
+
+ }
+
+ /**
+ * ### Checks if at least one array element satisfies a callback function
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array
+ * The array that should be searched.
+ *
+ * @param callable(TValue, TKey):bool $callback
+ * The callback function to call to check each element.
+ *
+ *
+ * @return bool True if there is at least one element for which callback returns true, false otherwise.
+ */
+ public static function any (array $array, callable $callback):bool {
+
+ return array_any($array, $callback);
+
+ }
+
+ /**
+ * ### Checks if a value exists in an array
+ * @since 1.0.0
+ *
+ * @param array $array
+ * The array.
+ *
+ * @param mixed $value
+ * The searched value.
+ * If the value is a string, the comparison is done in a case-sensitive manner.
+ *
+ *
+ * @return bool True if a value is found in the array, false otherwise.
+ */
+ public static function inArray (array $array, mixed $value):bool {
+
+ return in_array($value, $array, true);
+
+ }
+
+ /**
+ * ### Checks whether a given array is a list
+ *
+ * Determines if the given array is a list.
+ * An array is considered a list if its keys consist of consecutive numbers from 0 to count($array)-1.
+ * @since 1.0.0
+ *
+ * @param array $array
+ * The array is being evaluated.
+ *
+ *
+ * @phpstan-assert-if-true list $array
+ *
+ * @return ($array is list ? true : false) True if an array is a list, false otherwise.
+ *
+ * @note This function returns true on empty arrays.
+ */
+ public static function isList (array $array):bool {
+
+ return array_is_list($array);
+
+ }
+
+ /**
+ * ### Counts all elements in the array
+ * @since 1.0.0
+ *
+ * @param array|Countable $value
+ * Array or Countable instance to count.
+ *
+ * @param bool $recursive [optional]
+ * Recursively count the array.
+ * This is particularly useful for counting all the elements of a multidimensional array.
+ *
+ *
+ * @return non-negative-int Number of elements in an array.
+ */
+ public static function count (array|Countable $value, bool $recursive = false):int {
+
+ return count($value, $recursive ? COUNT_RECURSIVE : COUNT_NORMAL);
+
+ }
+
+ /**
+ * ### Counts the occurrences of each distinct value in an array
+ *
+ * Returns an array using the values of $array (which must be int-s or strings) as keys and their frequency in an
+ * $array as values.
+ * @since 1.0.0
+ *
+ * @template TValue of array-key
+ *
+ * @param array $array
+ * The array of values to count.
+ *
+ *
+ * @return array An associative array of values from input as keys and their count as
+ * value.
+ */
+ public static function countValues (array $array):array {
+
+ return array_count_values($array);
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Arr/Pointer.php b/src/Arr/Pointer.php
new file mode 100644
index 0000000..4ffeb73
--- /dev/null
+++ b/src/Arr/Pointer.php
@@ -0,0 +1,213 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.5
+ * @package Runtime
+ */
+
+namespace FireHub\Runtime\Arr;
+
+use FireHub\Runtime\Module;
+
+use function current;
+use function end;
+use function key;
+use function next;
+use function prev;
+use function reset;
+
+/**
+ * ### PHP Array Runtime Wrapper Utility - Pointer
+ *
+ * The Pointer class provides lightweight, deterministic wrappers for PHP array internal pointer operations.
+ *
+ * It contains runtime utilities for navigating and manipulating the internal array pointer, including moving between
+ * elements, retrieving the current position, and resetting or advancing traversal state while preserving native PHP behavior.
+ *
+ * This component is part of the FireHub Runtime layer and provides a consistent API for low-level array pointer
+ * operations without introducing domain logic, framework coupling, or additional abstraction overhead.
+ * @since 1.0.0
+ */
+final class Pointer extends Module {
+
+ /**
+ * ### Return the current element in an array
+ *
+ * Every array has an internal pointer to its "current" element, which is initialized to the first element
+ * inserted into the array.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray $array
+ * The array.
+ *
+ *
+ * @return value-of|false The Iterables#current() function simply returns the value of the array element
+ * that is being pointed to with the internal pointer.
+ * It doesn't move the pointer in any way.
+ * If the internal pointer points beyond the end of the element list or the array is empty, Iterables#current()
+ * returns false.
+ *
+ * @warning This function may return Boolean false but may also return a non-Boolean value which evaluates to false.
+ * Read the section on Booleans for more information.
+ * Use the === operator for testing the return value of this function.
+ * @note The results of calling Iterables#current() on an empty array and on an array whose internal pointer points
+ * beyond the end of the elements is indistinguishable from a bool false element.
+ * To properly traverse an array which may contain false elements, see the foreach control structure.
+ * To still use Iterables#current() and properly check if the value is really an element of the array, the
+ * Iterables#key() of the Iterables#current() element should be checked to be strictly different from null.
+ */
+ public static function current (array $array):mixed {
+
+ return current($array);
+
+ }
+
+ /**
+ * ### Fetch a key from an array
+ *
+ * Key returns the index element of the current array position.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray $array
+ * The array.
+ *
+ *
+ * @return null|key-of The Iterables#key() function simply returns the key of the array element that's
+ * currently being pointed to by the internal pointer.
+ * It doesn't move the pointer in any way.
+ * If the internal pointer points beyond the end of the element list or the array is empty, Iterables#key()
+ * returns null.
+ */
+ public static function key (array $array):null|int|string {
+
+ return key($array);
+
+ }
+
+ /**
+ * ### Rewind the internal array pointer
+ *
+ * Method Iterables#prev() behaves like Iterables#next(), except it rewinds the internal array pointer one place
+ * instead of advancing it.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray &$array
+ * The input array.
+ *
+ * @phpstan-param-out TArray $array
+ *
+ * @return null|value-of Returns the array value in the previous place that is pointed to by the internal
+ * array pointer, or false if there are no more elements.
+ *
+ * @warning This function may return Boolean false but may also return a non-Boolean value which evaluates to false.
+ * Read the section on Booleans for more information.
+ * Use the === operator for testing the return value of this function.
+ * @note The beginning of an array is indistinguishable from a bool false element. To make the distinction, check
+ * that the Iterables#key() of the Iterables#prev() element is not null.
+ */
+ public static function prev (array &$array):mixed {
+
+ return prev($array);
+
+ }
+
+ /**
+ * ### Advance the internal pointer of an array
+ *
+ * Method Iterables#next() behaves like Iterables#current(), with one difference.
+ * It advances the internal array pointer one place forward before returning the element value.
+ * That means it returns the next array value and advances the internal array pointer by one.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray &$array
+ * The array being affected.
+ *
+ * @phpstan-param-out TArray $array
+ *
+ * @return value-of|false Returns the array value in the next place that is pointed to by the internal array
+ * pointer, or false if there are no more elements.
+ *
+ * @warning This function may return Boolean false but may also return a non-Boolean value which evaluates to false.
+ * Read the section on Booleans for more information.
+ * Use the === operator for testing the return value of this function.
+ * @note The end of an array is indistinguishable from a bool false element.
+ * To properly traverse an array which may contain false elements, see the foreach function.
+ * To still use Iterables#next() and properly check if the end of the array has been reached, verify that the
+ * Iterables#key() is null.
+ */
+ public static function next (array &$array):mixed {
+
+ return next($array);
+
+ }
+
+ /**
+ * ### Set the internal pointer of an array to its first element
+ *
+ * Method Iterables#reset() rewinds the array's internal pointer to the first element and returns the value of
+ * the first array element.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray &$array
+ * The input array.
+ *
+ * @phpstan-param-out TArray $array
+ *
+ * @return value-of|false Returns the value of the first array element, or false if the array is empty.
+ *
+ * @warning This function may return Boolean false but may also return a non-Boolean value which evaluates to false.
+ * Read the section on Booleans for more information.
+ * Use the === operator for testing the return value of this function.
+ * @note The return value for an empty array is indistinguishable from the return value in the case of an array
+ * which has a bool false first element.
+ * To properly check the value of the first element in an array which may contain false elements, first check the
+ * Iterables#count() of the array, or check that Iterables#key() is not null, after calling Iterables#reset().
+ */
+ public static function reset (array &$array):mixed {
+
+ return reset($array);
+
+ }
+
+ /**
+ * ### Set the internal pointer of an array to its last element
+ *
+ * Method Iterables#end() advances the array's internal pointer to the last element and returns its value.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray &$array
*
* @return bool True if the key exists in an array, false otherwise.
*
* @note Method will search for the keys in the first dimension only.
* Nested keys in multidimensional arrays will not be found.
*/
- public static function keyExists (int|string $key, array $array):bool {
+ public static function keyExists (array $array, int|string $key):bool {
return array_key_exists($key, $array);
@@ -72,6 +72,8 @@ public static function keyExists (int|string $key, array $array):bool {
/**
* ### Searches the array for a given value and returns the first corresponding key if successful
+ *
+ * Performs a strict comparison when searching for the value.
* @since 1.0.0
*
* @template TKey of array-key
@@ -111,21 +113,27 @@ public static function search (array $array, mixed $value):int|string|false {
* @template TArray of array
*
* @param array $array
- * A multidimensional array (record set) from which to pull a column of values.
- * If an array of objects is provided, then public properties can be directly pulled.
+ * A multidimensional array (record set) from which to pull a column of values.
+ *
+ * If an array of objects is provided, then public properties can be directly pulled.
+ *
* In order for protected or private properties to be pulled, the class must implement both the __get() and
- * __isset() magic methods.
+ * __isset() magic methods.
*
* @param TKey $key
- * The column of values to return.
+ * The column of values to return.
+ *
* This value may be an integer key of the column you wish to retrieve, or it may be a string key name for an
- * associative array or property name.
+ * associative array or property name.
+ *
* It may also be null to return complete arrays or objects (this is useful together with $index to reindex the
- * array).
+ * array).
*
* @param TIndex $index [optional]
- * The column to use as the index/keys for the returned array.
- * This value may be the integer key of the column, or it may be the string key name.
+ * The column to use as the index/keys for the returned array.
+ *
+ * This value may be the integer key of the column, or it may be the string key name.
+ *
* The value is cast as usual for array keys.
*
*
@@ -225,8 +233,10 @@ public static function lastKey (array $array):null|int|string {
/**
* ### Return all the keys or a subset of the keys for an array
*
- * Returns the keys, numeric, and string, from the $array.
- * If a $filter is specified, then only the keys for that value are returned.
+ * Returns the keys, numeric, and string, from the $array.
+ *
+ * If a $filter is specified, then only the keys for that value are returned.
+ *
* Otherwise, all the keys from the array are returned.
* @since 1.0.0
*
@@ -319,6 +329,8 @@ public static function findKey (array $array, callable $callback):null|int|strin
* Picks one or more random entries out of an array and returns the key (or keys) of the random entries.
* @since 1.0.0
*
+ * @uses \FireHub\Runtime\Arr\Inspection::count() To check the number of requested random keys.
+ *
* @template TKey of array-key
*
* @param non-empty-array $array
@@ -329,11 +341,12 @@ public static function findKey (array $array, callable $callback):null|int|strin
*
*
* @throws \FireHub\Runtime\Exception\EmptyArrayException If the input array is empty.
- * @throws \FireHub\Runtime\Exception\InvalidRangeException If the number of requested random keys is less than
- * one or exceeds the available array size.
+ * @throws \FireHub\Runtime\Exception\InvalidRandomKeyCountException If the number of requested random keys is less
+ * than one or exceeds the available array size.
*
* @return ($number is int<2, max> ? list : TKey) When picking only one entry, the method returns the key
- * for a random entry.
+ * for a random entry.
+ *
* Otherwise, an array of keys for the random entries is returned.
*
* @caution This function doesn't generate cryptographically secure values and mustn't be used for cryptographic
@@ -344,20 +357,20 @@ public static function random (array $array, int $number = 1):int|string|array {
if ($array === []) throw new EmptyArrayException;
if ($number < 1) {
- throw new InvalidRangeException(
+ throw new InvalidRandomKeyCountException(
'The number of requested random keys must be greater than zero.',
[
- 'value' => $number,
+ 'number' => $number,
'minimum' => 1,
]
);
}
- if ($number > $maximum = count($array)) {
- throw new InvalidRangeException(
+ if ($number > $maximum = Inspection::count($array)) {
+ throw new InvalidRandomKeyCountException(
'The number of requested random keys exceeds the available array size.',
[
- 'value' => $number,
+ 'number' => $number,
'maximum' => $maximum,
]
);
diff --git a/src/Arr/Composition.php b/src/Arr/Composition.php
new file mode 100644
index 0000000..303ae68
--- /dev/null
+++ b/src/Arr/Composition.php
@@ -0,0 +1,230 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=7.4
+ * @package Runtime
+ */
+
+namespace FireHub\Runtime\Arr;
+
+use FireHub\Core\Boundary\Runtime\NativeRuntime;
+use FireHub\Runtime\Exception\ArrayKeysAndValuesCountMismatchException;
+
+use function array_combine;
+use function array_merge;
+use function array_merge_recursive;
+use function array_replace;
+use function array_replace_recursive;
+
+/**
+ * ### PHP Array Runtime Wrapper Utility - Composition
+ *
+ * The Composition class provides lightweight, deterministic wrappers for composing arrays from multiple sources.
+ *
+ * It contains common runtime operations for merging arrays, replacing values, combining keys with values, and creating
+ * new array structures through composition while preserving native PHP behavior and performance.
+ *
+ * This component is part of the FireHub Runtime layer and provides a consistent API for array composition operations
+ * without introducing domain logic, framework coupling, or additional abstraction overhead.
+ * @since 1.0.0
+ */
+final class Composition extends NativeRuntime {
+
+ /**
+ * ### Creates an array by using one array for keys and another for its values
+ *
+ * Creates an array by using the values from the $keys array as keys and the values from the $values array as the
+ * corresponding values.
+ * @since 1.0.0
+ *
+ * @uses \FireHub\Runtime\Arr\Inspection::count() To check the number of keys and values.
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $keys
+ * Array of values to be used as keys.
+ *
+ * Illegal values for a key will be converted to string.
+ *
+ * @param array $values
+ * Array of values to be used as values on a combined array.
+ *
+ *
+ * @throws \FireHub\Runtime\Exception\ArrayKeysAndValuesCountMismatchException If the number of keys and values
+ * doesn't match.
+ *
+ * @return array The combined array.
+ */
+ public static function combine (array $keys, array $values):array {
+
+ if (($key_count = Inspection::count($keys)) !== ($value_count = Inspection::count($values))) {
+ throw new ArrayKeysAndValuesCountMismatchException(
+ 'The number of keys and values must be equal.',
+ [
+ 'keys' => $key_count,
+ 'values' => $value_count,
+ ]
+ );
+ }
+
+ return array_combine($keys, $values);
+
+ }
+
+ /**
+ * ### Merges the elements of one or more arrays
+ *
+ * Merges the elements of one or more arrays so that the values of one are appended to the end of
+ * the previous one.
+ *
+ * It returns the resulting array.
+ *
+ * If the input arrays have the same string keys, then the later value for that key will overwrite the previous one.
+ *
+ * If, however, the arrays contain numeric keys, the later value will not overwrite the original value but will
+ * be appended.
+ *
+ * Values in the input arrays with numeric keys will be renumbered with incrementing keys starting from zero in
+ * the result array.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array ...$arrays [optional]
+ * Variable list of arrays to merge.
+ *
+ *
+ * @return array The resulting array.
+ *
+ * @note If the input arrays have the same string keys, then the later value for that key will overwrite
+ * the previous one.
+ * @note If the arrays contain numeric keys, the later value will be appended.
+ * @note Numeric keys will be renumbered.
+ */
+ public static function merge (array ...$arrays):array {
+
+ return array_merge(...$arrays);
+
+ }
+
+ /**
+ * ### Merge two or more arrays recursively
+ *
+ * Merges the elements of one or more arrays so that the values of one are appended to the end of the
+ * previous one.
+ *
+ * It returns the resulting array.
+ *
+ * If the input arrays have the same string keys, then the values for these keys are merged into an array.
+ *
+ * This is done recursively, so that if one of the values is an array itself, the function will merge it with a
+ * corresponding entry in another array too.
+ *
+ * If, however, the arrays have the same numeric key, the later value will not overwrite the original value but
+ * will be appended.
+ * @since 1.0.0
+ *
+ * @param array ...$arrays [optional]
+ * Variable list of arrays to recursively merge.
+ *
+ *
+ * @return array The resulting array.
+ */
+ public static function mergeRecursive (array ...$arrays):array {
+
+ return array_merge_recursive(...$arrays);
+
+ }
+
+ /**
+ * ### Replaces elements from passed arrays into the first array
+ *
+ * Replaces the values of $array with values having the same keys in each of the following arrays.
+ *
+ * If a key from the first array exists in the second array, its value will be replaced by the value from the
+ * second array.
+ *
+ * If the key exists in the second array, and not the first, it will be created in the first array.
+ *
+ * If a key only exists in the first array, it will be left as is.
+ *
+ * If several arrays are passed for replacement, they will be processed in order, the later arrays overwriting
+ * the previous values.
+ *
+ * Method is not recursive, it will replace values in the first array by whatever type is in the second array.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValueOriginal
+ * @template TValueReplacement
+ *
+ * @param array $array
+ * The array in which elements are replaced.
+ *
+ * @param array ...$replacements
+ * Arrays from which elements will be extracted.
+ *
+ * Values from later arrays overwrite the previous values.
+ *
+ *
+ * @return array The resulting array.
+ */
+ public static function replace (array $array, array ...$replacements):array {
+
+ return array_replace($array, ...$replacements);
+
+ }
+
+ /**
+ * ### Replace two or more arrays recursively
+ *
+ * Replaces the values of $array with the same values from all the following arrays.
+ *
+ * If a key from the first array exists in the second array, its value will be replaced by the value from the
+ * second array.
+ *
+ * If the key exists in the second array, and not the first, it will be created in the first array.
+ *
+ * If a key only exists in the first array, it will be left as is.
+ *
+ * If several arrays are passed for replacement, they will be processed in order, the later array overwriting the
+ * previous values.
+ *
+ * When the value in the first array is scalar, it will be replaced by the value in the second array, may it be
+ * scalar or array.
+ *
+ * When the value in the first array and the second array are both arrays, Arr#replaceRecursive() will replace
+ * their respective values recursively.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValueOriginal
+ * @template TValueReplacement
+ *
+ * @param array $array
+ * The array in which elements are replaced.
+ *
+ * @param array ...$replacements
+ * Arrays from which elements will be extracted.
+ *
+ * Values from later arrays overwrite the previous values.
+ *
+
+ * @return array The resulting array.
+ */
+ public static function replaceRecursive (array $array, array ...$replacements):array {
+
+ /** @var array */
+ return array_replace_recursive($array, ...$replacements);
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Arr/Inspection.php b/src/Arr/Inspection.php
index 3c87277..0b09cc5 100644
--- a/src/Arr/Inspection.php
+++ b/src/Arr/Inspection.php
@@ -13,7 +13,7 @@
namespace FireHub\Runtime\Arr;
-use FireHub\Runtime\Module;
+use FireHub\Core\Boundary\Runtime\NativeRuntime;
use Countable;
use const COUNT_NORMAL;
@@ -38,7 +38,7 @@
* This component contains no domain logic, no framework coupling, and no business rules.
* @since 1.0.0
*/
-final class Inspection extends Module {
+final class Inspection extends NativeRuntime {
/**
* ### Checks if all array elements satisfy a callback function
@@ -96,7 +96,7 @@ public static function any (array $array, callable $callback):bool {
* If the value is a string, the comparison is done in a case-sensitive manner.
*
*
- * @return bool True if a value is found in the array, false otherwise.
+ * @return bool Returns true if the given value exists in the array using strict comparison.
*/
public static function inArray (array $array, mixed $value):bool {
@@ -135,7 +135,8 @@ public static function isList (array $array):bool {
* Array or Countable instance to count.
*
* @param bool $recursive [optional]
- * Recursively count the array.
+ * Recursively count the array.
+ *
* This is particularly useful for counting all the elements of a multidimensional array.
*
*
diff --git a/src/Arr/Math.php b/src/Arr/Math.php
new file mode 100644
index 0000000..e4e770c
--- /dev/null
+++ b/src/Arr/Math.php
@@ -0,0 +1,71 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.0
+ * @package Runtime
+ */
+
+namespace FireHub\Runtime\Arr;
+
+use FireHub\Core\Boundary\Runtime\NativeRuntime;
+
+use function array_product;
+use function array_sum;
+
+/**
+ * ### PHP Array Runtime Wrapper Utility - Math
+ *
+ * Provides runtime wrappers for performing mathematical operations on arrays, including aggregation and calculation
+ * of numerical values while preserving native PHP behavior.
+ *
+ * This component is part of the FireHub Runtime layer and provides a consistent API for array mathematical operations
+ * without introducing domain logic, framework coupling, or additional abstraction overhead.
+ * @since 1.0.0
+ */
+final class Math extends NativeRuntime {
+
+ /**
+ * ### Calculate the product of values in an array
+ *
+ * Returns the product of values in an array.
+ * @since 1.0.0
+ *
+ * @template TValue of int|float
+ *
+ * @param array $array
+ * The array.
+ *
+ *
+ * @return int|float The product as an integer or float.
+ */
+ public static function product (array $array):int|float {
+
+ return array_product($array);
+
+ }
+
+ /**
+ * ### Calculate the sum of values in an array
+ * @since 1.0.0
+ *
+ * @template TValue of int|float
+ *
+ * @param array $array
+ * The input array.
+ *
+ *
+ * @return int|float The sum of values as an integer or float; 0 if the array is empty.
+ */
+ public static function sum (array $array):int|float {
+
+ return array_sum($array);
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Arr/Mutation.php b/src/Arr/Mutation.php
new file mode 100644
index 0000000..5a0ff92
--- /dev/null
+++ b/src/Arr/Mutation.php
@@ -0,0 +1,148 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.0
+ * @package Runtime
+ */
+
+namespace FireHub\Runtime\Arr;
+
+use FireHub\Core\Boundary\Runtime\NativeRuntime;
+
+use function array_pop;
+use function array_push;
+use function array_shift;
+use function array_unshift;
+
+/**
+ * ### PHP Array Runtime Wrapper Utility - Mutation
+ *
+ * Provides runtime wrappers for modifying arrays through direct value insertion, removal, and queue or stack
+ * operations while preserving native PHP behavior.
+ *
+ * This component is part of the FireHub Runtime layer and provides a consistent API for array mutation operations
+ * without introducing domain logic, framework coupling, or additional abstraction overhead.
+ * @since 1.0.0
+ */
+final class Mutation extends NativeRuntime {
+
+ /**
+ * ### Pop the element off the end of an array
+ *
+ * Pops and returns the last element value of the $array, shortening the $array by one element.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray &$array
+ * The array to get the value from.
+ *
+ * @phpstan-param-out TArray $array
+ *
+ * @return null|value-of The last value of an array. If an array is empty (or is not an array), null will
+ * be returned.
+ *
+ * @note This function will reset the array pointer of the input array after use.
+ */
+ public static function pop (array &$array):mixed {
+
+ return array_pop($array);
+
+ }
+
+ /**
+ * ### Push elements onto the end of an array
+ *
+ * Method treats an array as a stack and pushes the passed variables onto the end of an array.
+ *
+ * The length of an array increases by the number of variables pushed.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ * @template TPushedValue
+ *
+ * @param array &$array
+ * The input array.
+ *
+ * @param TPushedValue ...$values [optional]
+ * The values to push onto the end of the array.
+ *
+ * @phpstan-param-out array $array
+ *
+ * @return int The new number of elements in the array.
+ *
+ * @note If you use push to add one element to the array, it is better to use $array[] = because in that way
+ * there is no overhead of calling a function.
+ */
+ public static function push (array &$array, mixed ...$values):int {
+
+ return array_push($array, ...$values);
+
+ }
+
+ /**
+ * ### Removes an item at the beginning of an array
+ *
+ * Shifts the first value of the array off and returns it, shortening the array by one element and moving
+ * everything down.
+ *
+ * All numerical array keys will be modified to start counting from zero while literal keys won't be affected.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray &$array
+ * Array to shift.
+ *
+ * @phpstan-param-out TArray $array
+ *
+ * @return null|value-of The shifted value, or null if an array is empty or is not an array.
+ *
+ * @note This function will reset the array pointer of the input array after use.
+ */
+ public static function shift (array &$array):mixed {
+
+ return array_shift($array);
+
+ }
+
+ /**
+ * ### Prepend one or more elements to the beginning of an array
+ *
+ * Method prepends passed elements to the front of the array.
+ *
+ * Note that the list of elements is prepended as a whole so that the prepended elements stay in the same order.
+ *
+ * All numerical array keys will be modified to start counting from zero, while literal keys won't be changed.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ * @template TUnshiftValue
+ *
+ * @param array &$array
+ * The input array.
+ *
+ * @param TUnshiftValue ...$values [optional]
+ * The values to prepend.
+ *
+ * @phpstan-param-out array $array
+ *
+ * @return int The new number of elements in the array.
+ *
+ * @note Resets array's internal pointer to the first element.
+ */
+ public static function unshift (array &$array, mixed ...$values):int {
+
+ return array_unshift($array, ...$values);
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Arr/Ordering.php b/src/Arr/Ordering.php
new file mode 100644
index 0000000..abd3ac0
--- /dev/null
+++ b/src/Arr/Ordering.php
@@ -0,0 +1,242 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Runtime
+ */
+
+namespace FireHub\Runtime\Arr;
+
+use FireHub\Core\Boundary\Runtime\NativeRuntime;
+use FireHub\Core\Meta\Enum\Order;
+use FireHub\Runtime\Type\Arr\ {
+ SortFlag, SortType
+};
+
+use function array_multisort;
+use function arsort;
+use function asort;
+use function krsort;
+use function ksort;
+use function rsort;
+use function shuffle;
+use function sort;
+use function uasort;
+use function uksort;
+use function usort;
+
+/**
+ * ### PHP Array Runtime Wrapper Utility - Ordering
+ *
+ * Provides runtime wrappers for ordering, sorting, and rearranging array elements while preserving native PHP behavior
+ * and performance.
+ *
+ * This component is part of the FireHub Runtime layer and provides a consistent API for array ordering operations
+ * without introducing domain logic, framework coupling, or additional abstraction overhead.
+ * @since 1.0.0
+ */
+final class Ordering extends NativeRuntime {
+
+ /**
+ * ### Sorts array
+ * @since 1.0.0
+ *
+ * @uses \FireHub\Core\Meta\Enum\Order::ASC As default parameter.
+ * @uses \FireHub\Runtime\Type\Arr\SortType::BY_REGULAR As default parameter.
+ * @uses \FireHub\Runtime\Type\Arr\SortFlag: As default parameter.
+ *
+ * @template TArray of array
+ *
+ * @param TArray &$array
+ * Array to sort.
+ *
+ * @param bool $preserve_keys [optional]
+ * Whether you want to preserve keys from an original array or not.
+ *
+ * The comparison function must return an integer less than, equal to, or greater than zero if the first argument
+ * is considered to be respectively less than, equal to, or greater than the second.
+ *
+ * @param bool $preserve_keys [optional]
+ * Whether you want to preserve keys from an original array or not.
+ *
+ * @phpstan-param-out ($preserve_keys is true ? TArray : list>) $array
+ *
+ * @return true Always true.
+ *
+ * @caution Returning non-integer values from the comparison function, such as float, will result in an internal
+ * cast to int of the callback's return value.
+ *
+ * So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as
+ * equal.
+ */
+ public static function sortBy (array &$array, callable $callback, bool $preserve_keys = false):true {
+
+ return $preserve_keys
+ ? uasort($array, $callback)
+ : usort($array, $callback);
+
+ }
+
+ /**
+ * ### Sorts an array by key using a user-defined comparison function
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray &$array
+ * The callback comparison function.
+ *
+ * Function cmp_function should accept two parameters which will be filled by pairs of array keys.
+ *
+ * The comparison function must return an integer less than, equal to, or greater than zero if the first argument
+ * is considered to be respectively less than, equal to, or greater than the second.
+ *
+ *
+ * @return true True on success.
+ *
+ * @caution Associative (string) keys will be maintained, but numeric keys will be re-indexed.
+ * @note Resets array's internal pointer to the first element.
+ */
+ public static function multiSort (array &...$array):bool {
+
+ return array_multisort(...$array);
+
+ }
+
+ /**
+ * ### Shuffle array
+ *
+ * This function shuffles (randomizes the order of the elements in) an array.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray &$array
+ * The array.
+ *
+ * @phpstan-param-out TArray $array
+ *
+ * @return true Always returns true.
+ *
+ * @caution This function doesn't generate cryptographically secure values and mustn't be used for cryptographic
+ * purposes, or purposes that require returned values to be unguessable.
+ * @note This function assigns new keys to the elements in an array.
+ * It will remove any existing keys that may have been assigned, rather than reordering the keys.
+ * @note Resets array's internal pointer to the first element.
+ */
+ public static function shuffle (array &$array):true {
+
+ return shuffle($array);
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Arr/Pointer.php b/src/Arr/Pointer.php
index 4ffeb73..f58fedb 100644
--- a/src/Arr/Pointer.php
+++ b/src/Arr/Pointer.php
@@ -13,7 +13,7 @@
namespace FireHub\Runtime\Arr;
-use FireHub\Runtime\Module;
+use FireHub\Core\Boundary\Runtime\NativeRuntime;
use function current;
use function end;
@@ -34,7 +34,7 @@
* operations without introducing domain logic, framework coupling, or additional abstraction overhead.
* @since 1.0.0
*/
-final class Pointer extends Module {
+final class Pointer extends NativeRuntime {
/**
* ### Return the current element in an array
@@ -50,17 +50,23 @@ final class Pointer extends Module {
*
*
* @return value-of|false The Iterables#current() function simply returns the value of the array element
- * that is being pointed to with the internal pointer.
- * It doesn't move the pointer in any way.
+ * that is being pointed to with the internal pointer.
+ *
+ * It doesn't move the pointer in any way.
+ *
* If the internal pointer points beyond the end of the element list or the array is empty, Iterables#current()
* returns false.
*
- * @warning This function may return Boolean false but may also return a non-Boolean value which evaluates to false.
- * Read the section on Booleans for more information.
+ * @warning This function may return Boolean false but may also return a non-Boolean value which evaluates to false.
+ *
+ * Read the section on Booleans for more information.
+ *
* Use the === operator for testing the return value of this function.
* @note The results of calling Iterables#current() on an empty array and on an array whose internal pointer points
- * beyond the end of the elements is indistinguishable from a bool false element.
- * To properly traverse an array which may contain false elements, see the foreach control structure.
+ * beyond the end of the elements is indistinguishable from a bool false element.
+ *
+ * To properly traverse an array which may contain false elements, see the foreach control structure.
+ *
* To still use Iterables#current() and properly check if the value is really an element of the array, the
* Iterables#key() of the Iterables#current() element should be checked to be strictly different from null.
*/
@@ -83,8 +89,10 @@ public static function current (array $array):mixed {
*
*
* @return null|key-of The Iterables#key() function simply returns the key of the array element that's
- * currently being pointed to by the internal pointer.
- * It doesn't move the pointer in any way.
+ * currently being pointed to by the internal pointer.
+ *
+ * It doesn't move the pointer in any way.
+ *
* If the internal pointer points beyond the end of the element list or the array is empty, Iterables#key()
* returns null.
*/
@@ -112,7 +120,8 @@ public static function key (array $array):null|int|string {
* array pointer, or false if there are no more elements.
*
* @warning This function may return Boolean false but may also return a non-Boolean value which evaluates to false.
- * Read the section on Booleans for more information.
+ * Read the section on Booleans for more information.
+ *
* Use the === operator for testing the return value of this function.
* @note The beginning of an array is indistinguishable from a bool false element. To make the distinction, check
* that the Iterables#key() of the Iterables#prev() element is not null.
@@ -126,8 +135,10 @@ public static function prev (array &$array):mixed {
/**
* ### Advance the internal pointer of an array
*
- * Method Iterables#next() behaves like Iterables#current(), with one difference.
- * It advances the internal array pointer one place forward before returning the element value.
+ * Method Iterables#next() behaves like Iterables#current(), with one difference.
+ *
+ * It advances the internal array pointer one place forward before returning the element value.
+ *
* That means it returns the next array value and advances the internal array pointer by one.
* @since 1.0.0
*
@@ -141,11 +152,14 @@ public static function prev (array &$array):mixed {
* @return value-of|false Returns the array value in the next place that is pointed to by the internal array
* pointer, or false if there are no more elements.
*
- * @warning This function may return Boolean false but may also return a non-Boolean value which evaluates to false.
- * Read the section on Booleans for more information.
+ * @warning This function may return Boolean false but may also return a non-Boolean value which evaluates to false.
+ *
+ * Read the section on Booleans for more information.
+ *
* Use the === operator for testing the return value of this function.
- * @note The end of an array is indistinguishable from a bool false element.
- * To properly traverse an array which may contain false elements, see the foreach function.
+ * @note The end of an array is indistinguishable from a bool false element.
+ * To properly traverse an array which may contain false elements, see the foreach function.
+ *
* To still use Iterables#next() and properly check if the end of the array has been reached, verify that the
* Iterables#key() is null.
*/
@@ -171,11 +185,14 @@ public static function next (array &$array):mixed {
*
* @return value-of|false Returns the value of the first array element, or false if the array is empty.
*
- * @warning This function may return Boolean false but may also return a non-Boolean value which evaluates to false.
- * Read the section on Booleans for more information.
+ * @warning This function may return Boolean false but may also return a non-Boolean value which evaluates to false.
+ *
+ * Read the section on Booleans for more information.
+ *
* Use the === operator for testing the return value of this function.
* @note The return value for an empty array is indistinguishable from the return value in the case of an array
- * which has a bool false first element.
+ * which has a bool false first element.
+ *
* To properly check the value of the first element in an array which may contain false elements, first check the
* Iterables#count() of the array, or check that Iterables#key() is not null, after calling Iterables#reset().
*/
@@ -200,8 +217,10 @@ public static function reset (array &$array):mixed {
*
* @return value-of|false Returns the value of the last element or false for an empty array.
*
- * @warning This function may return Boolean false but may also return a non-Boolean value which evaluates to false.
- * Read the section on Booleans for more information.
+ * @warning This function may return Boolean false but may also return a non-Boolean value which evaluates to false.
+ *
+ * Read the section on Booleans for more information.
+ *
* Use the === operator for testing the return value of this function.
*/
public static function end (array &$array):mixed {
diff --git a/src/Arr/SetOperation.php b/src/Arr/SetOperation.php
new file mode 100644
index 0000000..db1eff9
--- /dev/null
+++ b/src/Arr/SetOperation.php
@@ -0,0 +1,587 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=7.4
+ * @package Runtime
+ */
+
+namespace FireHub\Runtime\Arr;
+
+use FireHub\Core\Boundary\Runtime\NativeRuntime;
+
+use function array_diff;
+use function array_diff_assoc;
+use function array_diff_key;
+use function array_diff_uassoc;
+use function array_diff_ukey;
+use function array_intersect;
+use function array_intersect_assoc;
+use function array_intersect_key;
+use function array_intersect_uassoc;
+use function array_intersect_ukey;
+use function array_udiff;
+use function array_udiff_assoc;
+use function array_udiff_uassoc;
+use function array_uintersect;
+use function array_uintersect_assoc;
+use function array_uintersect_uassoc;
+
+/**
+ * ### PHP Array Runtime Wrapper Utility - SetOperation
+ *
+ * Provides runtime wrappers for performing set-based operations on arrays, including difference, intersection,
+ * and user-defined comparison while preserving native PHP behavior and performance.
+ *
+ * This component is part of the FireHub Runtime layer and provides a consistent API for array set operations
+ * without introducing domain logic, framework coupling, or additional abstraction overhead.
+ * @since 1.0.0
+ */
+final class SetOperation extends NativeRuntime {
+
+ /**
+ * ### Computes the difference of arrays using values for comparison
+ *
+ * Compares an array against one or more other arrays and returns the values in an array that aren't present in any
+ * of the other arrays.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray $array
+ * The array to compare from.
+ *
+ * @param array ...$excludes [optional]
+ * An array to compare against.
+ *
+ *
+ * @return TArray An array containing all the entries from $array that aren't present in any of the other arrays.
+ *
+ * @note This function only checks one dimension of an n-dimensional array.
+ * You can check deeper dimensions by using Arr#difference($array1[0], $array2[0]).
+ */
+ public static function difference (array $array, array ...$excludes):array {
+
+ /** @var TArray */
+ return array_diff($array, ...$excludes);
+
+ }
+
+ /**
+ * ### Computes the difference of arrays using values for comparison by using a callback for comparison
+ *
+ * Computes the difference of arrays by using a callback function for data comparison.
+ * This is unlike Arr#difference() which uses an internal function for comparing the data.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ * @template TCompareArray of array
+ *
+ * @param TArray $array
+ * The comparison function must return an integer less than, equal to, or greater than zero if the first argument
+ * is considered to be respectively less than, equal to, or greater than the second.
+ *
+ *
+ * @return TArray An array containing all the entries from $array that aren't present in any of
+ * the other arrays.
+ *
+ * @caution Returning non-integer values from the comparison function, such as float, will result in an internal
+ * cast to int of the callback's return value.
+ * So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as
+ * equal.
+ * @note Note that this function only checks one dimension of an n-dimensional array.
+ * Of course, you can check deeper dimensions by using
+ * Arr#differenceFunc($array1[0], $array2[0], 'data_compare_func').
+ */
+ public static function differenceUsing (array $array, array $excludes, callable $callback):array {
+
+ /** @var TArray */
+ return array_udiff($array, $excludes, $callback);
+
+ }
+
+ /**
+ * ### Computes the difference of arrays using keys for comparison
+ *
+ * Compares the keys from an array against the keys from arrays and returns the difference.
+ * This function is like Arr#difference() except the comparison is done on the keys instead of the values.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray $array
+ * The array to compare from.
+ *
+ * @param array ...$excludes [optional]
+ * An array to compare against.
+ *
+ *
+ * @return TArray Returns an array containing all the entries from an array whose keys are absent from all the
+ * other arrays.
+ *
+ * @note This function only checks one dimension of an n-dimensional array.
+ * Of course, you can check deeper dimensions by using Arr#differenceKey($array1[0], $array2[0]).
+ */
+ public static function differenceKey (array $array, array ...$excludes):array {
+
+ /** @var TArray */
+ return array_diff_key($array, ...$excludes);
+
+ }
+
+ /**
+ * ### Computes the difference of arrays using keys for comparison by using a callback for data comparison
+ *
+ * Compares the keys from an array against the keys from arrays and returns the difference.
+ * This function is like Arr#difference() except the comparison is done on the keys instead of the values.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ * @template TCompareArray of array
+ *
+ * @param TArray $array
+ *
+ * @return TArray An array containing all the entries from $array that aren't present in any of the other arrays.
+ *
+ * @caution Returning non-integer values from the comparison function, such as float, will result in an internal
+ * cast to int of the callback's return value.
+ * So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as
+ * equal.
+ * @note This function only checks one dimension of an n-dimensional array.
+ * Of course, you can check deeper dimensions by using
+ * Arr#differenceKeyFunc($array1[0], $array2[0], 'callback_func').
+ */
+ public static function differenceUsingKey (array $array, array $excludes, callable $callback):array {
+
+ /** @var TArray */
+ return array_diff_ukey($array, $excludes, $callback);
+
+ }
+
+ /**
+ * ### Computes the difference of arrays with additional index check
+ *
+ * Compares an array against arrays and returns the difference.
+ * Unlike Arr#difference(), the array keys are also used in the comparison.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray $array
+ * The array to compare from.
+ *
+ * @param array ...$excludes [optional]
+ * An array to compare against.
+ *
+ *
+ * @return TArray An array containing all the entries from $array that aren't present in any of
+ * the other arrays.
+ *
+ * @note This function only checks one dimension of an n-dimensional array.
+ * It is possible to check deeper dimensions by using, for example, Arr#differenceAssoc($array1[0], $array2[0]).
+ * @note Ensure arguments are passed in the correct order when comparing similar arrays with more keys.
+ * The new array should be the first in the list.
+ */
+ public static function differenceAssoc (array $array, array ...$excludes):array {
+
+ /** @var TArray */
+ return array_diff_assoc($array, ...$excludes);
+
+ }
+
+ /**
+ * ### Computes the difference of arrays with additional index check by using a callback for value comparison
+ *
+ * Computes the difference of arrays with an additional index check, compares data by a callback function.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ * @template TCompareArray of array
+ *
+ * @param TArray $array
+ *
+ * @return TArray An array containing all the entries from $array that aren't present in any of the other arrays.
+ *
+ * @caution Returning non-integer values from the comparison function, such as float, will result in an internal
+ * cast to int of the callback's return value.
+ * So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as
+ * equal.
+ * @note Note that this function only checks one dimension of an n-dimensional array.
+ * Of course, you can check deeper dimensions by using, for example,
+ * Arr#differenceAssocFuncValue($array1[0], $array2[0], some_comparison_func').
+ */
+ public static function differenceAssocUsingValue (array $array, array $excludes, callable $callback):array {
+
+ /** @var TArray */
+ return array_udiff_assoc($array, $excludes, $callback);
+
+ }
+
+ /**
+ * ### Computes the difference of arrays with additional index check by using a callback for key comparison
+ *
+ * Compares an array against arrays and returns the difference.
+ * Unlike Arr#difference(), the array keys are used in the comparison.
+ * Unlike Arr#differenceAssoc(), a user-supplied callback function is used for the indices' comparison,
+ * not an internal function.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ * @template TCompareArray of array
+ *
+ * @param TArray $array
+ *
+ * @return TArray Returns an array containing all the entries from $array that aren't present in any of the other
+ * arrays.
+ *
+ * @caution Returning non-integer values from the comparison function, such as float, will result in an internal
+ * cast to int of the callback's return value.
+ * So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as
+ * equal.
+ * @note This function only checks one dimension of an n-dimensional array.
+ * It is possible to check deeper dimensions by using, for example,
+ * Arr#differenceAssocFuncKey($array1[0], $array2[0], 'key_compare_func').
+ */
+ public static function differenceAssocUsingKey (array $array, array $excludes, callable $callback):array {
+
+ /** @var TArray */
+ return array_diff_uassoc($array, $excludes, $callback);
+
+ }
+
+ /**
+ * ### Computes the difference of arrays with additional index check by using a callback for key-value comparison
+ *
+ * Computes the difference of arrays with additional index check, compares data, and indexes by a callback function.
+ * Note that the keys are used in the comparison unlike Arr#difference() and Arr#differenceFunc().
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ * @template TCompareArray of array
+ *
+ * @param TArray $array
+ *
+ * @return TArray An array containing all the entries from $array that aren't present in any of
+ * the other arrays.
+ *
+ * @caution Returning non-integer values from the comparison function, such as float, will result in an internal
+ * cast to int of the callback's return value.
+ * So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as
+ * equal.
+ * @note This function only checks one dimension of an n-dimensional array.
+ * It is possible to check deeper dimensions by using, for example,
+ * Arr#differenceAssocFuncKeyValue($array1[0], $array2[0], 'data_compare_func', 'key_compare_func').
+ */
+ public static function differenceAssocUsingKeyValue (array $array, array $excludes, callable $callback_value, callable $callback_key):array {
+
+ /** @var TArray */
+ return array_udiff_uassoc($array, $excludes, $callback_value, $callback_key);
+
+ }
+
+ /**
+ * ### Computes the intersection of arrays using values for comparison
+ *
+ * Returns an array containing all the values of an array that are present in all the arguments.
+ * Note that keys are preserved.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray $array
+ * The array with main values to check.
+ *
+ * @param array ...$arrays [optional]
+ * An array to compare values against.
+ *
+ *
+ * @return TArray The filtered array.
+ *
+ * @note Two elements are considered equal if and only if (string) $elem1 === (string) $elem2.
+ * In words: when the string representation is the same.
+ */
+ public static function intersect (array $array, array ...$arrays):array {
+
+ /** @var TArray */
+ return array_intersect($array, ...$arrays);
+
+ }
+
+ /**
+ * ### Computes the intersection of arrays using values for comparison by using a callback for data comparison
+ *
+ * Computes the intersection of arrays, compares data by a callback function.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ * @template TCompareArray of array
+ *
+ * @param TArray $array
+ *
+ * @return TArray Arrays containing all the entries from $array that are present in any of the other arrays.
+ *
+ * @caution Returning non-integer values from the comparison function, such as float, will result in an internal
+ * cast to int of the callback's return value.
+ * So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as
+ * equal.
+ * @note Two elements are considered equal if and only if (string) $elem1 === (string) $elem2.
+ * In words: when the string representation is the same.
+ */
+ public static function intersectUsing (array $array, array $excludes, callable $callback):array {
+
+ /** @var TArray */
+ return array_uintersect($array, $excludes, $callback);
+
+ }
+
+ /**
+ * ### Computes the intersection of arrays using keys for comparison
+ *
+ * Returns an array containing all the entries of an array which have keys that are present in all the arguments.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray $array
+ * The array with main values to check.
+ *
+ * @param array ...$arrays [optional]
+ * An array to compare values against.
+ *
+ *
+ * @return TArray The filtered array.
+ */
+ public static function intersectKey (array $array, array ...$arrays):array {
+
+ return array_intersect_key($array, ...$arrays);
+
+ }
+
+ /**
+ * ### Computes the intersection of arrays using keys for comparison by using a callback for data comparison
+ *
+ * Returns an array containing all the values of an array which have matching keys that are present in all the
+ * arguments.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ * @template TCompareArray of array
+ *
+ * @param TArray $array
+ *
+ * @return TArray An array containing all the entries from $array that are present in any of the other arrays.
+ *
+ * @caution Returning non-integer values from the comparison function, such as float, will result in an internal
+ * cast to int of the callback's return value.
+ * So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as
+ * equal.
+ */
+ public static function intersectUsingKey (array $array, array $excludes, callable $callback):array {
+
+ /** @var TArray */
+ return array_intersect_ukey($array, $excludes, $callback);
+
+ }
+
+ /**
+ * ### Computes the intersection of arrays with additional index check
+ *
+ * Returns an array containing all the values of an array that are present in all the arguments.
+ * Note that the keys are also used in the comparison, unlike in Arr#intersect().
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ *
+ * @param TArray $array
+ * The array with main values to check.
+ *
+ * @param array ...$arrays [optional]
+ * An array to compare values against.
+ *
+ *
+ * @return TArray The filtered array.
+ *
+ * @note The two values from the key → value pairs are considered equal only if (string) $elem1 === (string) $elem2.
+ * In other words, a strict type check is executed, so the string representation must be the same.
+ */
+ public static function intersectAssoc (array $array, array ...$arrays):array {
+
+ /** @var TArray */
+ return array_intersect_assoc($array, ...$arrays);
+
+ }
+
+ /**
+ * ### Computes the intersection of arrays with additional index check by using a callback for value comparison
+ *
+ * Computes the intersection of arrays with additional index check, compares data by a callback function.
+ * Note that the keys are used in the comparison unlike in Arr#intersectFunc().
+ * The data is compared by using a callback function.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ * @template TCompareArray of array
+ *
+ * @param TArray $array
+ *
+ * @return TArray An array containing all the entries from $array that are present in any of the other arrays.
+ *
+ * @caution Returning non-integer values from the comparison function, such as float, will result in an internal
+ * cast to int of the callback's return value.
+ * So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as
+ * equal.
+ */
+ public static function intersectAssocUsingValue (array $array, array $excludes, callable $callback):array {
+
+ /** @var TArray */
+ return array_uintersect_assoc($array, $excludes, $callback);
+
+ }
+
+ /**
+ * ### Computes the intersection of arrays with additional index check by using a callback for key comparison
+ *
+ * Computes the intersection of arrays with additional index check, compares data and indexes by separate
+ * callback functions.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ * @template TCompareArray of array
+ *
+ * @param TArray $array
+ *
+ * @return TArray An array containing all the entries from $array that are present in any of the other arrays.
+ *
+ * @caution Returning non-integer values from the comparison function, such as float, will result in an internal
+ * cast to int of the callback's return value.
+ * So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as
+ * equal.
+ * @note The comparison function must return an integer less than, equal to, or greater than zero if
+ * the first argument is considered to be respectively less than, equal to, or greater than the second.
+ */
+ public static function intersectAssocUsingKey (array $array, array $excludes, callable $callback):array {
+
+ /** @var TArray */
+ return array_intersect_uassoc($array, $excludes, $callback);
+
+ }
+
+ /**
+ * ### Computes the intersection of arrays with additional index check by using a callback for key-value comparison
+ *
+ * Computes the intersection of arrays with additional index check, compares data and indexes by separate
+ * callback functions.
+ * @since 1.0.0
+ *
+ * @template TArray of array
+ * @template TCompareArray of array
+ *
+ * @param TArray $array
+ *
+ * @return TArray An array containing all the entries from $array that are present in any of the other
+ * arrays.
+ *
+ * @caution Returning non-integer values from the comparison function, such as float, will result in an internal
+ * cast to int of the callback's return value.
+ * So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as
+ * equal.
+ * @note The comparison function must return an integer less than, equal to, or greater than zero if
+ * the first argument is considered to be respectively less than, equal to, or greater than the second.
+ */
+ public static function intersectAssocUsingKeyValue (array $array, array $excludes, callable $callback_value, callable $callback_key):array {
+
+ /** @var TArray */
+ return array_uintersect_uassoc($array, $excludes, $callback_value, $callback_key);
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Arr/Structure.php b/src/Arr/Structure.php
new file mode 100644
index 0000000..d040866
--- /dev/null
+++ b/src/Arr/Structure.php
@@ -0,0 +1,340 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.3
+ * @package Runtime
+ */
+
+namespace FireHub\Runtime\Arr;
+
+use FireHub\Core\Boundary\Runtime\NativeRuntime;
+use FireHub\Runtime\Exception\ {
+ InvalidArrayLengthException, InvalidChunkLengthException, InvalidRangeStepException
+};
+
+use function array_chunk;
+use function array_fill;
+use function array_fill_keys;
+use function array_pad;
+use function array_slice;
+use function array_splice;
+use function range;
+
+/**
+ * ### PHP Array Runtime Wrapper Utility - Transform
+ *
+ * The Structure class provides lightweight, deterministic wrappers for creating and restructuring PHP arrays.
+ *
+ * It contains common runtime operations for defining array shapes, combining arrays, filling arrays with values,
+ * padding arrays, extracting segments, replacing portions, and generating sequential value ranges while preserving
+ * native PHP behavior and performance.
+ *
+ * This component is part of the FireHub Runtime layer and provides a consistent API for array structure operations
+ * without introducing domain logic, framework coupling, or additional abstraction overhead.
+ * @since 1.0.0
+ */
+final class Structure extends NativeRuntime {
+
+ /**
+ * ### Split an array into chunks
+ *
+ * Chunks an array into arrays with $length elements.
+ *
+ * The last chunk may contain less than $length elements.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array
+ * The array.
+ *
+ * @param positive-int $length
+ * The size of each chunk.
+ * Must be greater than zero.
+ *
+ * @param bool $preserve_keys [optional]
+ * When set to true, keys will be preserved.
+ *
+ * Default is false that will reindex the chunk numerically.
+ *
+ *
+ * @throws \FireHub\Runtime\Exception\InvalidChunkLengthException If the length is less than 1.
+ *
+ * @return ($preserve_keys is true ? list> : list>) Multidimensional numerically
+ * indexed array, starting with zero, with each dimension contains $length elements.
+ */
+ public static function chunk (array $array, int $length, bool $preserve_keys = false):array {
+
+ if ($length < 1) {
+ throw new InvalidChunkLengthException(
+ 'The length of each chunk must be a positive integer.',
+ [
+ 'length' => $length,
+ 'minimum' => 1,
+ ]
+ );
+ }
+
+ return array_chunk($array, $length, $preserve_keys);
+
+ }
+
+ /**
+ * ### Fill an array with values
+ *
+ * Fills an array with $length entries of the value for the $value parameter, keys starting at the $start_index
+ * parameter.
+ * @since 1.0.0
+ *
+ * @template TValue
+ *
+ * @param TValue $value
+ * Value to use for filling.
+ *
+ * @param int $start_index
+ * The first index of the returned array.
+ *
+ * @param positive-int $length
+ * Number of elements to insert. Must be greater than or equal to zero.
+ *
+ *
+ * @throws \FireHub\Runtime\Exception\InvalidArrayLengthException If $length is invalid.
+ *
+ * @return array Filled array.
+ */
+ public static function fill (mixed $value, int $start_index, int $length):array {
+
+ if ($length < 1) {
+ throw new InvalidArrayLengthException(
+ 'The array length must be greater than zero.',
+ [
+ 'length' => $length,
+ 'minimum' => 1,
+ ]
+ );
+ }
+
+ return array_fill($start_index, $length, $value);
+
+ }
+
+ /**
+ * ### Fill an array with values, specifying keys
+ *
+ * Fills an array with the value of the $value parameter, using the values of the $keys array as keys.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $keys
+ * Array of values that will be used as keys.
+ *
+ * Illegal values for a key will be converted to string.
+ *
+ * @param TValue $value
+ * Value to use for filling.
+ *
+ *
+ * @return array The filled array.
+ */
+ public static function fillKeys (array $keys, mixed $value):array {
+
+ return array_fill_keys($keys, $value);
+
+ }
+
+ /**
+ * ### Pad array to the specified length with a value
+ *
+ * Returns a copy of the array padded to the size specified by $length with $value.
+ * If the length is positive, then the array is padded on the right if it is negative, then on the left.
+ * If the absolute value of a length is less than or equal to the length of the array, then no padding takes place.
+ * @since 1.0.0
+ *
+ * @template TValue
+ * @template TPaddedValue
+ *
+ * @param array $array
+ * Initial array of values to pad.
+ *
+ * @param int $length
+ * New size of the array.
+ * If the length is positive, then the array is padded on the right if it is negative, then on the left.
+ *
+ * If the absolute value of a length is less than or equal to the length of the array, then no padding takes place.
+ *
+ *
+ * @param TPaddedValue $value
+ * Value to pad if input is less than length.
+ *
+ *
+ * @return array A copy of the input padded to the size specified by $length with
+ * value $value.
+ *
+ * @caution Keys can be re-numbered.
+ */
+ public static function pad (array $array, int $length, mixed $value):array {
+
+ return array_pad($array, $length, $value);
+
+ }
+
+ /**
+ * ### Extract a slice of the array
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array
+ * The input array.
+ *
+ * @param int $offset
+ * If the offset is non-negative, the sequence will start at that offset in the array.
+ *
+ * If the offset is negative, the sequence will start that far from the end of the array.
+ *
+ * @param null|int $length [optional]
+ * If length is given and is positive, then the sequence will have that many elements in it.
+ *
+ * If length is given and is negative, then the sequence will stop that many elements from the end of the array.
+ *
+ * If it is omitted, then the sequence will have everything from offset up until the end of the array.
+ *
+ * @param bool $preserve_keys [optional]
+ * Note that array_slice will reorder and reset the array indices by default.
+ *
+ * You can change this behavior by setting preserve_keys to true.
+ *
+ *
+ * @return ( $preserve_keys is true
+ * ? array
+ * : ($array is list
+ * ? list
+ * : array)
+ * ) Converted value.
+ *
+ * @note Named keys will always retain their name.
+ */
+ public static function slice (array $array, int $offset, ?int $length = null, bool $preserve_keys = false):array {
+
+ return array_slice($array, $offset, $length, $preserve_keys);
+
+ }
+
+ /**
+ * ### Remove a portion of the array and replace it with something else
+ *
+ * Removes the elements designated by offset and length from the parameter $array and replaces them with the
+ * elements of the replacement array, if supplied.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ * @template TReplacedValue
+ *
+ * @param array &$array
+ * Array to splice.
+ *
+ * @param int $offset
+ * If the offset is positive, then the start of the removed portion is at that offset from the beginning of the
+ * input array.
+ *
+ * If the offset is negative, then it starts that far from the end of the input array.
+ *
+ * @param null|int $length [optional]
+ * If the length is omitted, removes everything from offset to the end of the array.
+ *
+ * If the length is specified and is positive, then that many elements will be removed.
+ *
+ * If the length is specified and is negative, then the end of the removed portion will be that many elements from
+ * the end of the array.
+ *
+ * @param TReplacedValue $replacement [optional]
+ * If a replacement array is specified, then the removed elements will be replaced with elements from this array.
+ *
+ * If offset and length are such that nothing is removed, then the elements from the replacement array or array
+ * are inserted in the place specified by the offset.
+ *
+ * Keys in a replacement array aren't preserved.
+ *
+ * @phpstan-param-out ($array is list ? list : array) $array
+ *
+ * @return array Spliced array.
+ *
+ * @note Numerical keys in an array aren't preserved.
+ *
+ * @note If the replacement is not an array, it will be typecast to one (in other words (array) $replacement).
+ *
+ * This may result in unexpected behavior when using an object or null replacement.
+ */
+ public static function splice (array &$array, int $offset, ?int $length = null, mixed $replacement = []):array {
+
+ return array_splice($array, $offset, $length, $replacement); // @phpstan-ignore paramOut.type
+
+ }
+
+ /**
+ * ### Create an array containing a range of elements
+ * @since 1.0.0
+ *
+ * @template TStart of int|float|string
+ * @template TEnd of int|float|string
+ * @template TStep of int|float
+ *
+ * @param TStart $start
+ * First value of the sequence.
+ *
+ * @param TEnd $end
+ * The sequence is ended upon reaching the end value.
+ *
+ * @param TStep $step [optional]
+ * If a step value is given, it will be used as the increment between elements in the sequence.
+ *
+ * Step should be given as a positive number. If not specified, a step will default to 1.
+ *
+ *
+ * @throws \FireHub\Runtime\Exception\InvalidRangeStepException If the step is zero or range step must be greater
+ * than zero when the start is greater than the end.
+ *
+ * @return (TStart is string
+ * ? array
+ * : (TEnd is string
+ * ? array
+ * : (TStart is float
+ * ? array
+ * : (TEnd is float
+ * ? array
+ * : (TStep is float
+ * ? array
+ * : array))))
+ * ) Sequence of elements as an array with the first element being start going up to end, with each value of the
+ * sequence being step values apart.
+ *
+ * @note Character sequence values are limited to a length of one.
+ *
+ * If a length greater than one is entered only the first character is used.
+ */
+ public static function range (int|float|string $start, int|float|string $end, int|float $step = 1):array {
+
+ if ($step === 0) throw new InvalidRangeStepException('The range step must not be zero.');
+
+ if ($end > $start && $step < 0) {
+ throw new InvalidRangeStepException(
+ 'The range step must be greater than zero when the start is greater than the end.'
+ );
+ }
+
+ return range($start, $end, $step);
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Arr/Transform.php b/src/Arr/Transform.php
new file mode 100644
index 0000000..5f0201d
--- /dev/null
+++ b/src/Arr/Transform.php
@@ -0,0 +1,342 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Runtime
+ */
+
+namespace FireHub\Runtime\Arr;
+
+use FireHub\Core\Boundary\Runtime\NativeRuntime;
+use FireHub\Runtime\Type\Arr\ {
+ KeyCase, UniqueMode
+};
+
+use const ARRAY_FILTER_USE_BOTH;
+
+use function array_change_key_case;
+use function array_filter;
+use function array_flip;
+use function array_map;
+use function array_reduce;
+use function array_reverse;
+use function array_unique;
+use function array_walk;
+use function array_walk_recursive;
+
+/**
+ * ### PHP Array Runtime Wrapper Utility - Transform
+ *
+ * The Transform class provides lightweight, deterministic wrappers for transforming and modifying PHP arrays.
+ *
+ * It contains common runtime operations for changing array structure, replacing values, mapping data, filtering
+ * elements, and producing transformed array representations while preserving native PHP behavior and performance.
+ *
+ * This component is part of the FireHub Runtime layer and provides a consistent API for array transformation
+ * operations without introducing domain logic, framework coupling, or additional abstraction overhead.
+ * @since 1.0.0
+ */
+final class Transform extends NativeRuntime {
+
+ /**
+ * ### Iteratively reduce the array to a single value using a callback function
+ *
+ * Iteratively applies the $callback function to the elements of the $array to reduce the array to a single value.
+ * @since 1.0.0
+ *
+ * @template TValue
+ * @template TReturn
+ *
+ * @param array $array
+ * If the optional initial is available, it will be used at the beginning of the process, or as a final result in
+ * case the array is empty.
+ *
+ *
+ * @return ($initial is null ? null|TReturn : TReturn) Resulting value or null if the array is empty and the
+ * initial is not passed.
+ */
+ public static function reduce (array $array, callable $callback, mixed $initial = null):mixed {
+
+ return func_num_args() < 3
+ ? array_reduce($array, $callback)
+ : array_reduce($array, $callback, $initial);
+
+ }
+
+ /**
+ * ### Changes the case of all keys in an array
+ *
+ * Returns an array with all keys from an array lowercased or uppercased.
+ * Numbered indices are left as is.
+ * @since 1.0.0
+ *
+ * @uses \FireHub\Runtime\Type\Arr\KeyCase::LOWER As default parameter.
+ *
+ * @template TValue
+ *
+ * @param array $array
+ *
+ * @return array An array with its keys lower or uppercased.
+ */
+ public static function keyCase (array $array, KeyCase $style = KeyCase::LOWER):array {
+
+ return array_change_key_case($array, $style->value);
+
+ }
+
+ /**
+ * ### Filters elements of an array using a callback function
+ *
+ * Iterates over each value in the $array, passing them to the $callback function.
+ *
+ * If the $callback function returns true, the current value from an $array is returned into the result array.
+ *
+ * Array keys are preserved and may result in gaps if the $array was indexed.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array
+ * The callback function to use.
+ *
+ * If no callback is supplied, all empty and false entries of an array will be removed.
+ *
+ *
+ * @return array Filtered array.
+ *
+ * @note The result array can be re-indexed using the Arr#values() function.
+ * @note If no callback is provided, all falsey values are removed.
+ * @caution If the array is changed from the callback function (for example, an element added, deleted, or unset),
+ * then the behavior of this function is undefined.
+ */
+ public static function filter (array $array, ?callable $callback = null):array {
+
+ return array_filter(
+ $array,
+ $callback ?? static fn(mixed $value): bool => (bool) $value,
+ ARRAY_FILTER_USE_BOTH
+ );
+
+ }
+
+
+ /**
+ * ### Exchanges all keys with their associated values in an array
+ *
+ * Returns an array in flip order; in other words, keys from an $array become values, and values from an $array
+ * become keys.
+ *
+ * Note that the values of $array need to be valid keys; in other words, they need to be either int or string.
+ *
+ * A warning will be emitted if a value has the wrong type, and the key/value pair in question will not be
+ * included in the result.
+ *
+ * If a value has several occurrences, the latest key will be used as its value, and all others will be lost.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue of array-key
+ *
+ * @param array $array
+ * The array to flip.
+ *
+ *
+ * @return array The flipped array.
+ */
+ public static function flip (array $array):array {
+
+ return array_flip($array);
+
+ }
+
+ /**
+ * ### Applies the callback to the elements of the given array
+ *
+ * Returns an array containing the results of applying the $callback to the corresponding value of an $array
+ * used as arguments for the callback.
+ *
+ * The number of parameters that the $callback function accepts should match the number of arrays passed to
+ * Arr#map(). Excess input arrays are ignored.
+ *
+ * An ArgumentCountError is thrown if an insufficient number of arguments is provided.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ * @template TReturn
+ *
+ * @param array $array
+ * Array to run through the callback function.
+ *
+ * @param callable(TValue):TReturn $callback
+ * Callback function to run for each element in each array.
+ *
+ * Null can be passed as a value to $callback to perform a zip operation on multiple arrays.
+ *
+ * If only an array is provided, Arr#map() will return the input array.
+ *
+ *
+ * @return ($array is list
+ * ? list
+ * : array
+ * ) Returns an array containing the results of applying the callback function to the corresponding value of array.
+ */
+ public static function map (array $array, callable $callback):array {
+
+ return array_map($callback, $array);
+
+ }
+
+ /**
+ * ### Apply a user function to every member of an array
+ *
+ * Applies the user-defined callback function to each element of the array $array.
+ *
+ * Method is not affected by the internal array pointer of an array.
+ *
+ * Method will walk through the entire array regardless of pointer position.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ * @template TReturn
+ *
+ * @param array &$array
+ * Typically, the function name takes on two parameters.
+ *
+ * The array parameter's value is the first, and the key/index second.
+ *
+ * If a function name needs to be working with the actual values of the array, specify the first parameter of the
+ * function name as a reference.
+ *
+ * Then, any changes made to those elements will be made in the original array itself.
+ *
+ * Users may not change the array itself from the callback function, for example, add/delete elements, unset
+ * elements, and so on.
+ *
+ * @phpstan-param-out array $array
+ *
+ * @return true True on success.
+ */
+ public static function walk (array &$array, callable $callback):true {
+
+ return array_walk($array, $callback); // @phpstan-ignore paramOut.type
+
+ }
+
+ /**
+ * ### Apply a user function recursively to every member of an array
+ *
+ * Applies the user-defined callback function to each element of the array.
+ *
+ * This function will recurse into deeper arrays.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ * @template TReturn
+ *
+ * @param array &$array
+ * Typically, the function name takes on two parameters.
+ *
+ * The array parameter's value is the first, and the key/index second.
+ *
+ * If a function name needs to be working with the actual values of the array, specify the first parameter of the
+ * function name as a reference.
+ *
+ * Then, any changes made to those elements will be made in the original array itself.
+ *
+ * Users may not change the array itself from the callback function.
+ *
+ * For example, Add/delete elements, unset elements, and so on.
+ *
+ * @phpstan-param-out array $array
+ *
+ * @return true True on success.
+ */
+ public static function walkRecursive (array &$array, callable $callback):true {
+
+ return array_walk_recursive($array, $callback); // @phpstan-ignore paramOut.type
+
+ }
+
+ /**
+ * ### Reverse the order of array items
+ *
+ * Takes an input array and returns a new array with the order of the elements reversed.
+ * @since 1.0.0
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array
+ * Array to reverse.
+ *
+ * @param bool $preserve_keys [optional]
+ * Whether you want to preserve keys from an original array or not.
+ *
+ * Non-numeric keys aren't affected by this setting and will always be preserved.
+ *
+ *
+ * @return ($preserve_keys is true ? array : list) The reversed array.
+ */
+ public static function reverse (array $array, bool $preserve_keys = false):array {
+
+ return array_reverse($array, $preserve_keys);
+
+ }
+
+ /**
+ * ### Removes duplicate values from an array
+ *
+ * Takes an input array and returns a new array without duplicate values.
+ * @since 1.0.0
+ *
+ * @uses \FireHub\Runtime\Type\Arr\UniqueMode::REGULAR As default compare enum.
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @param array $array