Single Object Queries
MasterPress offers highly intuitive methods to access a single item from each of the major object-types in WordPress – posts, pages, attachments, terms, users, post types, taxonomies, and roles. These methods improve greatly on their counterparts in the standard WordPress API on the strength of one key feature – each of these methods has an $id argument which can be interpreted in multiple ways based on the type of argument you pass. This means you can lookup objects using more meaningful identifiers such as post slugs and term names, rather than having to deal with database IDs.
In addition to using specific methods to lookup single objects, the WOOF class also makes use of some clever handling of unknown properties and methods via PHP 5 magic methods.
All of these features will become more clear as we see examples of each object type in turn.
When objects don’t exist…
Before we discuss all of the single-object methods in WOOF it’s worth noting what happens when the object you’re looking for is not found in the current site. When an object cannot be found, all of the methods we discuss below will return a WOOF_Silent object indicating failure to find the object.
If you’re unfamiliar with the concept of Silent Failure in the MasterPress API, please refer to the section Silent Failure with the WOOF_Silent class for a complete overview.
The critical thing about the use of silent failure is that we need to use the exists method to check the result of the lookup like in the example below for a post lookup:
Example 1: Checking the lookup result
Note the incorrect example in the commented section – WOOF_Silent objects do not evaluate to false.
Retrieving a specific post, page, or attachment
We can lookup a single post with the WOOF::post method, which returns a MEOW_Post object. This method will attempt to find posts of the standard post type by default, but can be configured to lookup other custom post types via its $type parameter. Let’s look at a few examples:
Example 2: Finding a single post
The great feature of this method is that it can lookup items by either slug or ID, which is a great improvement over the standard WordPress way.
Looking up a page is very similar, and the method WOOF::page we use to do it is simply a preset on the WOOF::post method to lookup the page post type instead.
Example 3: Looking up a page
Looking up an attachment is also similar, by using the WOOF::attachment method, with the one difference being the return type of WOOF_Attachment.
The magic way to lookup posts from custom post types
Note line 7 in Example 2, where we looked up a car by passing the “car” post type name as the second argument. This is a perfectly sensible and easy way to lookup a car, but with a bit of magic method trickery in the WOOF class, we can do even better. WOOF overrides the __call magic method to allow us to “call” the post type name with the slug we’re looking for, to provide an even more intuitive interface:
Example 4: Finding a single car - the awesome way
It doesn’t get any easier than that. Behind the scenes, this call forwards the call on to the WOOF::post method we’ve just discussed.
Keep in mind the nature of the __call magic method – this will only be used if the method does not exist in the WOOF class already, so if you were to name a post type “author” for example, you’d need to call the “post” method directly, since WOOF already has an author method. In practice, it’s unlikely you will run into these situations too often though.
Retrieving a specific taxonomy term
We can lookup a single taxonomy term with the WOOF::term method, which returns a MEOW_Term object. This method takes a flexible $id argument, which can ba a term ID, slug, or even term name. The method call will also require the name of a taxonomy to be specified if you’re looking up a term via slug or name. Let’s look at a few examples:
Example 5: Finding a single term
Since WordPress includes 2 built-in taxonomies – category and post tag – we also provide methods to find those: WOOF::category and WOOF::tag respectively:
Example 6: Finding categories or tags
The magic way to lookup terms from custom taxonomies
Just like our post lookups (see above), we can also lookup a specific taxonomy term by “calling” the name of the taxonomy with the desired $id (which would usually be a slug or term name). So line 4 in Example 5 can be rewritten as:
Example 7: Find custom taxonomy terms - the awesome way
… and again, it doesn’t get much easier than this. Behind the scenes, this unknown method call is passed on to the WOOF::term method we’ve just discussed.
Retrieving a specific user
We can lookup a single user with the WOOF::user method, which returns a MEOW_User object. This method takes a flexible $id argument, which can ba a user ID, a username (login), or even an email address. Let’s look at a few examples:
Example 8: Finding a specific user
Note that there is no “magic” way to lookup users inside certain roles, since users don’t necessarily belong to a specific role in a WordPress site.
Retrieving a specific post type
We can lookup a single post type with one of two methods: WOOF::types, and its singular alias WOOF::type which both return a MEOW_PostType object. Both methods simply take the name of the post type as a single argument (WOOF::types can take a few different argument types to achieve different results, but a single post type name will give you a single post type). Let’s look at an example:
Example 9: Looking up a specific post type
Note that the example shows us looking up posts inside this post type, which is just one way to make use of a post type object.
WOOF also has a magic method way to access a post type – if we access the post type name as a property on $wf in either singular or plural form, we will also get that post type back:
Example 10: The magic way to access a post type
To go off on a slight tangent, one peculiar thing about WOOF_PostType is how it represents a single post type, yet extends WOOF_Collection. There’s one very good reason – it allows us to support direct iteration on the post type, which will simply loop over all of the posts (ordered in ascending title order). So we can improve Example 10 like this:
Example 11: Even more magic
Pretty neat, and we can even configure our query with different parameters – more on that in the Multiple Object Queries recipe.
Retrieving a specific taxonomy
We can lookup a single taxonomy with the method WOOF::taxonomy which simply takes the name of the taxonomy as an argument. Let’s look at an example:
Example 12: Looking up a single taxonomy
Note that the example shows us looking up terms inside this taxonomy, which is just one way to make use of a taxonomy object.
WOOF also has a magic method way to access a taxonomy too – if we access the taxonomy name as a property on $wf in either singular or plural form, we get that taxonomy back:
Example 13: Magic access to a taxonomy
Just like for post types, note how WOOF_Taxonomy represents a single taxonomy, yet extends WOOF_Collection. This allows us to support direct iteration on the taxonomy, which will simply loop over all of the terms in the taxonomy. So we can improve Example 13 like this:
Example 14: Even more magic
Retrieving a specific user role
We can lookup a single user role with the method WOOF::role which simply takes the ID of the role as an argument. Note the ID of a role is really like a “slug”, a lowercase version of the name of the role, and not an integer ID. Let’s look at an example:
Example 15: Looking up a user role
Note that the example shows us looking up users inside this role, which is just one way to make use of a role object.