diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..115d815 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,10 @@ +version: 2 +updates: +- package-ecosystem: "composer" + directory: "/" + schedule: + interval: daily +- package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: daily diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a22124e..788f3df 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -11,13 +11,13 @@ jobs: strategy: matrix: operating-system: [ubuntu-latest] - php-versions: ['5.3', '5.4', '5.5', '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2'] + php-versions: ['7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3', '8.4', '8.5'] runs-on: ${{ matrix.operating-system }} steps: - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v7 - name: Install PHP uses: shivammathur/setup-php@v2 diff --git a/.mddoc.xml.dist b/.mddoc.xml.dist new file mode 100644 index 0000000..0e4deb2 --- /dev/null +++ b/.mddoc.xml.dist @@ -0,0 +1,24 @@ + + + +
+ + + + + A collection of global `array_*` functions appending to the native PHP set. + +
+ +
+ +
+ +
+ +
+ +
+
+ + diff --git a/README.md b/README.md index 3513a2b..95ccfc8 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,108 @@ # Quorum Array Functions -[![Build Status](https://travis-ci.org/QuorumCollection/ArrayFunctions.svg?branch=master)](https://travis-ci.org/QuorumCollection/ArrayFunctions) +[![Latest Stable Version](https://poser.pugx.org/quorum/array-functions/version)](https://packagist.org/packages/quorum/array-functions) +[![License](https://poser.pugx.org/quorum/array-functions/license)](https://packagist.org/packages/quorum/array-functions) +[![ci.yml](https://github.com/QuorumCollection/ArrayFunctions/actions/workflows/ci.yml/badge.svg)](https://github.com/QuorumCollection/ArrayFunctions/actions/workflows/ci.yml) + A collection of global `array_*` functions appending to the native PHP set. -- `array_flatten( array $array, $allow_duplicates = false )` - - Given an array, find all the values recursively. -- `array_blend( array $arrays, array $keys = null )` - - Given an array of arrays, merges the array's children together. -- `array_key_array( array $arrays, $key )` - - Given an array of similarly keyed arrays, returns an array of only the values of the key. -- `array_keys_array( array $arrays, $keys )` - - Given an array of similarly keyed arrays, returns an array of only the selected keys. -- `array_key_refill( array $array, $keys, $fill = array() )` - - Given a keyed array, fills any missing values. +## Requirements + +- **php**: >=7.2.0 + +## Installing + +Install the latest version with: + +```bash +composer require 'quorum/array-functions' +``` + +## Array Functions + +### Function: \array_flatten + +```php +function array_flatten(array $array [, $allow_duplicates = false]) +``` + +##### Parameters: + +- ***array*** `$array` - The Array to be Flattened +- ***bool*** `$allow_duplicates` - Should the array allow duplicates + +##### Returns: + +- ***array*** - The resulting array or NULL on failure + +Given an array, find all the values recursively. + +### Function: \array_blend + +```php +function array_blend(array $arrays [, array $keys = null]) +``` + +##### Parameters: + +- ***array*** `$arrays` - An array of arrays. +- ***array*** | ***null*** `$keys` - The merged array. + +##### Returns: + +- ***array*** - The resulting blended array + +Given an array of arrays, merges the array's children together. + +### Function: \array_key_array + +```php +function array_key_array(array $arrays, $key) +``` + +##### Parameters: + +- ***array*** `$arrays` - An array of similarly keyed arrays +- ***int*** | ***string*** `$key` - The desired key + +##### Returns: + +- ***array*** - The flattened array + +Given an array of similarly keyed arrays, returns an array of only the values of the key. + +### Function: \array_keys_array + +```php +function array_keys_array(array $arrays, $keys) +``` + +##### Parameters: + +- ***array*** `$arrays` - An array of similarly keyed arrays +- ***array*** | ***int*** | ***string*** `$keys` - The key or array of keys to return + +##### Returns: + +- ***array*** - The array of arrays with just the selected keys + +Given an array of similarly keyed arrays, returns an array of only the selected keys. + +### Function: \array_key_refill + +```php +function array_key_refill(array $array, array $keys [, $fill = array()]) +``` + +##### Parameters: + +- ***array*** `$array` - A Keyed array +- ***array*** `$keys` - The keys that must exist +- ***mixed*** `$fill` - The desired value to fill with + +##### Returns: + +- ***array*** + +Given a keyed array, fills any missing values. diff --git a/composer.json b/composer.json index dda72f0..967729e 100644 --- a/composer.json +++ b/composer.json @@ -21,10 +21,10 @@ } ], "require": { - "php" : ">=5.3.0" + "php" : ">=7.2.0" }, "require-dev": { - "phpunit/phpunit": "~4.8|~9" + "phpunit/phpunit": "~8|~9|~11" }, "autoload" : { "files": ["src/array.php"] diff --git a/test/ArrayFunctionsTest.php b/test/ArrayFunctionsTest.php index 7ebb6dd..010b236 100644 --- a/test/ArrayFunctionsTest.php +++ b/test/ArrayFunctionsTest.php @@ -18,8 +18,8 @@ public function testArrayFlatten() { array_flatten(array( 'bbq' => array( 'soda' => array( 1, 2, 4, 'fish fry' ), - 3 - ) + 3, + ), )) ); @@ -28,27 +28,185 @@ public function testArrayFlatten() { array_flatten(array( 'bbq' => array( 'soda' => array( 1, 2, 4, 'fish fry' ), - 3 - ) + 3, + ), ), true) ); - } public function testArrayBlend() { - //@todo: I'm not entirely sure how to test this + // Test blending arrays without specifying keys + $arrays = array( + 'fruits' => array( 'apple', 'banana', 'cherry' ), + 'vegetables' => array( 'carrot', 'broccoli', 'spinach' ), + 'meats' => array( 'chicken', 'beef', 'pork' ), + ); + + $expected = array( 'apple', 'banana', 'cherry', 'carrot', 'broccoli', 'spinach', 'chicken', 'beef', 'pork' ); + $this->assertEquals($expected, array_blend($arrays)); + + // Test blending arrays with specific keys + $keys = array( 'fruits', 'meats' ); + $expected = array( 'apple', 'banana', 'cherry', 'chicken', 'beef', 'pork' ); + $this->assertEquals($expected, array_blend($arrays, $keys)); + + // Test with empty arrays + $arrays = array( + 'fruits' => array(), + 'vegetables' => array( 'carrot', 'broccoli' ), + 'empty' => array(), + ); + + $expected = array( 'carrot', 'broccoli' ); + $this->assertEquals($expected, array_blend($arrays)); + + // Test with non-array values (should be skipped) + $arrays = array( + 'fruits' => array( 'apple', 'banana' ), + 'number' => 42, + 'vegetables' => array( 'carrot' ), + ); + + $expected = array( 'apple', 'banana', 'carrot' ); + $this->assertEquals($expected, array_blend($arrays)); } public function testArrayKeyArray() { + // Test with numeric keys + $arrays = array( + array( 'id' => 1, 'name' => 'John', 'role' => 'Developer' ), + array( 'id' => 2, 'name' => 'Jane', 'role' => 'Designer' ), + array( 'id' => 3, 'name' => 'Bob', 'role' => 'Manager' ), + ); + $expected = array( 1, 2, 3 ); + $this->assertEquals($expected, array_key_array($arrays, 'id')); + + // Test with string keys + $expected = array( 'John', 'Jane', 'Bob' ); + $this->assertEquals($expected, array_key_array($arrays, 'name')); + + // Test with associative array keys + $arrays = array( + 'user1' => array( 'id' => 101, 'name' => 'Alice' ), + 'user2' => array( 'id' => 102, 'name' => 'Charlie' ), + 'user3' => array( 'id' => 103, 'name' => 'Dave' ), + ); + + $expected = array( 'user1' => 101, 'user2' => 102, 'user3' => 103 ); + $this->assertEquals($expected, array_key_array($arrays, 'id')); + + // Test with mixed content + $arrays = array( + array( 'id' => 201, 'data' => 'value1' ), + array( 'id' => 202, 'data' => array( 'nested' => 'value2' ) ), + array( 'id' => 203, 'data' => 42 ), + ); + + $expected = array( 'value1', array( 'nested' => 'value2' ), 42 ); + $this->assertEquals($expected, array_key_array($arrays, 'data')); } public function testArrayKeysArray() { + // Test with multiple keys + $arrays = array( + array( 'id' => 1, 'name' => 'John', 'role' => 'Developer', 'age' => 30 ), + array( 'id' => 2, 'name' => 'Jane', 'role' => 'Designer', 'age' => 28 ), + array( 'id' => 3, 'name' => 'Bob', 'role' => 'Manager', 'age' => 35 ), + ); + + $keys = array( 'id', 'name' ); + $expected = array( + array( 'id' => 1, 'name' => 'John' ), + array( 'id' => 2, 'name' => 'Jane' ), + array( 'id' => 3, 'name' => 'Bob' ), + ); + $this->assertEquals($expected, array_keys_array($arrays, $keys)); + // Test with a single key (passed as string) + $expected = array( + array( 'id' => 1 ), + array( 'id' => 2 ), + array( 'id' => 3 ), + ); + $this->assertEquals($expected, array_keys_array($arrays, 'id')); + + // Test with a single key (passed as array) + $this->assertEquals($expected, array_keys_array($arrays, array( 'id' ))); + + // Test with associative array keys + $arrays = array( + 'user1' => array( 'id' => 101, 'name' => 'Alice', 'dept' => 'Engineering' ), + 'user2' => array( 'id' => 102, 'name' => 'Charlie', 'dept' => 'Marketing' ), + 'user3' => array( 'id' => 103, 'name' => 'Dave', 'dept' => 'Sales' ), + ); + + $keys = array( 'id', 'dept' ); + $expected = array( + 'user1' => array( 'id' => 101, 'dept' => 'Engineering' ), + 'user2' => array( 'id' => 102, 'dept' => 'Marketing' ), + 'user3' => array( 'id' => 103, 'dept' => 'Sales' ), + ); + $this->assertEquals($expected, array_keys_array($arrays, $keys)); } public function testArrayKeyRefill() { + // Test with missing keys and default empty array fill + $array = array( + 'key1' => 'value1', + 'key3' => 'value3', + ); + + $keys = array( 'key1', 'key2', 'key3', 'key4' ); + $expected = array( + 'key1' => 'value1', + 'key2' => array(), + 'key3' => 'value3', + 'key4' => array(), + ); + + $this->assertEquals($expected, array_key_refill($array, $keys)); + + // Test with custom fill value (string) + $expected = array( + 'key1' => 'value1', + 'key2' => 'default', + 'key3' => 'value3', + 'key4' => 'default', + ); + + $this->assertEquals($expected, array_key_refill($array, $keys, 'default')); + + // Test with custom fill value (number) + $expected = array( + 'key1' => 'value1', + 'key2' => 0, + 'key3' => 'value3', + 'key4' => 0, + ); + + $this->assertEquals($expected, array_key_refill($array, $keys, 0)); + + // Test with custom fill value (array) + $fillArray = array( 'status' => 'empty' ); + $expected = array( + 'key1' => 'value1', + 'key2' => $fillArray, + 'key3' => 'value3', + 'key4' => $fillArray, + ); + + $this->assertEquals($expected, array_key_refill($array, $keys, $fillArray)); + + // Test with no missing keys + $array = array( + 'a' => 1, + 'b' => 2, + 'c' => 3, + ); + $keys = array( 'a', 'b', 'c' ); + $this->assertEquals($array, array_key_refill($array, $keys, 'unused')); }