FuelPHP Logo

FuelPHP API Documentation

Ask your question about FuelPHP in the appropriate forum, or help others by answering their questions.

The Arr class provides a few nice functions for making dealing with arrays easier

package Fuel
subpackage Core

 Methods

Converts a multi-dimensional associative array into an array of key => values with the provided field names

assoc_to_keyval(array $assoc, string $key_field, string $val_field) : array

Parameters

$assoc

array

the array to convert

$key_field

string

the field name of the key field

$val_field

string

the field name of the value field

Exceptions

\InvalidArgumentException

Returns

array

Find the average of an array

average(array $array) : \Fuel\Core\number

Parameters

$array

array

the array containing the values

Returns

\Fuel\Core\numberthe average value

Unsets dot-notated key from an array

delete(array $array, mixed $key) : mixed

Parameters

$array

array

The search array

$key

mixed

The dot-notated key or array of keys

Returns

mixed

Filters an array by an array of keys

filter_keys(array $array, array $keys, bool $remove) : array

Parameters

$array

array

the array to filter.

$keys

array

the keys to filter

$remove

bool

if true, removes the matched elements.

Returns

array

Filters an array on prefixed associative keys.

filter_prefixed(array $array, string $prefix, bool $remove_prefix) : array

Parameters

$array

array

the array to filter.

$prefix

string

prefix to filter on.

$remove_prefix

bool

whether to remove the prefix.

Returns

array

Recursive version of PHP's array_filter()

filter_recursive(array $array, callback $callback) : array

Parameters

$array

array

the array to filter.

$callback

callback

the callback that determines whether or not a value is filtered

Returns

array

Filters an array on suffixed associative keys.

filter_suffixed(array $array, string $suffix, bool $remove_suffix) : array

Parameters

$array

array

the array to filter.

$suffix

string

suffix to filter on.

$remove_suffix

bool

whether to remove the suffix.

Returns

array

Flattens a multi-dimensional associative array down into a 1 dimensional associative array.

flatten(array $array, string $glue, bool $reset, bool $indexed) : array

Parameters

$array

array

the array to flatten

$glue

string

what to glue the keys together with

$reset

bool

whether to reset and start over on a new array

$indexed

bool

whether to flatten only associative array's, or also indexed ones

Returns

array

Flattens a multi-dimensional associative array down into a 1 dimensional associative array.

flatten_assoc(array $array, string $glue, bool $reset) : array

Parameters

$array

array

the array to flatten

$glue

string

what to glue the keys together with

$reset

bool

whether to reset and start over on a new array

Returns

array

Gets a dot-notated key from an array, with a default value if it does not exist.

get(array $array, mixed $key, string $default) : mixed

Parameters

$array

array

The search array

$key

mixed

The dot-notated key or array of keys

$default

string

The default value

Returns

mixed

Recursive in_array

in_array_recursive(mixed $needle, array $haystack, bool $strict) : bool

Parameters

$needle

mixed

what to search for

$haystack

array

array to search in

$strict

bool

Returns

boolwhether the needle is found in the haystack.

Insert value(s) into an array, mostly an array_splice alias WARNING: original array is edited by reference, only boolean success is returned

insert(array $original, array | mixed $value, int $pos) : bool

Parameters

$original

array

the original array (by reference)

$value

arraymixed

the value(s) to insert, if you want to insert an array it needs to be in an array itself

$pos

int

the numeric position at which to insert, negative to count from the end backwards

Returns

boolfalse when array shorter then $pos, otherwise true

Insert value(s) into an array after a specific key WARNING: original array is edited by reference, only boolean success is returned

insert_after_key(array $original, array | mixed $value, string | int $key, bool $is_assoc) : bool

Parameters

$original

array

the original array (by reference)

$value

arraymixed

the value(s) to insert, if you want to insert an array it needs to be in an array itself

$key

stringint

the key after which to insert

$is_assoc

bool

whether the input is an associative array

Returns

boolfalse when key isn't found in the array, otherwise true

Insert value(s) into an array after a specific value (first found in array)

insert_after_value(array $original, array | mixed $value, string | int $search, bool $is_assoc) : bool

Parameters

$original

array

the original array (by reference)

$value

arraymixed

the value(s) to insert, if you want to insert an array it needs to be in an array itself

$search

stringint

