Arr

Hazaar Array Utility Class.

This class provides a number of utility functions for working with arrays and objects.

Methods

get

Get a value from an array or object with advanced search capabilities.

public get(\ArrayAccess $array, string $key): mixed

Returns a value from an array or a property from an object, if it exists, using advanced search capabilities such as dot-notation and search parameters.

Keys may be specified using dot-notation. This allows array_get() to be called only once instead of for each element in a reference chain. For example, you can call array_get($myarray, 'object.child.other'); and each reference will be recursed into if it exists. If at any step the child does not exist then execution will stop and return null.

If the key contains round or square brackets, then this is taken as a search parameter, allowing the specified element to be search for child elements that match the search criteria. This search parameter can, and is actually designed to, be used with dot-notation. So for example, you can call array_get($myarray, 'items(type.id=1).name') to find an element in the items sub-element of $myarray that has it's own type element with another sub-element of id with a value that matches 1. As you can imagine, this allows quite a powerful way of accessing sub-elements of arrays/objects using a simple dot-notation search parameter.

If the key contains square brackets, then this is taken as an indexed array search parameter and the value will be accessed using it's numeric index. For example: array_get($myarray, 'items[0].name') will return the name of the first item in the items array.

Support types for $key parameter:

• string - Single key.
• string - Dot notation key for decending into multi-dimensional arrays/objects, including search parameters.

Parameters

Parameter	Type	Description
$array	\ArrayAccess	The array to search. Objects with public properties are also supported.
$key	string	the array key or object property name to look for

replaceKey

Array Key Rename.

public replaceKey(object $array, mixed $keyFrom, mixed $keyTo): mixed

Rename a key in an array to something else, maintaining the value.

Parameters

Parameter	Type	Description
$array	object	the array to work on
$keyFrom	mixed	the key name to rename
$keyTo	mixed	the key name to change to

isMulti

Test of array is multi-dimensional.

public isMulti(array $array): bool

Test an array to see if it's a multidimensional array and returns TRUE or FALSE.

Parameters

Parameter	Type	Description
$array	array	The array to test

isAssoc

Test of array is an associative array.

public isAssoc(array $array): bool

Test an array to see if it is associative or numerically keyed. Returns TRUE for associative or FALSE for numeric.

Parameters

Parameter	Type	Description
$array	array	The array to test

flatten

Flattens a multidimensional array into a string representation.

public flatten(array $array, string $delim = '=', string $sectionDelim = ';'): string

This method will convert an array into a string representation of the array. This is useful for storing arrays in a database or other storage where the array needs to be stored as a string.

Use the Arr::unflatten() method to convert the string back into an array.

Parameters

Parameter	Type	Description
$array	array	the array to flatten
$delim	string	The delimiter to use between the key and value of each item. Default is '='.
$sectionDelim	string	The delimiter to use between each item. Default is ';'.

unflatten

Converts a flattened string or array into a multidimensional array.

public unflatten(string $items, string $delim = '=', string $sectionDelim = ';'): void

This method will convert a string representation of an array into an array. It is normally used in conjunction with the Arr::flatten() method to convert the string back into an array, but can also be used to convert a string that contains key-value pairs into an array.

Parameters

Parameter	Type	Description
$items	string	The flattened string to be converted
$delim	string	The delimiter used to separate the key-value pairs in the flattened string. Default is '='.
$sectionDelim	string	The delimiter used to separate multiple key-value pairs in the flattened string. Default is ';'.

collate

Collate a multi-dimensional array into an associative array where $keyItem is the key and $valueItem is the value.

public collate(array $array, string $keyItem, string $valueItem, string $groupItem): void

• If the key value does not exist in the array, the element is skipped.
• If the value item does not exist, the value will be NULL.

Parameters

Parameter	Type	Description
$array	array	the array to collate
$keyItem	string	the value to use as the key. If true is passed, the key will be the array key.
$valueItem	string	The value to use as the value. If not supplied, the whole element will be the value. Allows re-keying a mult-dimensional array by an array element.
$groupItem	string	optional value to group items by

buildHtml

Converts a multi dimensional array into key[key][key] => value syntax that can be used in html INPUT field names.

public buildHtml(array $array, bool $root = true): void

Parameters

Parameter	Type	Description
$array	array	The array to convert
$root	bool	If true, the root element is not included in the key

toDotNotation

Convert a multi-dimenstional array to dot notation.

public toDotNotation(array $array, string $separator = '.', ?int $depth, string $numericArraySeparators = '[]'): void

Converts/reduces a multidimensional array into a single dimensional array with keys in dot-notation.

Parameters

Parameter	Type	Description
$array	array	the array to convert
$separator	string	The separater to use between keys. Defaults to '.', hence the name of the functions.
$depth	int	Limit to the specified depth. Starting at 1, this is the number of levels to return. Essentially, this is the number of dots, plus one.
$numericArraySeparators	string	This parameter is used to display numeric arrays. It defaults to '[]' which means that numeric arrays will appear as "item[index].key". This argument must be at least two characters. The first character is the left side and the second character is the right side. Any non-string values or string values less than 2 characters long will be ignored and numeric arrays will not be used. To disable numeric arrays and cause elements with a numeric key to be output the same as other string key elements, simply set this to NULL.

