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_Post, WOOF_Term, WOOF_User, WOOF_PostType, WOOF_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):