the value after which to insert

$is_assoc

bool

whether the input is an associative array

Returns

boolfalse when value isn't found in the array, otherwise true

Insert value(s) into an array, mostly an array_splice alias WARNING: original array is edited by reference, only boolean success is returned

insert_assoc(array $original, array $values, int $pos) : bool

Parameters

$original

array

the original array (by reference)

$values

arraymixed

the value(s) to insert, if you want to insert an array it needs to be in an array itself

$pos

int

the numeric position at which to insert, negative to count from the end backwards

Returns

boolfalse when array shorter then $pos, otherwise true

Insert value(s) into an array before a specific key WARNING: original array is edited by reference, only boolean success is returned

insert_before_key(array $original, array | mixed $value, string | int $key, bool $is_assoc) : bool

Parameters

$original

array

the original array (by reference)

$value

arraymixed

the value(s) to insert, if you want to insert an array it needs to be in an array itself

$key

stringint

the key before which to insert

$is_assoc

bool

whether the input is an associative array

Returns

boolfalse when key isn't found in the array, otherwise true

Insert value(s) into an array before a specific value (first found in array)

insert_before_value(array $original, array | mixed $value, string | int $search, bool $is_assoc) : bool

Parameters

$original

array

the original array (by reference)

$value

arraymixed

the value(s) to insert, if you want to insert an array it needs to be in an array itself

$search

stringint

the value after which to insert

$is_assoc

bool

whether the input is an associative array

Returns

boolfalse when value isn't found in the array, otherwise true

Checks if the given array is an assoc array.

is_assoc(array $arr) : bool

Parameters

$arr

array

the array to check

Returns

booltrue if its an assoc array, false if not

Checks if the given array is a multidimensional array.

is_multi(array $arr, bool $all_keys) : bool

Parameters

$arr

array

the array to check

$all_keys

bool

if true, check that all elements are arrays

Returns

booltrue if its a multidimensional array, false if not

Array_key_exists with a dot-notated key from an array.

key_exists(array $array, mixed $key) : mixed

Parameters

$array

array

The search array

$key

mixed

The dot-notated key or array of keys

Returns

mixed

Converts an array of key => values into a multi-dimensional associative array with the provided field names

keyval_to_assoc(array $array, string $key_field, string $val_field) : array

Parameters

$array

array

the array to convert

$key_field

string

the field name of the key field

$val_field

string

the field name of the value field

Exceptions

\InvalidArgumentException

Returns

array

Merge 2 arrays recursively, differs in 2 important ways from array_merge_recursive() - When there's 2 different values and not both arrays, the latter value overwrites the earlier instead of merging both into an array - Numeric keys that don't conflict aren't changed, only when a numeric key already exists is the value added using array_push()

merge() : array

Exceptions

\InvalidArgumentException

Returns

array

Merge 2 arrays recursively, differs in 2 important ways from array_merge_recursive() - When there's 2 different values and not both arrays, the latter value overwrites the earlier instead of merging both into an array - Numeric keys are never changed

merge_assoc() : array

Exceptions

\InvalidArgumentException

Returns

array

Sorts an array on multiple values, with deep sorting support.

multisort(array $array, array $conditions, bool $ignore_case) : array

Parameters

$array

array

collection of arrays/objects to sort

$conditions

array

sorting conditions

$ignore_case

bool

whether to sort case insensitive

Returns

array

Get the next value or key from an array using the current array key

next_by_key(array $array, string $key, bool $get_value, bool $strict) : mixed

Parameters

$array

array

the array containing the values

$key

string

key of the current entry to use as reference

$get_value

bool

if true, return the next value instead of the next key

$strict

bool

if true, do a strict key comparison

Returns

mixedthe value in the array, null if there is no next value, or false if the key doesn't exist

Get the next value or key from an array using the current array value

next_by_value(array $array, string $value, bool $get_value, bool $strict) : mixed

Parameters

$array

array

the array containing the values

$value

string

value of the current entry to use as reference

$get_value

bool

if true, return the next value instead of the next key

$strict

bool

if true, do a strict key comparison

Returns

mixedthe value in the array, null if there is no next value, or false if the key doesn't exist

Pluck an array of values from an array.

pluck(array $array, string $key, string $index) : array

Parameters

$array

array

collection of arrays to pluck from

$key

string

