Retrieving Objects

To get Objects in xPDO, there are a variety of methods. The two basic themes we'll concern ourselves with here is in the differences between an Object, a Collection, and an Iterator.

An Object is a single xPDOObject, nothing more, nothing less. It is retrieved via xPDO::getObject(). Think of it like one row in a database table.

A Collection is an array of xPDOObjects. They are retrieved via xPDO::getCollection. Think of it as a list of rows in a table.

An Iterator is a special kind of Collection which is accessed sequentially so that all of the rows and objects representing them are not loaded into memory all at once.

xPDO::getObject

getObject takes 3 arguments: $className, $criteria, and $cacheFlag. The first argument is the class name you'd like to retrieve; the second is the criteria by which you'd like to search for it; and the final argument is the caching option for the object.

If an integer value is provided for the $cacheFlag argument, then it specifies the time to live in the object cache; if cacheFlag === false, caching is ignored for the object and if cacheFlag === true, the object will live in the cache indefinitely.

Back to $criteria. This can be one of 3 things:

A primary key value
An array of field(s)
An xPDOCriteria object or derivative.

We'll get back to the third option later. First, an example of the first option:

$box23 = $xpdo->getObject('Box', 23);

If an object doesn't exist, it will return 'null'.

Let's say we wanted to grab an object that had multiple Primary Keys. We could do so using the array of fields option:

// GroupUser is a table with 2 PKs - 'user' and 'group'
$gu = $xpdo->getObject('GroupUser', array(
   'user' => 12,
   'group' => 4,
));

Or, lets say we just wanted to grab the first Box object that SQL would find in natural order with a width of 150:

$bigbox = $xpdo->getObject('Box',array('width' => 150));

We'll discuss the third option, xPDOCriteria, later in the xPDOQuery and xPDOCriteria sections.

xPDO::getCollection

xPDO::getCollection takes the same three arguments as getObject; except the $criteria field must be either an array or xPDOCriteria object.

Lets say we wanted to grab all the Box objects with width of 14:

// assume we have 3 boxes, with colors 'red','blue' and 'yellow'
$boxes = $xpdo->getCollection('Box', array(
  'width' => 14,
));
foreach ($boxes as $box) {
   echo $box->get('color')."\n";
}
// this would print:
// red
// blue
// yellow

xPDO::getIterator

The xPDO::getIterator method is identical to xPDO::getCollection except that you can only access one xPDOObject from the Collection of rows at one time. If you need access to all of the objects/rows at once, use getCollection. Otherwise, it is more efficient in terms of memory usage, to use getIterator to loop through a Collection of xPDOObjects.

The code for iterating over the Box objects with width of 14 is almost identical to that of getCollection:

// assume we have 3 boxes, with colors 'red','blue' and 'yellow'
$boxes = $xpdo->getIterator('Box', array(
  'width' => 14,
));
foreach ($boxes as $box) {
   echo $box->get('color')."\n";
}
// this would print:
// red
// blue
// yellow

Note that the index for each object when iterated over is not the primary key, unlike the array index when using getCollection.

xPDO::newQuery

One of the most powerful parts of xPDO is its ability to create complex queries in a simple fashion using the xPDOQuery wrapper. This class lets you build SQL queries using OOP methods, and extends the xPDOCriteria class - so you can pass its instance right into getObject or getCollection calls. The newQuery function creates an xPDOQuery object, and takes 3 parameters:

$class - The class name to create the query for.
$criteria - This is optional; but should you want to feed it with a criteria, you can.
$cacheFlag - Similar to getObject's cacheFlag, you can specify the caching behavior for this query.

So let's create a demonstration query using xPDOQuery, that will grab the first 5 Boxes with width of 5 and an owner with ID 2, sorted by their name. Our BoxOwner table is a many-to-many relationship table with two fields: box and user, which reference the corresponding Box and User.

$c = $xpdo->newQuery('Box');
$c->innerJoin('BoxOwner','Owner'); // arguments are: className, alias
$c->where(array(
   'width' => 5,
   'Owner.user' => 2,
));
$c->sortby('name','ASC');
$c->limit(5);
$boxes = $xpdo->getCollection('Box',$c);

Now, say we want to grab that same query, but grab it by the owner's name. We can chain the innerJoin queries to create a more complex query. Let's also grab the 2nd 5 Boxes:

$c = $xpdo->newQuery('Box');
$c->innerJoin('BoxOwner','Owner'); // arguments are: className, alias
$c->innerJoin('User','User','Owner.user = User.id');
// note the 3rd argument that defines the relationship in the innerJoin

$c->where(array(
   'Box.width' => 5,
   'User.user' => 2,
));
$c->sortby('Box.name','ASC');
$c->limit(5,5);
$boxes = $xpdo->getCollection('Box',$c);

You'll also see that the sortby and where functions can take dot syntax on their parameters; they can prefix their columns - and sometimes have to to prevent collisions! - with alias names.

More information on xPDOQuery can be found here.

xPDOCriteria

xPDOCriteria is a base SQL criteria class, and can be used to create complex SQL queries that don't necessarily fit into abstraction paradigms. Examples of this could be HAVING clauses, UNIONs, subqueries or other complex and custom queries.

One downside to using xPDOCriteria is that it's not, by principle, database-agnostic since you're providing it with the SQL. If you plan on using other types of databases in the future, make sure to encapsulate any xPDOCriteria-based queries in Object classes that can be overridden per SQL platform.

xPDOCriteria uses PDO formatting for it's SQL statements and bindings. An example of using xPDOCriteria to grab a list of Boxes with a width of greater than 4, limiting to only 10:

$boxTable = $xpdo->getTableName('Box');
$query= new xPDOCriteria($xpdo,'
    SELECT * FROM '.$boxTable.'
    WHERE `width` > :width
    LIMIT 10
',array(
  ':width' => 4,
));
$boxes = $xpdo->getCollection('Box',$query);

Graphs

Under construction

xPDO::getObjectGraph

Under construction

xPDO::getCollectionGraph

Please view the dedicated page: getCollectionGraph