fromDotNotation

Convert a single dimension array in dot notation into a multi-dimensional array.

public fromDotNotation(array $array): void

This is the inverse of Arr::toDotNotation().

Parameters

Parameter	Type	Description
$array	array

enhance

Merge two arrays together but only add elements that don't already exist in the target array.

public enhance(array $targetArray, array $sourceArray): void

This function is similar to array_merge() but will only add elements that don't already exist in the target array.

Parameters

Parameter	Type	Description
$targetArray	array	The array to merge into
$sourceArray	array	The array to merge from

seek

Seek the array cursor forward $count number of elements.

public seek(array $array, int $count): void

Parameters

Parameter	Type	Description
$array	array	The array to seek
$count	int	The number of elements to seek forward

replaceRecursive

Replaces elements from passed arrays or objects into the first array or object recursively.

public replaceRecursive(mixed $items): mixed

NOTE: This function is almost identical to the PHP function array_replace_recursive() except that it also works with stdClass objects.

replace_recursive() replaces the values of item1 with the same values from all the following items. If a key from the first item exists in the second item, its value will be replaced by the value from the second item. If the key exists in the second item, and not the first, it will be created in the first item. If a key only exists in the first item, it will be left as is. If several items are passed for replacement, they will be processed in order, the later item overwriting the previous values.

replace_recursive() is recursive : it will recurse into item and apply the same process to the inner value.

When the value in item1 is scalar, it will be replaced by the value in item2, may it be scalar, array or stdClass. When the value in item1 and item2 are both arrays or objects, replace_recursive() will replace their respective value recursively.

Parameters

Parameter	Type	Description
$items	mixed

diffAssocRecursive

Recursivly computes the difference of arrays with additional index check.

public diffAssocRecursive(mixed $arrays): void

Compares array1 against array2 and returns the difference. Unlike array_diff() the array keys are also used in the comparison. Also, unlike the PHP array_diff_assoc() function, this function recurse into child arrays.

Parameters

Parameter	Type	Description
$arrays	mixed	more arrays to compare against

fromObject

Recursively convert an object into an array.

public fromObject(object $object): void

This is basically a recursive version of PHP's get_object_vars().

Parameters

Parameter	Type	Description
$object	object	the object to convert

toObject

Recursively convert an array into an object.

public toObject(array $array): void

This is the inverse of object_to_array().

Parameters

Parameter	Type	Description
$array	array

usearch

Searches the array using a callback function and returns the first corresponding key if successful.

public usearch(array $haystack, callable $callback): mixed

Parameters

Parameter	Type	Description
$haystack	array	the array
$callback	callable	The callback function to use. This function should return true if the value matches.

inUarray

Checks if a value exists in an array using a callback function.

public inUarray(mixed $haystack, callable $callback): void

Parameters

Parameter	Type	Description
$haystack	mixed	the array
$callback	callable	The callback function to use. This function should return true if the value matches.

removeEmpty

Recursively remove all empty values from an array.

public removeEmpty(array $array): void

Removes all values from an array that are considered empty. This includes null values, empty strings and empty arrays.

Unlike PHP's empty() function, this DOES NOT include 0, 0.0, "0" or false.

Parameters

Parameter	Type	Description
$array	array

pull

Pull an item out of an array by is key.

public pull(array $array, string $key): mixed

This function is similar to array_pop() and array_shift(), except that instead of popping the last/first element off the array, it pops an element with the specified key.

Parameters

Parameter	Type	Description
$array	array	the array to pull the element from
$key	string	the key of the element

deepClone

Performs a deep clone on an object or array.

public deepClone(mixed $object): mixed

The standard PHP clone function will only perform a shallow copy of the object. PHP has implemented the __clone() magic method to allow objects to recursively clone properties. However, this does not help when you are cloning a \stdClass object. This function allows you to perform a deep clone of any object, including \stdClass and also clone all it's properties recursively.

Parameters

Parameter	Type	Description
$object	mixed	The object to clone. If the parameter is an array then it will be recursed. If it is anything it simply returned as is.

diffKeyRecursive

Computes the difference of arrays using keys for comparison recursively.

public diffKeyRecursive(mixed $arrays): void

This is the same as array_diff_key() except it will recurse into child arrays and return them in the result if they contain any key differences.

Parameters

Parameter	Type	Description
$arrays	mixed

grammaticalImplode

Grammatically correct array implode.

public grammaticalImplode(array $array, string $glue = 'and'): string

Implode an array, joining it's values in a grammatically correct manner.

Example:

echo grammatical_implode([ 'One', 'Two', 'Three', 'Four' ]);

Output: One, Two, Three and Four

Parameters

Parameter	Type	Description
$array	array
$glue	string

recursiveIteratorToArray

Recrusively convert a traversable object into a normal array.

public recursiveIteratorToArray(\Traversable $it): void

This is the same as the built-in PHP iterator_to_array() function except it will recurse into any \Traversable objects it contains.

Parameters

Parameter	Type	Description
$it	\Traversable	the object to convert to an array

---

Generated by Hazaar API Doc Generator