If you’ve spent much time reading the MODX Community Forum, You’ve probably read that there’s almost always more than one way to do something in MODX. If you’ve ever doubted that, this article should change your mind. In this article, we’ll see ten different ways to retrieve all the Resources in a Resource Group in the code of a Snippet or Plugin.
The methods in this article are more than just an exercise in showing that you can do things in many different ways in MODX. They serve to demonstrate the variety of methods that are available for getting information from your MODX database. They also showcase the genius of MODX-core-coder Jason Coward (opengeek), who created xPDO, the architecture used for all but one of the methods below.
If you can understand the examples below, you’re most of the way toward understanding how to use MODX and xPDO to interact with almost any MODX object.
Getting Started
Suppose you want to get all the Resources in a Resource Group. Maybe you want to display them a little faster than getResources would do it, or maybe you’re creating a utility Snippet to do something with each Resource such as adding a prefix to the alias or setting a TV value.
I’ve made up names for all ten methods to help keep them straight. I tried to make the names descriptive but was somewhat unsuccessful because I didn’t want to give them monstrously long names, and there are a lot of similarities between the methods.
The methods are all functions, so they can easily be dropped into your code. A second reason for this is that in my next article, we’ll be looking at benchmarking the methods to see how fast they are, and having them as functions will make that easier. Each function takes four arguments, two of which are optional. The first is the $modx object. The second is groupId, the identifier for the Resource Group. We’ll look at the other arguments after the first example below.
The Tag
This tag is what you would use to call a Snippet called “GetGroupResources” containing any of the functions below.
[[!GetGroupResources? &groupId=`12`]]
The Snippet tag takes only one property—the Name or ID of the Resource Group.
Important: For the useAllDocs methods (the first two), the groupId will be the Group’s name. For all other methods, it will be the Group’s ID.
The Group’s ID is shown in parentheses after the name of the Group on the left side of the panel reached by selecting “Security”, then “Resource Groups” in the MODX Manager’s Main Menu.
The Snippet
To use any method below, the Snippet will look like this (with the addition of the function you want to use):
<?php
/* GetGroupResources snippet */
/* Set linefeed for browser and command line */
$lf = php_sapi_name() === 'cli'
? "\n"
: '<br>';
/* Make code work in MODX 2 and MODX 3 */
$prefix = $modx->getVersionData()['version'] >= 3
? 'MODX\Revolution\\'
: '';
$groupId = $scriptProperties['groupId'];
/* Call the function */
$output = functionName($modx,$groupId, $prefix, $lf);
return $output;
functionName($modx,$groupId, $prefix, $lf) {
/* Function code here */
}Just drop in the function, and change “functionName” to the name of the function. As written below, the functions will get the Resources in the Resource Group but won’t do anything with them other than add their pagetitles to the output. You can create the output inside the function and return it as a string (like getResources does), or you can return the array of modResource objects and create the output in your main code.
As noted in the comments, the $prefix allows the code to run in both Revo 2 and Revo 3. The functions will work fine without it but in Revo 3, a deprecation notice will be placed in the Deprecations Log, which slows things down.
The $lf variable is a linefeed. It’s used to make the functions work in a MODX Snippet, or from the command-line. For testing, I run the code in my code editor, PhpStorm. Without the $lf variable, the <br> tags are displayed literally and the output is crammed together in a single line.
The “\n” character must be in double quotes, not single quotes. In single quotes, it would be displayed literally, rather than creating a linefeed.
The following sections contain the functions and some information about how they work.
useAllDocs Method
The most obvious way to get a Resource Group’s Resources is to get all the Resources on the site, then walk through them one at a time, and check to see if they are in the group, using isMember('groupName').
Important: As I mentioned above, with this method, and the next one, the $groupId must be set to the name of the Resource Group. In all other methods it should be the id of the Resource Group (adjust the &groupId property in the tag accordingly).
function useAllDocs($modx, $groupId, $prefix = '', $lf = '<br>') {
$output = '';
$docs = $modx->getCollection($prefix . 'modResource');
foreach ($docs as $doc) {
if ($doc->isMember($groupId)) {
$output .= $lf . $doc->get('pagetitle');
}
}
return $output;
}The $output statement above (and in the other methods) is just to make sure the code works. You’d either replace it with whatever action you want to perform on each Resource and any information you want to display, or remove it and return the array holding the Resources.
As you might suspect, getting the ResourceGroup’s Resources by getting all the Resources on the site is not only very slow (for a Resource Group with a lot of Resources, it might time out), it wastes a lot of time and server capacity by getting a large number of Resources that we don’t need and won’t ever see.
The useAllDocs_iterator Method
This is the same as the function above, except that it uses getIterator() instead of getCollection(). The getIterator() method works exactly like the getCollection() method except that it uses less memory by not retrieving the full modResource objects until they’re used for something.
function useAllDocs($modx, $groupId, $prefix = '', $lf = '<br>') {
$output = '';
$docs = $modx->getIterator($prefix . 'modResource');
foreach ($docs as $doc) {
if ($doc->isMember($groupId)) {
$output .= $lf . $doc->get('pagetitle');
}
}
return $output;
}The useNoAliases Method
As the name suggests, this method uses no aliases at all (we’ll see aliases used and explained in examples below).
First, we get the modResourceGroupResource objects that are related to our Resource Group with $modx->getCollection(). The “where” line sets the criteria for the search by asking for modResourceGroupResource objects with a document_group field that matches the Resource Group’s ID ($groupId);.
function useNoAliases($modx, $groupId, $prefix = '', $lf = '<br>') {
$output = '';
$query = $modx->newQuery($prefix . 'modResourceGroupResource');
$query->where(array('document_group' => $groupId));
$rgrs = $modx->getCollection($prefix . 'modResourceGroupResource', $query);
foreach ($rgrs as $rgr) {
$resource = $modx->getObject($prefix . 'modResource', $rgr->get('document'));
$output .= $lf . $resource->get('pagetitle');
}
return $output;
}What the Heck Is a modResourceGroupResource?
The code above is fairly self-explanatory but the $rgrs variable needs some explanation.
If there can only be one value for something associated with a Resource, such as Parent, Template, pagetitle, or alias, MODX stores the information with the Resource in a single field of that Resource’s row in the modx_site_content table.
That doesn’t work, though, when there can be more than one value to store. Resources can belong to more than one Resource Group (just as Users can be in more than one User Group), and a Resource Group can contain more than one Resource. This is a “many-to-many” relationship. In those cases, MODX stores the information in an “intersect” object, which in this case has the class modResourceGroupResource.
The modResourceGroupResource object has a document field containing the ID of a Resource, and a document_group field containing the ID of the Resource Group. That’s how MODX knows which Resources are in which Resource Groups. More on this below.
Once we have the modResourceGroupResource objects, we walk through the retrieved objects and get each Resource with $modx->getObject() using the Resource’s ID, ($rgr->get('document')).
UseOneAlias Method
We’ll get to this method in a bit, but first, some information about aliases.
You’re almost certainly familiar with standard MODX objects like modResource, modUser, modResource, and modResourceGroup. You may also be familiar with “intersect” objects like modUserGroupUser, modResourceGroupResource, and modPluginEvent (if not, you’ll learn about them later in this article).
Aliases, on the other hand, are not MODX objects. Instead, they are entities (strings, actually) that belong to specific MODX objects and point to other MODX objects that are related to the original object. For example, the modUser object has a Profile alias that points to that user’s related modUserProfile object. When MODX (xPDO actually) sees the Profile alias, it knows that the user’s ID is stored in the internalKey field of the modUserProfile object.
If we have the user object in the $user variable, we can use the Profile alias to get the users Profile with $user->getOne('Profile'). MODX knows where to find it.
Similarly, we can get the Children of a Resource by calling resource->getMany('Children');. In this case 'Children' is the alias.
Aliases always start with a capital letter. When used with getOne(), they are always singular. When used with getMany(), they are always plural. We’ll see lots of examples below.
Now, back to the UseOneAlias method.
In this method, we get the Resource Group first, using its ID ($groupId). Once we have it, we get its modResourceGroupResource objects using its getMany() method with the 'ResourceGroupResources' alias as an argument. The ResourceGroupResources objects hold the ID of the Resource in the 'document' field. From there, we can walk through those objects and get each Resource in the Resource Group by calling $modx->getObject() with the Resource’s ID.
function useOneAlias($modx, $groupId, $prefix = '', $lf = '<br>') {
$output = '';
$resourceGroup = $modx->getObject($prefix . 'modResourceGroup', $groupId);
$rgrs = $resourceGroup->getMany('ResourceGroupResources');
foreach ($rgrs as $rgr) {
$resource = $modx->getObject($prefix . 'modResource', $rgr->get('document'));
$output .= $lf . $resource->get('pagetitle');
}
return $output;
}Resources are stored in one table and Resource Groups are stored in another table. As we mentioned above, the connections between the two are stored in a third table (in this case, the modx_document_groups table). Each row in that table stores a modResourceGroupResource intersect object that just contains the ID of the Resource Group and the ID of the Resource. In that table, the Resource ID is in the document field and the Resource Group ID is in the document_group field.
So, if a Resource belongs to six Resource Groups, there will be six rows in the modx_document_groups table, one for each Resource Group the Resource belongs to. Each row is a modResourceGroupResource object as far as MODX is concerned. The document field would contain the ID of the Resource, and the document_group field would contain the ID of the Resource Group.
The MODX intersect objects are always named using the names of the two objects being connected, modResourceGroupResource, modPluginEvent, modElementPropertySet, modUserGroupMember, and so on.
Once we have the modResourceGroup object, we can use its ResourceGroupResources alias to get its related records in the modx_document_groups table. Only the records that have the $groupId of the Resource Group in their document_group field will be retrieved.
Once we have them, we loop through them and get the Resource itself like this:
$modx->getObject($prefix . 'modResource', $rgr->get('document'));
In the code above, the second argument will be the Resource’s ID, which is stored in the document field of the modResourceGroupResource ($rgr).
UseTwoAliases
This method is very similar to the one above, the difference is that in this method, we use a second alias to get each modResource object instead of getting it with getObject() We’re using the ResourceGroupResources alias with getMany() as we did in the method above to get the modResourceGroupResource objects. But then, we walk through the modResourceGroupResource objects and, for each one we use its Resource alias to get its modResource object with $rgr-getOne('Resource').
function useTwoAliases ($modx, $groupId, $prefix = '', $lf = '<br>') {
$output = '';
$resourceGroup = $modx->getObject($prefix . 'modResourceGroup', $groupId);
$rgrs = $resourceGroup->getMany('ResourceGroupResources');
foreach ($rgrs as $rgr) {
$resource = $rgr->getOne('Resource');
$output .= $lf . $resource->get('pagetitle');
}
return $output;
}All intersect objects in MODX have two getOne() calls, one to get each of the two objects they point to. We could have retrieved the Resource Group object, if we wanted it, with this code:
$rgr->getOne('ResourceGroup');
But we don’t need that, because we want to process the Resources, not the Resource Groups.
The aliases used to get the related objects from the Intersect Objects are documented here. Here’s a direct link to the modResourceGroupResource one. You can see the fields, and the ResourceGroup and Resource aliases.
There’s also a link near the top of that page to the Revo 3 version of the page, though the field names are the same.
The useGetCollectionModRgr Method
In this method, we don’t get the Resource Group at all. Instead, we query the modx_document_groups table directly (which holds the modResourceGroupResource objects). We use getCollection() to get only the modResourceGroupResource objects that have our Resource Group’s ID in their document_group field. Then we walk through them and get their related modResource object directly using the Resource alias (which, internally, uses the Resource’s ID held in the document field) of the modResourceGroupResource object).
function useGetCollectionModRgr ($modx, $groupId, $prefix = '', $lf = '<br>') {
$output = '';
$query = $modx->newQuery($prefix . 'modResourceGroupResource');
/* Set the criteria for the search based
* on the &groupId variable */
$query->where(array('document_group:=' => $groupId));
/* Additional criteria like 'published' => true could go here
with more $query->where() statements */
/* Get the modResourceGroupResources */
$rgrs = $modx->getCollection($prefix . 'modResourceGroupResource', $query);
foreach ($rgrs as $rgr) {
/** @var $rgr modResourceGroupResource */
$resource = $rgr->getOne('Resource');
$output .= $lf . $resource->get('pagetitle');
}
if (!empty($output)) {
$output = $lf . $output;
}
return $output;
}The useRgGetResources Method
This method is a little different and somewhat simpler. The modResourceGroup class has a method called getResources() that gets all the modResource objects in the Resource Group. First, we get the modResourceGroup object using its ID ($groupId), then we get all its Resources with $resourceGroup->getResources().
function useRgGetResources($modx, $groupId, $prefix = '', $lf = '<br>') {
$output = '';
$resourceGroup = $modx->getObject($prefix . 'modResourceGroup', $groupId);
$resources = $resourceGroup->getResources();
foreach ($resources as $resource) {
$output .= $lf . $resource->get('pagetitle');
}
return $output;
}This method is not available for most other MODX objects, which don’t have a similar method.
The useInnerJoin Method
I owe a huge debt of gratitude to MODX Community member (halftrainedharry) for helping me make this method work. His solution also helped me get the following method working (useGetCollectionGraph).
If you were using MYSQL to get the Resource Group’s Resources, you’d probably use an inner join to make the query faster. xPDO has this capability as well, and we use it in this method.
function useInnerJoin($modx, $groupId, $prefix = '', $lf = '<br>') {
$output = '';
$query = $modx->newQuery($prefix . 'modResource');
$query->innerJoin($prefix . 'modResourceGroupResource', 'ResourceGroupResources');
$query->select($modx->getSelectColumns($prefix . 'modResource', $prefix . 'modResource', '', ['id', 'pagetitle', 'introtext', 'description']));
$query->select($modx->getSelectColumns($prefix . 'modResourceGroupResource', 'ResourceGroupResources', '', ['document', 'document_group']));
$query->where(['ResourceGroupResources.document_group' => $groupId]);
$query->prepare();
$result = $modx->getCollection('modResource', $query);
foreach ($result as $resource) {
$output .= $lf . $resource->get('pagetitle');
}
return $output;
}Basically, the method performs an INNER JOIN that joins the modx_site_content table (which contains the modResource objects, and the modx_document_groups table, which contains the modResourceGroupResource objects.
The join criteria selects only the rows where the Resource ID is in the document field of the modResourceGroupResource and the document_group field contains the ID of our Resource Group.
Notice that we use the ResourceGroupResources alias of the modResourceGroup to make the connection. All inner joins in xPDO make use of an alias that connects the objects we’re interested in.
The useGetCollectionGraph Method
The MODX (actually xPDO) getCollectionGraph method lets you get objects and their related objects with a single query. It’s difficult to explain but is quite fast and very convenient once you get it working. The beauty of this method is that once you’ve made the getObjectGraph call, you have the Resources you want in a PHP array with no further steps.
Like the previous method, this method uses the related object’s alias, and any criteria you need to filter the results, to create the SQL for the query, which will automatically contain the appropriate join.
The “where” line makes sure we only get modResourceGroupResource records where the document_group field matches the ID of our Resource Group ($groupId).
The call to getObjectGraph uses the Resource alias of the modResourceGroupResource object in a JSON string ('{Resource:{]]') to pull in the related Resources. If we also wanted the associated modResourceGroup object, we could use this string: '{Resource:{}, ResourceGroup:()}' but we have no use for the Resource Group, and it would slow things down very slightly.
Getting multiple related objects can be useful at times. For example, the ClassExtender Extra can create another user-related object (and a custom DB table for it) called UserData containing user information that is not in the modUser or modUserProfileobjects. To get all fields related to the user, you can query the UserData object and use the two aliases of the UserData object with this JSON string '{"Profile":{},"User":{]]'. In this case, you call getObjectGraph(), instead of getCollectionGraph(), because this is not a many-to-many relationship. Each user has only one UserData object and one modUserProfile object.
Here’s the code of the useGetCollectionGraph method:
function useGetCollectionGraph($modx, $groupId, $prefix = '', $lf = '<br>') {
$output = '';
$query = $modx->newQuery($prefix . 'modResourceGroupResource');
/* $query->select($modx->getSelectColumns('modResource', 'modResource',
'', array('id', 'pagetitle', 'introtext', 'description')
));
$query->select($modx->getSelectColumns('modResourceGroupResource', 'ResourceGroupResources', '', array('document', 'document_group')
));*/
$query->where(array($prefix . 'modResourceGroupResource.document_group' => $groupId));
$rgrs = $modx->getCollectionGraph($prefix . 'modResourceGroupResource','{Resource:{]]', $query);
foreach($rgrs as $rgr) {
$output .= $lf . $rgr->Resource->get('pagetitle');
}
return $output;
}The two commented-out “select” statements allow you to limit the fields retrieved. The second one is not much use because the modResourceGroupResource object only has three fields, and you need two of them. Without the “select” statements, all object fields are retrieved, though the method is so fast, that the time you’d save by selecting the fields you want would be fairly trivial.
The usePDO Method
This method bypasses xPDO altogether and uses PHP’s PDO methods to get the Resource Group’s Resources with a MySQL query. This method is blindingly fast, and if you know MySQL, it’s very easy to use. It has one drawback, which we’ll discuss below the code.
Basically, you just write a standard MySQL query and pass it to $modx->query() like this:
$stmt = $modx->query('MySQL Here');
Then, you use PDO’s $stmt->fetchAll(PDO::FETCH_ASSOC) to fetch the results.
Once you have the results (as a PHP associative array of Resources and their fields) you just walk through them and display the results you want.
function usePDO($modx, $groupId, $prefix = '', $lf = '<br>') {
$output = '';
$stmt = $modx->query("SELECT
resource.id,
resource.pagetitle,
resource.introtext,
resource.description,
docgroups.document,
docgroups.document_group
FROM modx_site_content AS resource
INNER JOIN modx_document_groups AS docgroups
ON resource.id=docgroups.document AND docgroups.document_group= {$groupId}");
if ($stmt) {
$results = $stmt->fetchAll(PDO::FETCH_ASSOC);
foreach ($results as $doc => $fields) {
$output .= $lf . $fields['pagetitle'];
}
} else {
throw new Exception("SQL Failed");
}
return $output;
}The “select” part of the query in the code above can be used to specify the fields you actually need. This will make the query faster than it would be if it pulled all the many fields of the modResource object. Don’t change the two docgroups lines because you’ll need both of those fields.
Earlier, we mentioned a drawback of this method. Unlike the other methods, the results are not an array of modResource objects. Instead, they are an array of arrays, with each inner array containing the Resource fields and their values. That means you can’t modify the Resource and save it to the database unless you take the further step of getting each Resource by using its id field., which slows things down considerably (roughly by a factor of 60), making it slower than many of the xPDO methods.
If you need the Resource objects, you can speed it up considerably by putting the Resource IDs in an array inside the foreach($results as $doc) loop, then making a single query asking for Resources that have an ID in that array, like this :
$ids = array();
foreach ($results as $doc => $fields) {
$ids[] = $fields['id'];
}
$q = $modx->newQuery($prefix . 'modResource');
$q->where(array('modResource.id:in' => $ids));
$resources = $modx->getCollection($prefix . 'modResource', $q);
foreach($resources as $resource) {
$output .= $lf . $resource->get('pagetitle');
}This modification makes the method faster than any of the above methods except useGetCollectionGraph. Using PDO for the second query as well would likely make it the fastest method. Doing that is left as an exercise for the reader.
Without any modification, this method is great if all you want to do is display the Resource fields and don’t need the Extra features of getResources or PdoResources. It’s approximately 15 times faster than the next fastest method above.
How Do the Methods Compare in Performance
In my next article, we’ll look at benchmarking. We’ll see some code that measures and reports the performance of each of the methods above. You may be surprised at some of the results. I was surprised by some of them as well.
Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.