Wrapping simple WordPress objects

While you wouldn’t necessarily call the WordPress API an “object-oriented” API due to its heavy use of global function calls, the WordPress API still contains a lot of methods which return simple objects (that is, objects of type stdClass) or arrays of such objects. An example is the get_post method which returns an object representing the post, which maps the database columns for that post into a simple object.

The MasterPress API also contains a lot of methods to retrieve objects and collections of objects from your WordPress site, but the objects in this API are not simple. Specifically, a post, term, user, post type, taxonomy, and role are represented by the WOOF_PostWOOF_TermWOOF_UserWOOF_PostTypeWOOF_Taxonomy, and WOOF_Role classes respectively. These classes provide a lot of powerful methods for working with the object they represent, which simple objects can’t do.

WOOF_Wrap and the wrapping mechanism

If you visit the class reference page behind any of the class links in the previous paragraph, you’ll notice that many of them are derived from the class WOOF_Wrap. This class provides the common wrapping mechanism that the API uses to map simple WordPress API objects into the more fully realised versions in the MasterPress API. This is a very simple mechanism, but it is important to know how it works when you want to access properties of these objects.

Every class deriving from WOOF_Wrap simply has an internal $item property which is set to the standard WordPress API object at the time the MasterPress API object is created. For example, the method WOOF::post does the following:

  • Attempts to find the post specified, using the WordPress function get_post
  • If the post is found, a new WOOF_Post object is created, which sets the internal $item property to the result of get_post.

Accessing properties of wrapped objects

The interesting thing about the MasterPress API objects is that you can still access the properties of the simple objects they wrap, just as if our API objects directly contain the same properties as the wrapped simple object. These properties are not copied across though – they reside in the $item property as we described above.

This is one of the roles of the WOOF_Wrap class – it overrides PHP5’s __get magic method to forward any attempts to access these properties on our objects to the actual properties inside the wrapped objects. For example, in the code below, we access the post_title property of a WOOF_Post object returned by the WOOF::post method, which extracts the property from the internal $item property to give us our post title.

Example 1: Accessing post_title

Throughout this documentation, we refer to these simple object properties as “wrapped properties”.

Property Normalisation with class methods

In our previous example, we accessed the title of the post through the wrapped property post_title. The name of this property has a clear redundancy though – it’s clumsy that we have to type “post_title”, when we’re dealing with a post, we should be able to just type “title”. Even more annoying though is that if you look carefully at the properties that get_post returns, some of them have the “post_” prefix and some don’t, which probably means another codex page in your browser’s bookmarks (or you’ve got a better memory than we do).

In many cases like this, the MasterPress API provides actual class methods that allow us to use the shorter, less redundant property names. For example, the WOOF_Post class has the method WOOF_Post::title which returns the post title, so we can rewrite our example:

Example 2: Accessing the title

If you know your way around PHP, you may be thinking “Hold on, you said class methods. That looks like you’re accessing a title property“. If you don’t know your way around PHP, the reason you might ask this is that the “title” call in Example 2 does not have trailing braces (), which would inform PHP that you’re calling a method (function) on the class, and not just trying to access a property.

This is another feature of classes derived from WOOF_Wrap – they route unknown property access to a method of the same name with no arguments. Whether you like to use this feature is entirely up to you, you certainly can add braces to call the method directly if you want to (which would be marginally better performance-wise):

Example 3: One for the strict coders out there

Latest From the Blog

MasterPress 1.1.4 now available

MasterPress 1.1.4 is now available. This release contains an important compatibility fix for WordPress 4.5 to allow correct detection of the taxonomy term editing screen. Without this fix, any custom fields you have attached to custom taxonomies will not be shown at all in the editing form. Note also that MasterPress will still detect the edit screen correctly in… 

Plugin Requirements

MasterPress requires a minimum of WordPress version 3.4, MySQL 5, and PHP version 5.2.4.

We also recommend that PHP is configured to use a memory limit of 64MB per request (128MB may be required for sites with higher complexity).

This plug-in is not compatible with the WordPress.com hosted service.

Traversal