Value Object Collections

Collections are array like classes that are used to hold multiple instances of a single type of VO. Unlike an array though, the collections know what kind of class they're designed for and won't allow the wrong type to be added to them. The collections can also be iterated over in a foreach loop, like arrays, and provide other convenience methods.

It should also be noted that the collection objects use lazy instantiation. Each collection returned by a query contains the raw data and object data. When a query for a table is retrieved using its selector object, the raw result data is given to the collection in its constructor. The collection does not construct any VO instance until it is specifically requested. This prevents resources (CPU cycles and memory) from being used unless they are actually needed.

This may not benefit much in a lot of scripts, but if you fetch 10000 results and are only looking for the first match (at index #i), then only i rows are converted to objects and the resources needed to instantiate the other 10000 - i objects remain free to do other work.

Getting a collection via the Table's Selector class

Our first collection will be the result of selecting a single `user_id` from the `user` table via a “UserSelector” instance. Selectors always return a collection, so that there's no doubt about the return type of the fetch() method (single VO or multiple).

Note that the last line of output “Built UserVO Objects (Total = 0 of 1):” is saying that the collection has data for 1 UserVO object and has instantiated 0.

A larger collection via the table selector

Now we will make a query on the table that will return multiple rows.

Getting objects from a collection and adding objects to a collection.

Now we will put a few of the results from this collection into a new empty collection.

The random() method of the Collection classes also optionally accepts an integer parameter n. If given, the random method will return a new Collection instance of the same type with n random VO instances already in it.

Now we can echo both collections to get a look at what is in them. We removed two VOs from the previous collection, so the total objects should be two less than above. (We only copied the random VO)

Using the collection in a foreach loop

We'll loop through the $freshCollection of users set their usernames, update them in the database, and then remove them from the collection.

Note that the raw array values don't match the object array values afterward, but this is alright, because the collection will only ever use the built objects, unless it is instantiating new VOs.

We can also reverse the direction that the collection iterates in.

Getting Collections from Collections

As mentioned before, if random() is supplied a positive integer n, it will return a new collection with n random VOs pre-loaded from the original collection.

Collections also have a filterAryWith($funcName) method that accepts a function name and uses it to build a new collection. filterWith() will test each VO that it contains and if $funcName($vo) returns true, then that $vo will be included in the filtered collection that is returned.

Collections also have a filterRawWith($funcName) method, which is identical to filterWith(), except that filterRawWith() passes the raw arrays to $funcName and does not instantiate the objects to be included. This will save overhead if the actual VOs never need to be constructed. If they are ever needed, the returned collection will instantiate the objects just as the original would have.

Using Collections in a for loop and emptying them

Now we will empty the collection one at a time.
Note: This does not effect the database. It simply pulls instances out of the collection.

“Resetting” and Reusing a Collection

We can also replace the contents of a collection with an array of VOs or raw VO data. First we will make an ordinary array of VOs, then we will use that array to replace the contents of the $resultCollection instance.

$weakVoAry = array();
foreach($filteredCollection as $vo){
	$weakVoAry[] = $vo;
}
$resultCollection->replaceVOs($weakVoAry);
echo $resultCollection;

...and we'll empty the first collection with the built in removeAll() method

$resultCollection->removeAll();
echo $resultCollection . "<br/>";

End of Script