Kohana array helper: an alternative to array_push that returns the result instead of handling the first argument by reference.

arr.php

<?php defined('SYSPATH') or die('No direct script access.');
/**
 * Arr transparently extended. Place in "classes" directory of Kohana 3+ application or module.
 * 
 * @author		Micheal Morgan <micheal@morgan.ly>
 * @copyright		(c) 2012 Micheal Morgan
 * @license		MIT
 */
class Arr extends Kohana_Arr
{
	/**
	 * Alternative to "array_push" that returns the contents of the appended elements instead of 
	 * treating the first element by reference.
	 * 
	 * 	$collection = Arr::push(array('apple', 'orange'), 'mango', array('pear', 'raspberry'));
	 * 
	 * 	print_r($collection);
	 * 	
	 * 	Array
	 * 	(
	 * 		[0] => apple
	 * 		[1] => orange
	 * 		[2] => mango
	 * 		[3] => pear
	 * 		[4] => raspberry
	 * 	)
	 * 
	 * @see		http://us3.php.net/array_push
	 * @static
	 * @access	public
	 * @param	mixed
	 * @return	array
	 */
	public static function push()
	{
		$args = func_get_args();
		
		$array = array();
		
		foreach ($args as $values) 
		{
			if (is_array($values)) 
			{
				if ( ! empty($values)) 
				{
					// Append reference to beginning of array.
					// I.E. `array( & $array, 'apple', 'orange')`
					array_unshift($values, & $array);

					// Called such as: `array_push( & $array, 'apple', 'orange');`
					call_user_func_array('array_push', $values);
				}
			} 
			else 
			{
				$array[] = $values;
			}
		}		

		return $array;
	}
}