xPDO.getObjectGraph
Last edited by Wayne Roddy on Feb 10, 2015.
xPDO::getObjectGraph
Retrieves a single object instance and related objects defined by a graph, by the specified criteria.
The graph can be an array or JSON object that describes relations from the specified $className.
The criteria can be a primary key value, an array of primary key values (for multiple primary key objects) or an xPDOCriteria object. If no $criteria parameter is specified, no class is found, or an object cannot be located by the supplied criteria, null is returned.
In order to use getObjectGraph effectively, you need to understand the data model behind your object. It pays to keep one finger on the XML schema file that defines your objects and their relations. If you attempt to join on another object when that relationship does not exist, this method will fail!
Syntax
API Docs: http://api.modx.com/xpdo/xPDO.html#getObjectGraph
xPDOObject|null getObjectGraph (string $className, array|str $graph, [xPDOCriteria|array|str|int $criteria = null], [bool|int $cacheFlag = true])
Example using Template Variables
Before you try using this method to walk through your custom data model, here's an example of how it might be used to retrieve built-in MODX objects.
Example of what NOT to do
You may be tempted to retrieve MODX Template Variable values by using getObjectGraph:
// DO NOT DO THIS!!! TV's have some special methods $page = $modx->getObjectGraph('modResource', '{"TemplateVarResources":{}}',123); $output = ''; foreach ($page->TemplateVarResources as $tv) { $output .= $tv->get('value'); // or do something else with this value } return $output;
It's critical to understand that even though you may think you are retrieving a single object, that object may be joined to a collection of related objects.
You'll notice that if you use the above example to get your TV values, you'll sometimes get weird JSON encoded values that are basically unusable! The lesson? DO NOT RELY ON getObjectGraph to retrieve Template Variable values! This is important: although you may be able to retrieve some values this way, the default TV values are stored in distant corners of the database, so you should instead rely on the getTVValue helper function.
Use the getTVValue Helper Function
Instead, use the helper functions getTVValue and setTVValue:
$page = $modx->getObject('modResource', 123); return $page->getTVValue('my_tv_name');
Example
Get a Box object with ID 134, along with related BoxColors and Color instances already loaded.
$box = $xpdo->getObjectGraph('Box', array('BoxColors' => array('Color' => array())), 134); foreach ($box->getMany('BoxColors') as $boxColor) { echo $boxColor->getOne('Color')->get('name'); }
The same example using a JSON-format $graph parameter.
$box = $xpdo->getObjectGraph('Box', '{"BoxColors":{"Color":{}}}', 134); foreach ($box->getMany('BoxColors') as $boxColor) { echo $boxColor->getOne('Color')->get('name'); }
The main benefit of using getObjectGraph is to retrieve data from related tables in a single query. No additional queries are executed when getMany() or getOne() are called on the related objects that are already loaded from the $graph.
See Also
- Retrieving Objects
- xPDO.getObject
- xPDO.getCollection
- xPDO.getCollectionGraph
- xPDO.getIterator
- [xPDO.load]
- xPDO
Suggest an edit to this page on GitHub (Requires GitHub account. Opens a new window/tab).