Modules

Arr
extends Kohana_Arr

Array helper.

package
Kohana
category
Helpers
author
Kohana Team
copyright
© 2007-2012 Kohana Team
license
http://kohanaframework.org/license

Class declared in SYSPATH/classes/arr.php on line 3.

Properties

public static string $delimiter

default delimiter for path()

string(1) "."

Methods

public static callback( string $str ) (defined in Kohana_Arr)

Creates a callable function and parameter list from a string representation. Note that this function does not validate the callback string.

// Get the callback function and parameters
list($func, $params) = Arr::callback('Foo::bar(apple,orange)');

// Get the result of the callback
$result = call_user_func_array($func, $params);

Parameters

  • string $str required - Callback string

Return Values

  • array - Function, params

Source Code

public static function callback($str)
{
	// Overloaded as parts are found
	$command = $params = NULL;

	// command[param,param]
	if (preg_match('/^([^\(]*+)\((.*)\)$/', $str, $match))
	{
		// command
		$command = $match[1];

		if ($match[2] !== '')
		{
			// param,param
			$params = preg_split('/(?<!\\\\),/', $match[2]);
			$params = str_replace('\,', ',', $params);
		}
	}
	else
	{
		// command
		$command = $str;
	}

	if (strpos($command, '::') !== FALSE)
	{
		// Create a static method callable command
		$command = explode('::', $command, 2);
	}

	return array($command, $params);
}

public static extract( array $array , array $keys [, mixed $default = NULL ] ) (defined in Kohana_Arr)

Retrieves multiple keys from an array. If the key does not exist in the array, the default value will be added instead.

// Get the values "username", "password" from $_POST
$auth = Arr::extract($_POST, array('username', 'password'));

Parameters

  • array $array required - Array to extract keys from
  • array $keys required - List of key names
  • mixed $default = NULL - Default value

Return Values

  • array

Source Code

public static function extract($array, array $keys, $default = NULL)
{
	$found = array();
	foreach ($keys as $key)
	{
		$found[$key] = isset($array[$key]) ? $array[$key] : $default;
	}

	return $found;
}

public static flatten( array $array ) (defined in Kohana_Arr)

Convert a multi-dimensional array into a single-dimensional array.

$array = array('set' => array('one' => 'something'), 'two' => 'other');

// Flatten the array
$array = Arr::flatten($array);

// The array will now be
array('one' => 'something', 'two' => 'other');

The keys of array values will be discarded.

Parameters

  • array $array required - Array to flatten

Tags

  • Since - 3.0.6

Return Values

  • array

Source Code

public static function flatten($array)
{
	$is_assoc = Arr::is_assoc($array);

	$flat = array();
	foreach ($array as $key => $value)
	{
		if (is_array($value))
		{
			$flat = array_merge($flat, Arr::flatten($value));
		}
		else
		{
			if ($is_assoc)
			{
				$flat[$key] = $value;
			}
			else
			{
				$flat[] = $value;
			}
		}
	}
	return $flat;
}

public static get( array $array , string $key [, mixed $default = NULL ] ) (defined in Kohana_Arr)

Retrieve a single key from an array. If the key does not exist in the array, the default value will be returned instead.

// Get the value "username" from $_POST, if it exists
$username = Arr::get($_POST, 'username');

// Get the value "sorting" from $_GET, if it exists
$sorting = Arr::get($_GET, 'sorting');

Parameters

  • array $array required - Array to extract from
  • string $key required - Key name
  • mixed $default = NULL - Default value

Return Values

  • mixed

Source Code

public static function get($array, $key, $default = NULL)
{
	return isset($array[$key]) ? $array[$key] : $default;
}

public static is_array( mixed $value ) (defined in Kohana_Arr)

Test if a value is an array with an additional check for array-like objects.

// Returns TRUE
Arr::is_array(array());
Arr::is_array(new ArrayObject);

// Returns FALSE
Arr::is_array(FALSE);
Arr::is_array('not an array!');
Arr::is_array(Database::instance());

Parameters

  • mixed $value required - Value to check

Return Values

  • boolean

Source Code

public static function is_array($value)
{
	if (is_array($value))
	{
		// Definitely an array
		return TRUE;
	}
	else
	{
		// Possibly a Traversable object, functionally the same as an array
		return (is_object($value) AND $value instanceof Traversable);
	}
}

public static is_assoc( array $array ) (defined in Kohana_Arr)

Tests if an array is associative or not.

// Returns TRUE
Arr::is_assoc(array('username' => 'john.doe'));

// Returns FALSE
Arr::is_assoc('foo', 'bar');

Parameters

  • array $array required - Array to check

Return Values

  • boolean

Source Code

public static function is_assoc(array $array)
{
	// Keys of the array
	$keys = array_keys($array);

	// If the array keys of the keys match the keys, then the array must
	// not be associative (e.g. the keys array looked like {0:0, 1:1...}).
	return array_keys($keys) !== $keys;
}

