collection.php

<?php
/**
 * Collection functions, mainly used to manipulate lists of PHPActiveRecord models.
 * 
 * @author Taddeus Kroes
 * @version 1.0
 * @date 13-07-2012
 */

namespace WebBasics;

require_once 'base.php';

/**
 * The Collection class contains a number of functions sort, index and manipulate
 * an array of items.
 * 
 * Example 1: Index a list based on its values and extract a single attribute.
 * <code>
 * class Book extends PHPActiveRecord\Model {
 *     static $attr_accessible = array('id', 'name');
 * }
 * 
 * // Index all book names by their id.
 * $books = Book::all();                      // Find a list of books
 * $collection = new Collection($books);      // Put the list in a collection
 * $indexed = $collection->index_by('id');    // Create indexes for all books
 * $names = $indexed->get_attribute('name');  // Get the values of a single attribute
 * // $names now contains something like array(1 => 'Some book', 2 => 'Another book')
 * 
 * // Same as above:
 * $names = Collection::create(Book::all())->index_by('id')->get_attribute('name');
 * </code>
 * 
 * Example 2: Execute a method for each item in a list.
 * <code>
 * // Delete all books
 * Collection::create(Book::all())->map_method('delete');
 * </code>
 * 
 * @package WebBasics
 * @todo Finish unit tests
 */
class Collection extends Base {
	/**
	 * The set of items item that is being manipulated, as an associoative array.
	 * 
	 * @var array
	 */
	private $items;
	
	/**
	 * Create a new Collection object.
	 * 
	 * @param array $items Initial item set (optional).
	 */
	function __construct(array $items=array()) {
		$this->items = $items;
	}
	
	/**
	 * Add an item to the collection.
	 * 
	 * @param mixed $item The item to add.
	 */
	function add($item) {
		$this->items[] = $item;
	}
	
	/**
	 * Insert an item at a specific index in the collection.
	 * 
	 * If the index is numeric, all existing numeric indices from that
	 * index will be shifted one position to the right.
	 * 
	 * @param mixed $item The item to insert.
	 * @param int|string $index The index at which to insert the item.
	 * @throws \InvalidArgumentException If the added index already exists, and is non-numeric.
	 */
	function insert($item, $index) {
		if( isset($this->items[$index]) ) {
			if( !is_int($index) )
				throw new \InvalidArgumentException(sprintf('Index "%s" already exists in this collection.', $index));
			
			for( $i = count($this->items) - 1; $i >= $index; $i--)
				$this->items[$i + 1] = $this->items[$i];
		}
		
		$this->items[$index] = $item;
	}
	
	/**
	 * Get all items in the collection as an array.
	 * 
	 * @return array The items in the collection.
	 */
	function all() {
		return $this->items;
	}
	
	/**
	 * Get the first item in the collection.
	 * 
	 * @return mixed
	 * @throws \OutOfBoundsException if the collection is empty.
	 */
	function first() {
		if( !$this->count() )
			throw new \OutOfBoundsException(sprintf('Cannot get first item: collection is empty.'));
		
		return $this->items[0];
	}
	
	/**
	 * Get the last item in the collection.
	 * 
	 * @return mixed
	 * @throws \OutOfBoundsException if the collection is empty.
	 */
	function last() {
		if( !$this->count() )
			throw new \OutOfBoundsException(sprintf('Cannot get last item: collection is empty.'));
		
		return end($this->items);
	}
	
	/**
	 * Get the number of items in the collection.
	 * 
	 * @return int The number of items in the collection.
	 */
	function count() {
		return count($this->items);
	}
	
	/**
	 * Check if an item with the given index exists.
	 * 
	 * @param int|string $index The index to check existance of.
	 * @return bool Whether the index exists.
	 */
	function index_exists($index) {
		return isset($this->items[$index]);
	}
	
	/**
	 * Get an item from the collection by its index.
	 * 
	 * @param int|string $index The index to the item to get.
	 * @return mixed The value corresponding to the specified index.
	 */
	function get($index) {
		return $this->items[$index];
	}
	
	/**
	 * Delete an item from the collection by its index.
	 * 
	 * @param int|string $index The index to the item to delete.
	 */
	function delete_index($index) {
		unset($this->items[$index]);
	}
	
	/**
	 * Delete an item from the collection.
	 * 
	 * @param mixed $item The item to delete.
	 */
	function delete($item) {
		$this->delete_index(array_search($item, $this->items));
	}
	