key of the value to pluck

$index

string

optional return array index key, true for original index

Returns

arrayarray of plucked values

Prepends a value with an associative key to an array.

prepend(array $arr, string | array $key, mixed $value) 

Will overwrite if the value exists.

Parameters

$arr

array

the array to prepend to

$key

stringarray

the key or array of keys and values

$value

mixed

the value to prepend

Get the previous value or key from an array using the current array key

previous_by_key(array $array, string $key, bool $get_value, bool $strict) : mixed

Parameters

$array

array

the array containing the values

$key

string

key of the current entry to use as reference

$get_value

bool

if true, return the previous value instead of the previous key

$strict

bool

if true, do a strict key comparison

Returns

mixedthe value in the array, null if there is no previous value, or false if the key doesn't exist

Get the previous value or key from an array using the current array value

previous_by_value(array $array, string $value, bool $get_value, bool $strict) : mixed

Parameters

$array

array

the array containing the values

$value

string

value of the current entry to use as reference

$get_value

bool

if true, return the previous value instead of the previous key

$strict

bool

if true, do a strict key comparison

Returns

mixedthe value in the array, null if there is no previous value, or false if the key doesn't exist

Returns the array with all numeric keys re-indexed, and string keys untouched

reindex(array $arr) : array

Parameters

$arr

array

the array to reindex

Returns

arrayre-indexed array

Removes items from an array that match a key prefix.

remove_prefixed(array $array, string $prefix) : array

Parameters

$array

array

the array to remove from

$prefix

string

prefix to filter on

Returns

array

Removes items from an array that match a key suffix.

remove_suffixed(array $array, string $suffix) : array

Parameters

$array

array

the array to remove from

$suffix

string

suffix to filter on

Returns

array

Replaces key names in an array by names in $replace

replace_key(array $source, array | string $replace, string $new_key) : array

Parameters

$source

array

the array containing the key/value combinations

$replace

arraystring

key to replace or array containing the replacement keys

$new_key

string

the replacement key

Returns

arraythe array with the new keys

Reverse a flattened array in its original form.

reverse_flatten(array $array, string $glue) : array

Parameters

$array

array

flattened array

$glue

string

glue used in flattening

Returns

arraythe unflattened array

Searches the array for a given value and returns the corresponding key or default value.

search(array $array, mixed $value, string $default, bool $recursive, string $delimiter, bool $strict) : mixed

If $recursive is set to true, then the Arr::search() function will return a delimiter-notated key using $delimiter.

Parameters

$array

array

The search array

$value

mixed

The searched value

$default

string

The default value

$recursive

bool

Whether to get keys recursive

$delimiter

string

The delimiter, when $recursive is true

$strict

bool

If true, do a strict key comparison

Returns

mixed

Set an array item (dot-notated) to the value.

set(array $array, mixed $key, mixed $value) : void

Parameters

$array

array

The array to insert it into

$key

mixed

The dot-notated key to set or array of keys

$value

mixed

The value

Sorts a multi-dimensional array by it's values.

sort(array $array, string $key, string $order, int $sort_flags) : array

access public

Parameters

$array

array

The array to fetch from

$key

string

The key to sort by

$order

string

The order (asc or desc)

$sort_flags

int

The php sort type flag

Returns

array

Return the subset of the array defined by the supplied keys.

subset(array $array, array $keys, mixed $default) : array

Returns $default for missing keys, as with Arr::get()

Parameters

$array

array

the array containing the values

$keys

array

list of keys (or indices) to return

$default

mixed

value of missing keys; default null

Returns

arrayAn array containing the same set of keys provided.

Calculate the sum of an array

sum(array $array, string $key) : \Fuel\Core\number

Parameters

$array

array

the array containing the values

$key

string

key of the value to pluck

Returns

\Fuel\Core\numberthe sum value

Converts the given 1 dimensional non-associative array to an associative array.

to_assoc(string $arr) : array | null

The array given must have an even number of elements or null will be returned.

Arr::to_assoc(array('foo','bar'));

Parameters

$arr

string

the array to change

Exceptions

\BadMethodCallException

Returns

arraynullthe new array or null

Returns only unique values in an array.

unique(array $arr) : array

It does not sort. First value is used.

Parameters

$arr

array

the array to dedup

Returns

arrayarray with only de-duped values