https://github.com/bayfrontmedia/php-array-helpers
PHP helper class to provide useful array functions.
https://github.com/bayfrontmedia/php-array-helpers
array function helper helpers php
Last synced: 3 months ago
JSON representation
PHP helper class to provide useful array functions.
- Host: GitHub
- URL: https://github.com/bayfrontmedia/php-array-helpers
- Owner: bayfrontmedia
- License: mit
- Created: 2020-07-27T18:15:19.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-12-23T21:06:44.000Z (about 1 year ago)
- Last Synced: 2025-03-25T16:51:31.318Z (9 months ago)
- Topics: array, function, helper, helpers, php
- Language: PHP
- Homepage:
- Size: 34.2 KB
- Stars: 14
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
## PHP array helpers
PHP helper class to provide useful array functions.
- [License](#license)
- [Author](#author)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
## License
This project is open source and available under the [MIT License](LICENSE).
## Author
- [Bayfront Media homepage](https://www.bayfrontmedia.com?utm_source=github&utm_medium=direct)
- [Bayfront Media GitHub](https://github.com/bayfrontmedia)
## Requirements
* PHP `^8.0` (Tested up to `8.4`)
## Installation
```
composer require bayfrontmedia/php-array-helpers
```
## Usage
- [dot](#dot)
- [undot](#undot)
- [set](#set)
- [has](#has)
- [get](#get)
- [pluck](#pluck)
- [forget](#forget)
- [except](#except)
- [exceptValues](#exceptvalues)
- [only](#only)
- [missing](#missing)
- [isMissing](#ismissing)
- [multisort](#multisort)
- [numericMultisort](#numericmultisort)
- [renameKeys](#renamekeys)
- [order](#order)
- [getRandomItems](#getrandomitems)
- [query](#query)
- [getAnyValues](#getanyvalues)
- [hasAnyValues](#hasanyvalues)
- [hasAllValues](#hasallvalues)
- [ensureHas](#ensurehas)
### dot
**Description:**
Converts a multidimensional array to a single depth "dot" notation array, optionally prepending a string to each array key.
The key values will never be an array, even if empty. Empty arrays will be dropped.
**Parameters:**
- `$array` (array): Original array
- `$prepend = ''` (string): String to prepend
**Returns:**
- (array)
**Example:**
```
$array = [
'name' => [
'first_name' => 'John',
'last_name' => 'Doe'
],
'hobbies' => [ // This empty array will be dropped
]
];
$dot = Arr::dot($array);
```
### undot
**Description:**
Converts array in "dot" notation to a standard multidimensional array.
**Parameters:**
- `$array` (array): Array in "dot" notation
**Returns:**
- (array)
**Example:**
```
$array = [
'name.first_name' => 'John',
'name.last_name' => 'Doe'
];
$undot = Arr::undot($array);
```
### set
**Description:**
Set an array item to a given value using "dot" notation.
**Parameters:**
- `$array` (array): Original array
- `$key` (string): Key to set in "dot" notation
- `$value` (mixed): Value of key
**Returns:**
- (void)
**Example:**
```
$array = [
'name' => [
'first_name' => 'John',
'last_name' => 'Doe'
],
];
Arr::set($array, 'name.middle_name', 'Middle');
```
### has
**Description:**
Checks if array key exists and not null using "dot" notation.
**Parameters:**
- `$array` (array): Original array
- `$key` (string): Key to check in "dot" notation
**Returns:**
- (bool)
**Example:**
```
$array = [
'name' => [
'first_name' => 'John',
'last_name' => 'Doe'
],
];
if (Arr::has($array, 'name.first_name')) {
// Do something
}
```
### get
**Description:**
Get an item from an array using "dot" notation, returning an optional default value if not found.
**Parameters:**
- `$array` (array): Original array
- `$key` (string): Key to return in "dot" notation
- `$default = NULL` (mixed): Default value to return
**Returns:**
- (mixed)
**Example:**
```
$array = [
'name' => [
'first_name' => 'John',
'last_name' => 'Doe'
],
];
echo Arr::get($array, 'name.first_name');
```
### pluck
**Description:**
Returns an array of values for a given key from an array using "dot" notation.
**Parameters:**
- `$array` (array): Original array
- `$value` (string): Value to return in "dot" notation
- `$key = NULL` (string|null): Optionally how to key the returned array in "dot" notation
**Returns:**
- (array)
**Example:**
```
$array = [
[
'user_id' => 110,
'username' => 'John',
'active' => true
],
[
'user_id' => 111,
'username' => 'Jane',
'active' => true
]
];
$array = Arr::pluck($array, 'username', 'user_id');
```
### forget
**Description:**
Remove a single key, or an array of keys from a given array using "dot" notation.
**Parameters:**
- `$array` (array): Original array
- `$keys` (string|array): Key(s) to forget in "dot" notation
**Returns:**
- (void)
**Example:**
```
$array = [
'name' => [
'first_name' => 'John',
'last_name' => 'Doe'
],
];
Arr::forget($array, 'name.last_name');
```
### except
**Description:**
Returns the original array except given key(s).
**Parameters:**
- `$array` (array): Original array
- `$keys` (string|array): Key(s) to remove
**Returns:**
- (array)
**Example:**
```
$array = [
'user_id' => 110,
'username' => 'John',
'active' => true
];
$array = Arr::except($array, 'active');
```
### exceptValues
**Description:**
Returns the original array except given value(s).
**Parameters:**
- `$array` (array): Original array
- `$values` (string|array): Values(s) to remove
**Returns:**
- (array)
**Example:**
```
$array = [
'John',
'Jane',
'Bob'
];
$array = Arr::exceptValues($array, 'John');
```
### only
**Description:**
Returns only desired key(s) from an array.
**Parameters:**
- `$array` (array): Original array
- `$keys` (string|array): Key(s) to return
**Returns:**
- (array)
**Example:**
```
$array = [
'user_id' => 110,
'username' => 'John',
'active' => true
];
$array = Arr::only($array, 'username');
```
### missing
**Description:**
Returns array of missing keys from the original array, or an empty array if none are missing.
**Parameters:**
- `$array` (array): Original array
- `$keys` (array): Key(s) to check
**Returns:**
- (array)
**Example:**
```
$array = [
'user_id' => 110,
'username' => 'John',
'active' => true
];
$missing = Arr::missing($array, [
'active',
'last_login'
]);
```
### isMissing
**Description:**
Checks if keys are missing from the original array.
**Parameters:**
- `$array` (array): Original array
- `$keys` (array): Key(s) to check
**Returns:**
- (bool)
**Example:**
```
$array = [
'user_id' => 110,
'username' => 'John',
'active' => true
];
if (Arr::isMissing($array, [
'active',
'last_login'
])) {
// Do something
}
```
### multisort
**Description:**
Sort a multidimensional array by a given key in ascending (optionally, descending) order.
**Parameters:**
- `$array` (array): Original array
- `$key` (string): Key name to sort by
- `$descending = false` (bool): Sort descending
**Returns:**
- (array)
**Example:**
```
$clients = [
[
'first_name' => 'John',
'last_name' => 'Doe'
],
[
'first_name' => 'Jane',
'last_name' => 'Doe'
]
];
$sorted = Arr::multisort($clients, 'first_name');
```
### numericMultisort
**Description:**
Sort a numerically indexed array of multidimensional arrays by a given key in ascending (optionally, descending) order.
**Parameters:**
- `$array` (array): Numerically indexed array of multidimensional arrays
- `$key` (string): Key name to sort by in dot notation
- `$descending = false` (bool): Sort descending
**Returns:**
- (array)
**Example:**
```
$contacts = [
[
'id' => 1,
'contact' => [
'name' => 'James'
]
],
[
'id' => 2,
'contact' => [
'name' => 'Bob'
]
],
[
'id' => 3,
'contact' => [
'name' => 'Carl'
]
]
];
$sorted = Arr::numericMultisort($contacts, 'contact.name');
```
### renameKeys
**Description:**
Rename array keys while preserving their order.
**Parameters:**
- `$array` (array): Original array
- `$keys` (array): Key/value pairs to rename
**Returns:**
- (array)
**Example:**
```
$user = [
'UserID' => 5,
'UserEmail' => 'name@example.com',
'UserGroup' => 'Administrator'
];
$renamed = Arr::renameKeys($user, [
'UserID' => 'id',
'UserEmail' => 'email',
'UserGroup' => 'group'
]);
```
### order
**Description:**
Order an array based on an array of keys.
Keys from the `$order` array which do not exist in the original array will be ignored.
**Parameters:**
- `$array` (array): Original array
- `$order` (array): Array of keys in the order to be returned
**Returns:**
- (array)
**Example:**
```
$address = [
'street' => '123 Main St.',
'state' => 'IL',
'zip' => '60007',
'city' => 'Chicago'
];
$order = [
'street',
'city',
'state',
'zip',
'country'
];
$address = Arr::order($address, $order);
```
The above example will return the following array:
```
Array
(
[street] => 123 Main St.
[city] => Chicago
[state] => IL
[zip] => 60007
)
```
### getRandomItems
**Description:**
Get random items from array.
If `$count` is greater than or equal to the number of items on the array,
the original array is returned in random order.
**Parameters:**
- `$array` (array): Original array
- `$count` (int): Number of random items to return
**Returns:**
- (array)
**Example:**
```
$array = [
'John',
'Jane',
'Bob'
];
$array = Arr::getRandomItems($array, 1);
```
### query
**Description:**
Convert array into a query string.
**Parameters:**
- `$array` (array): Original array
**Returns:**
- (string)
**Example:**
```
$array = [
'first_name' => 'Jane',
'last_name' => 'Doe'
];
echo Arr::query($array);
```
### getAnyValues
**Description:**
Return an array of values which exist in a given array.
**Parameters:**
- `$array` (array)
- `$values` (array)
**Returns:**
- (array)
**Example:**
```
$array = [
'name' => [
'John',
'Dave'
],
];
$existing_values = Arr::getAnyValues($array['name'], [
'John',
'Jane'
]);
```
### hasAnyValues
**Description:**
Do any values exist in a given array.
**Parameters:**
- `$array` (array)
- `$values` (array)
**Returns:**
- (bool)
**Example:**
```
$array = [
'name' => [
'John',
'Dave'
],
];
if (Arr::hasAnyValues($array['name'], [
'John',
'Jane'
])) {
// Do something
}
```
### hasAllValues
**Description:**
Do all values exist in a given array.
**Parameters:**
- `$array` (array)
- `$values` (array)
**Returns:**
- (bool)
**Example:**
```
$array = [
'name' => [
'John',
'Dave'
],
];
if (Arr::hasAllValues($array['name'], [
'John',
'Jane'
])) {
// Do something
}
```
### ensureHas
**Description:**
Ensure a numerically indexed array of arrays has a given item based on a unique key.
**Parameters:**
- `$array` (array)
- `$item` (array): Item to exist
- `$unique_key` (string): Unique array key
**Returns:**
- (bool)
**Example:**
```
$contacts = [
[
'id' => 1,
'contact' => [
'name' => 'James'
]
],
[
'id' => 2,
'contact' => [
'name' => 'Bob'
]
],
[
'id' => 3,
'contact' => [
'name' => 'Carl'
]
]
];
$item = [
'id' => 2,
'contact' => [
'name' => 'Bob'
]
];
$contacts = Arr::ensureHas($contacts, $item, 'id');
```