	/**
	 * Create a new item set with the same class name as this object.
	 * 
	 * @param array $items The new items to create a set with.
	 * @param bool $clone If TRUE, the item set will overwrite the current
	 *                    object's item set and not create a new object.
	 * @return Collection A collection with the new item set.
	 */
	private function set_items(array $items, $clone=true) {
		if( $clone )
			return new self($items);
		
		$this->items = $items;
		
		return $this;
	}
	
	/**
	 * Remove duplicates from the current item set.
	 * 
	 * @param bool $clone Whether to create a new object, or overwrite the current item set.
	 * @return Collection A collection without duplicates.
	 */
	function uniques($clone=false) {
		return $this->set_items(array_values(array_unique($this->items)), $clone);
	}
	
	/**
	 * Filter items from the collection.
	 * 
	 * @param callable $callback Function that receives an item from the collection and
	 *                           returns TRUE if the item should be present in the
	 *                           resulting collection.
	 * @param bool $clone Whether to create a new object, or overwrite the current item set.
	 * @return Collection A collection with the filtered set of items.
	 */
	function filter($callback, $clone=true) {
		return $this->set_items(array_values(array_filter($this->items, $callback)), $clone);
	}
	
	/**
	 * Find a subset of items in the collection using property value conditions.
	 * 
	 * The conditions are specified as an associative array of property names
	 * pointing to values. Only items whose properties have these values will
	 * appear in the resulting collection. The items in the collection have to
	 * be objects or associative arrays, or an error will occur.
	 * 
	 * @param array $conditions The conditions that items in the subset should meet.
	 * @param bool $clone Whether to create a new object, or overwrite the current item set.
	 * @throws \UnexpectedValueException If a non-object and non-array value is encountered.
	 * @return Collection
	 */
	function find(array $conditions, $clone=true) {
		return $this->filter(function($item) use ($conditions) {
			if( is_object($item) ) {
				// Object, match property values
				foreach( $conditions as $property => $value )
					if( $item->{$property} != $value )
						return false;
			} elseif( is_array($item) ) {
				// Array item, match array values
				foreach( $conditions as $property => $value )
					if( $item[$property] != $value )
						return false;
			} else {
				// Other, incompatible type -> throw exception
				throw new \UnexpectedValueException(
					sprintf('Collection::find encountered a non-object and non-array item "%s".', $item)
				);
			}
			
			return true;
		}, $clone);
	}
	
	/**
	 * Get an attribute value for each of the items in the collection.
	 * 
	 * The items are assumed to be objects with the specified attribute.
	 * 
	 * @param string $attribute The name of the attribute to get the value of.
	 * @return array The original item keys, pointing to single attribute values.
	 */
	function get_attribute($attribute) {
		return array_map(function($item) use ($attribute) {
			return $item->{$attribute};
		}, $this->items);
	}
	
	/**
	 * Use an attribute of each item in the collection as an index to that item.
	 * 
	 * The items are assumed to be objects with the specified index attribute.
	 * 
	 * @param string $attribute The name of the attribute to use as index value.
	 * @param bool $clone Whether to create a new object, or overwrite the current item set.
	 * @return Collection A collection object with the values of the attribute used as indices.
	 */
	function index_by($attribute, $clone=true) {
		$indexed = array();
		
		foreach( $this->items as $item )
			$indexed[$item->$attribute] = $item;
		
		return $this->set_items($indexed, $clone);
	}
	
	/**
	 * Execute a callback for each of the items in the collection.
	 * 
	 * @param callable $callback Function that receives an item from the collection.
	 * @param bool $clone Whether to create a new object, or overwrite the current item set.
	 * @return Collection A collection with return values of the callback calls.
	 */
	function map($callback, $clone=true) {
		return $this->set_items(array_map($callback, $this->items), $clone);
	}
	
	/**
	 * Execute an object method for each item in the collection.
	 * 
	 * The items are assumed to be objects with the specified method.
	 * 
	 * @param string $method_name The name of the method to execute.
	 * @param array $args Any arguments to pass to the method.
	 * @param bool $clone Whether to create a new object, or overwrite the current item set.
	 * @return Collection A collection with return values of the method calls.
	 */
	function map_method($method_name, array $args=array(), $clone=true) {
		$items = array();
		
		foreach( $this->items as $item )
			$items[] = call_user_func_array(array($item, $method_name), $args);
		
		return $this->set_items($items);
	}
}

?>