public static map( mixed $callbacks , array $array [, array $keys = NULL ] ) (defined in Kohana_Arr)

Recursive version of array_map, applies one or more callbacks to all elements in an array, including sub-arrays.

// Apply "strip_tags" to every element in the array
$array = Arr::map('strip_tags', $array);

// Apply $this->filter to every element in the array
$array = Arr::map(array(array($this,'filter')), $array);

// Apply strip_tags and $this->filter to every element
$array = Arr::map(array('strip_tags',array($this,'filter')), $array);

Because you can pass an array of callbacks, if you wish to use an array-form callback you must nest it in an additional array as above. Calling Arr::map(array($this,'filter'), $array) will cause an error. [!!] Unlike array_map, this method requires a callback and will only map a single array.

Parameters

  • mixed $callbacks required - Array of callbacks to apply to every element in the array
  • array $array required - Array to map
  • array $keys = NULL - Array of keys to apply to

Return Values

  • array

Source Code

public static function map($callbacks, $array, $keys = NULL)
{
	foreach ($array as $key => $val)
	{
		if (is_array($val))
		{
			$array[$key] = Arr::map($callbacks, $array[$key]);
		}
		elseif ( ! is_array($keys) or in_array($key, $keys))
		{
			if (is_array($callbacks))
			{
				foreach ($callbacks as $cb)
				{
					$array[$key] = call_user_func($cb, $array[$key]);
				}
			}
			else
			{
				$array[$key] = call_user_func($callbacks, $array[$key]);
			}
		}
	}

	return $array;
}

public static merge( array $a1 , array $a2 ) (defined in Kohana_Arr)

Merges one or more arrays recursively and preserves all keys. Note that this does not work the same as array_merge_recursive!

$john = array('name' => 'john', 'children' => array('fred', 'paul', 'sally', 'jane'));
$mary = array('name' => 'mary', 'children' => array('jane'));

// John and Mary are married, merge them together
$john = Arr::merge($john, $mary);

// The output of $john will now be:
array('name' => 'mary', 'children' => array('fred', 'paul', 'sally', 'jane'))

Parameters

  • array $a1 required - Initial array
  • array $a2 required - ,... array to merge

Return Values

  • array

Source Code

public static function merge(array $a1, array $a2)
{
	$result = array();
	for ($i = 0, $total = func_num_args(); $i < $total; $i++)
	{
		// Get the next array
		$arr = func_get_arg($i);

		// Is the array associative?
		$assoc = Arr::is_assoc($arr);

		foreach ($arr as $key => $val)
		{
			if (isset($result[$key]))
			{
				if (is_array($val) AND is_array($result[$key]))
				{
					if (Arr::is_assoc($val))
					{
						// Associative arrays are merged recursively
						$result[$key] = Arr::merge($result[$key], $val);
					}
					else
					{
						// Find the values that are not already present
						$diff = array_diff($val, $result[$key]);

						// Indexed arrays are merged to prevent duplicates
						$result[$key] = array_merge($result[$key], $diff);
					}
				}
				else
				{
					if ($assoc)
					{
						// Associative values are replaced
						$result[$key] = $val;
					}
					elseif ( ! in_array($val, $result, TRUE))
					{
						// Indexed values are added only if they do not yet exist
						$result[] = $val;
					}
				}
			}
			else
			{
				// New values are added
				$result[$key] = $val;
			}
		}
	}

	return $result;
}

public static overwrite( array $array1 , array $array2 ) (defined in Kohana_Arr)

Overwrites an array with values from input arrays. Keys that do not exist in the first array will not be added!

$a1 = array('name' => 'john', 'mood' => 'happy', 'food' => 'bacon');
$a2 = array('name' => 'jack', 'food' => 'tacos', 'drink' => 'beer');

// Overwrite the values of $a1 with $a2
$array = Arr::overwrite($a1, $a2);

// The output of $array will now be:
array('name' => 'jack', 'mood' => 'happy', 'food' => 'tacos')

Parameters

  • array $array1 required - Master array
  • array $array2 required - Input arrays that will overwrite existing values

Return Values

  • array

Source Code

public static function overwrite($array1, $array2)
{
	foreach (array_intersect_key($array2, $array1) as $key => $value)
	{
		$array1[$key] = $value;
	}

	if (func_num_args() > 2)
	{
		foreach (array_slice(func_get_args(), 2) as $array2)
		{
			foreach (array_intersect_key($array2, $array1) as $key => $value)
			{
				$array1[$key] = $value;
			}
		}
	}

	return $array1;
}

public static path( array $array , mixed $path [, mixed $default = NULL , string $delimiter = NULL ] ) (defined in Kohana_Arr)

Gets a value from an array using a dot separated path.

// Get the value of $array['foo']['bar']
$value = Arr::path($array, 'foo.bar');

Using a wildcard "*" will search intermediate arrays and return an array.

// Get the values of "color" in theme
$colors = Arr::path($array, 'theme.*.color');

