Skip to content

Arr.md

Latest commit

 

History

History
287 lines (213 loc) · 6.84 KB

Arr.md

File metadata and controls

287 lines (213 loc) · 6.84 KB

Array Utilities Documentation

The Arr class provides a set of powerful utility methods for working with arrays in PHP. It's designed to offer a clean and expressive API for common array operations, inspired by Laravel's collection methods.

Available Methods

  • where() - Filter items by the given key value pair
  • whereIn() - Filter items by the given key value pairs
  • whereNot() - Filter items by excluding the given key value pair
  • contains() - Check if an array contains a given key value pair
  • first() - Get the first element from the array passing the given truth test
  • firstWhere() - Get the first element from the array matching the given key value pair
  • last() - Get the last element from the array
  • filter() - Filter the array using the given callback
  • map() - Map over each of the items in the array
  • each() - Iterate over each item in the array and apply a callback
  • get() - Get an item from an array using "dot" notation

where()

Filter items in an array by a given key-value pair. This method supports various comparison operators and callback functions.

use Avmg\PhpSimpleUtilities\Arr;

$array = [
    ['name' => 'John', 'age' => 25],
    ['name' => 'Jane', 'age' => 30],
    ['name' => 'Bob', 'age' => 25]
];

// Using simple equality
$result = Arr::where($array, 'age', 25);
// Returns: [['name' => 'John', 'age' => 25], ['name' => 'Bob', 'age' => 25]]

// Using comparison operator
$result = Arr::where($array, 'age', '>=', 30);
// Returns: [['name' => 'Jane', 'age' => 30]]

// Using callback
$result = Arr::where($array, function($value, $key) {
    return $value['age'] < 30;
});

Supported operators: =, ==, !=, <>, <, >, <=, >=, ===, !==

whereIn()

Filter items by checking if a key's value exists in a given array of values.

$array = [
    ['name' => 'John', 'role' => 'admin'],
    ['name' => 'Jane', 'role' => 'user'],
    ['name' => 'Bob', 'role' => 'admin']
];

$result = Arr::whereIn($array, 'role', ['admin']);
// Returns: [['name' => 'John', 'role' => 'admin'], ['name' => 'Bob', 'role' => 'admin']]

whereNot()

Filter items by excluding those with a specific key-value pair.

$array = [
    ['name' => 'John', 'role' => 'admin'],
    ['name' => 'Jane', 'role' => 'user'],
    ['name' => 'Bob', 'role' => 'admin']
];

$result = Arr::whereNot($array, 'role', 'admin');
// Returns: [['name' => 'Jane', 'role' => 'user']]

contains()

Check if an array contains a value, key-value pair, or matches a callback condition.

// Array of items
$array = [
    ['name' => 'John', 'age' => 25],
    ['name' => 'Jane', 'age' => 30],
    ['name' => 'Bob', 'age' => 25]
];

// Check for key-value pair
$result = Arr::contains($array, 'age', 25);
// Returns: true

// Check with callback
$result = Arr::contains($array, function($value) {
    return $value['age'] > 30;
});
// Returns: false

// Check for simple value
$result = Arr::contains($array, 'Bob');
// Returns: true

first()

Get the first element from the array that passes a given truth test. If no callback is provided, returns the first element.

$array = [1, 2, 3, 4, 5];

// Get first element
$result = Arr::first($array);
// Returns: 1

// Get first element matching condition
$result = Arr::first($array, function($value) {
    return $value > 3;
});
// Returns: 4

// With default value if nothing matches
$result = Arr::first($array, function($value) {
    return $value > 10;
}, 'default');
// Returns: 'default'

firstWhere()

Get the first element from the array that matches the given key-value pair.

$array = [
    ['name' => 'John', 'age' => 25],
    ['name' => 'Jane', 'age' => 30],
    ['name' => 'Bob', 'age' => 25]
];

// Using key/value pair
$result = Arr::firstWhere($array, 'name', 'Bob');
// Returns: ['name' => 'Bob', 'age' => 25]

// Using comparison operator
$result = Arr::firstWhere($array, 'age', '>=', 18);
// Returns: ['name' => 'John', 'age' => 25]

// Using truthy check
$result = Arr::firstWhere($array, 'age');
// Returns: ['name' => 'John', 'age' => 25]

// Using callback, You can use the normal first method for this instead :) 
$result = Arr::firstWhere($array, fn($item) => $item['age'] > 18);
// Returns: ['name' => 'John', 'age' => 25]

last()

Get the last element from the array that passes a given truth test. If no callback is provided, returns the last element.

$array = [1, 2, 3, 4, 5];

// Get last element
$result = Arr::last($array);
// Returns: 5

// Get last element matching condition
$result = Arr::last($array, function($value) {
    return $value < 4;
});
// Returns: 3

// With default value if nothing matches
$result = Arr::last($array, function($value) {
    return $value > 10;
}, 'default');
// Returns: 'default'

filter()

Filter the array using the given callback function.

$array = [1, 2, 3, 4, 5];

$result = Arr::filter($array, function($value, $key) {
    return $value > 3;
});
// Returns: [4, 5]

// Without callback (removes falsy values)
$array = [0, 1, '', null, false, 'hello'];
$result = Arr::filter($array);
// Returns: [1, 'hello']

map()

Map over each item in the array using a callback function. Preserves the original array keys.

$array = ['a' => 1, 'b' => 2, 'c' => 3];

$result = Arr::map($array, function($value, $key) {
    return $value * 2;
});
// Returns: ['a' => 2, 'b' => 4, 'c' => 6]

each()

Iterate over each item in the array and apply a callback function.

$array = ['a' => 1, 'b' => 2, 'c' => 3];

Arr::each($array, function($value, $key) {
    echo "$key: $value\n";
});

// Outputs:
// a: 1
// b: 2
// c: 3

get()

Retrieve a value from a deeply nested array or object using dot notation.

$array = [
    'user' => [
        'profile' => [
            'name' => 'John',
        ],
        'settings' => null,
    ],
];

// Retrieve a value using dot notation
$result = Arr::get($array, 'user.profile.name');
// Returns: 'John'

// Retrieve a value with a default if not found
$result = Arr::get($array, 'user.profile.age', 30);
// Returns: 30

// Retrieve a value where the key path does not exist
$result = Arr::get($array, 'user.settings.language', 'English');
// Returns: 'English'

Note: This method can also retrieve data from objects or a combination of arrays and objects when navigating the keys.

Advanced Features

Dot Notation

The utility supports dot notation for accessing nested array values:

$array = [
    'user' => [
        'profile' => [
            'name' => 'John'
        ]
    ]
];

$result = Arr::where($array, 'user.profile.name', 'John');

Closure Support

Many methods support closure values for dynamic evaluation:

$default = function() {
    return computeExpensiveDefaultValue();
};

$result = Arr::first($array, null, $default);