Dynamic properties and string conversion
The MasterPress API is highly dynamic, in the sense that a lot of the code that you’ll write with the API will contain access to object properties and calls on object methods that don’t actually exist in the classes they’re based on. In addition, you can very often directly echo objects into your templates, particularly custom fields, and you’ll get output that is appropriate for the type of object you’re working with.
These features are made possible through the Magic Methods features of PHP 5, which allow developers to provide special methods to handle unknown property access or method calls on a PHP object, and automatic string conversion, among other things.
The availability of magic methods has only been guaranteed since WordPress started requiring PHP 5 as of version 3.2 – MasterPress takes great advantage of this new baseline requirement.
Understanding the benefits that magic methods bring is best illustrated with an example. Suppose we have a post type called “car” to encapsulate details about cars, and that this post type is setup in MasterPress to have a field set details with the following structure:
Figure 1: Details Field Set
Now, let’s look at code we could use to get this information into a single template for this post type, for example, this could be a code block inside the single-car.php template file.
Example 1: Theme code for the car details field set
There are a number of things to note here:
- Firstly, $wf->the uses the WOOF::the method to get the current post (lines 1 and 3), which returns a WOOF_Post object.
- $wf->the is a method call, but there are no braces “()” in both of the calls (lines 1 and 3). Our API allows this by routing a property access on “the” to the method “the”. Likewise for the “title” call, which is also a method (line 1). This is entirely optional, but it makes for very readable code.
- “details” (line 3) is certainly not a property of the, which is a WOOF_Post, but it will indeed retrieve our field set named “details” (that is the field set with front end name “details”). This is made possible by PHP’s __get magic method, which routes that property access to our field set.
- Likewise for photo (line 5), make (line 8), year (line 9), detailed_description (line 12), and other_models (line 16) – none of these are declared or assigned properties of $details ( a MEOW_FieldSetCollection ) but they will give us our field objects.
- The resize method of photo (line 5) returns a WOOF_Image object representing the resized image, but we are echoing this directly in our template, and we will indeed see a resized image. This is the work of PHP’s __toString magic method, which WOOF_Image implements to convert the image to an HTML tag.
- photo, year, detailed_description, other_models, are MEOW_Field objects, but echoing these gives us their string content – again, __toString is the magic behind this.
As a point of comparison, let’s write this code again with more explicit method calls, which should illustrate more of the magic happening behind the scenes.
Example 2: More verbose theme code for the car details field set
An important point to make about the dynamic properties is that you can always fallback to calling methods explicitly to get the information you want, and there is one specific scenario where you will need to…
Caveat: String conversion and variables.
As we’ve discussed PHP’s __toString magic method is called upon to auto-convert field objects and images into a string form that is more appropriate when echoing them into your templates. Importantly though, automatic string conversion in PHP will only be performed when the object is used in a context that requires conversion to a string – usually, indeed, when echoing a value.
Suppose that you need to write code that uses the value of a field in another operation – for example, let’s suppose you have an associative array of values, and you want to use the value of a field called “key” in a field set called “details” as a key into that array. You might be tempted to write code like this:
Example 3: __toString isn't always called...
This will not actually do what you think it might, since $key is never regarded as a string in this code, it is a MEOW_Field object. PHP can’t auto-convert it, since it doesn’t really know what your intention is, and will assume you’re trying to use the object as an object here. What you need to do instead is this:
Example 4: Explicitly obtaining field values to use in other code
That is, if you want to use a field value as a variable, you need to call the value method first to reduce it to a literal value.