// Using an array of keys
$colors = Arr::path($array, array('theme', '*', 'color'));

Parameters

  • array $array required - Array to search
  • mixed $path required - Key path string (delimiter separated) or array of keys
  • mixed $default = NULL - Default value if the path is not set
  • string $delimiter = NULL - Key path delimiter

Return Values

  • mixed

Source Code

public static function path($array, $path, $default = NULL, $delimiter = NULL)
{
	if ( ! Arr::is_array($array))
	{
		// This is not an array!
		return $default;
	}

	if (is_array($path))
	{
		// The path has already been separated into keys
		$keys = $path;
	}
	else
	{
		if (array_key_exists($path, $array))
		{
			// No need to do extra processing
			return $array[$path];
		}

		if ($delimiter === NULL)
		{
			// Use the default delimiter
			$delimiter = Arr::$delimiter;
		}

		// Remove starting delimiters and spaces
		$path = ltrim($path, "{$delimiter} ");

		// Remove ending delimiters, spaces, and wildcards
		$path = rtrim($path, "{$delimiter} *");

		// Split the keys by delimiter
		$keys = explode($delimiter, $path);
	}

	do
	{
		$key = array_shift($keys);

		if (ctype_digit($key))
		{
			// Make the key an integer
			$key = (int) $key;
		}

		if (isset($array[$key]))
		{
			if ($keys)
			{
				if (Arr::is_array($array[$key]))
				{
					// Dig down into the next part of the path
					$array = $array[$key];
				}
				else
				{
					// Unable to dig deeper
					break;
				}
			}
			else
			{
				// Found the path requested
				return $array[$key];
			}
		}
		elseif ($key === '*')
		{
			// Handle wildcards

			$values = array();
			foreach ($array as $arr)
			{
				if ($value = Arr::path($arr, implode('.', $keys)))
				{
					$values[] = $value;
				}
			}

			if ($values)
			{
				// Found the values requested
				return $values;
			}
			else
			{
				// Unable to dig deeper
				break;
			}
		}
		else
		{
			// Unable to dig deeper
			break;
		}
	}
	while ($keys);

	// Unable to find the value requested
	return $default;
}

public static pluck( array $array , string $key ) (defined in Kohana_Arr)

Retrieves muliple single-key values from a list of arrays.

// Get all of the "id" values from a result
$ids = Arr::pluck($result, 'id');

A list of arrays is an array that contains arrays, eg: array(array $a, array $b, array $c, ...)

Parameters

  • array $array required - List of arrays to check
  • string $key required - Key to pluck

Return Values

  • array

Source Code

public static function pluck($array, $key)
{
	$values = array();

	foreach ($array as $row)
	{
		if (isset($row[$key]))
		{
			// Found a value in this row
			$values[] = $row[$key];
		}
	}

	return $values;
}

public static range( [ integer $step = integer 10 , integer $max = integer 100 ] ) (defined in Kohana_Arr)

Fill an array with a range of numbers.

// Fill an array with values 5, 10, 15, 20
$values = Arr::range(5, 20);

Parameters

  • integer $step = integer 10 - Stepping
  • integer $max = integer 100 - Ending number

Return Values

  • array

Source Code

public static function range($step = 10, $max = 100)
{
	if ($step < 1)
		return array();

	$array = array();
	for ($i = $step; $i <= $max; $i += $step)
	{
		$array[$i] = $i;
	}

	return $array;
}

public static set_path( array & $array , string $path , mixed $value [, string $delimiter = NULL ] ) (defined in Kohana_Arr)

Set a value on an array by path.

Parameters

  • byref array $array required - Array to update
  • string $path required - Path
  • mixed $value required - Value to set
  • string $delimiter = NULL - Path delimiter

Tags

  • See - Arr::path()

Source Code

public static function set_path( & $array, $path, $value, $delimiter = NULL)
{
	if ( ! $delimiter)
	{
		// Use the default delimiter
		$delimiter = Arr::$delimiter;
	}

	// Split the keys by delimiter
	$keys = explode($delimiter, $path);

	// Set current $array to inner-most array path
	while (count($keys) > 1)
	{
		$key = array_shift($keys);

		if (ctype_digit($key))
		{
			// Make the key an integer
			$key = (int) $key;
		}

		if ( ! isset($array[$key]))
		{
			$array[$key] = array();
		}

		$array = & $array[$key];
	}

	// Set key on inner-most array
	$array[array_shift($keys)] = $value;
}

public static unshift( array & $array , string $key , mixed $val ) (defined in Kohana_Arr)

Adds a value to the beginning of an associative array.

// Add an empty value to the start of a select list
Arr::unshift($array, 'none', 'Select a value');

Parameters

  • byref array $array required - Array to modify
  • string $key required - Array key name
  • mixed $val required - Array value

Return Values

  • array

Source Code

public static function unshift( array & $array, $key, $val)
{
	$array = array_reverse($array, TRUE);
	$array[$key] = $val;
	$array = array_reverse($array, TRUE);

	return $array;
}