The succinct Wordpress Getter method and how it works

If you code for Wordpress on a daily basis you're probably quite familiar with post meta fields and the almighty get_post_meta function that is used to retrieve them. In case you need a quick refresher these are the function's documentations. Today I'll be writing about the global post's Getter method. Taking advantage of this method will allow you to change your meta data retrieval syntax from this:

get_post_meta( $post_id, 'customText', TRUE )

$post->customText

Introducing the Getter method

The Getter method was introduced to the WP_Post class in version 3.5 as part of revision 21559 and in its current incarnation is living happily inside class-wp-post.php. It takes advantage of the fact that WP_POST is a class and utilizes the magic method __get to address inaccessible properties in the WP_POST class as meta field keys. The Getter method then tries to retrieve the value of those post meta keys. Here's how the entire process looks:

 /*
 * Getter.
 *
 * @param string $key Key to get.
 * @return mixed
 */
public function __get( $key ) {
	if ( 'page_template' == $key && $this->__isset( $key ) ) {
		return get_post_meta( $this->ID, '_wp_page_template', true );
	}

	if ( 'post_category' == $key ) {
		if ( is_object_in_taxonomy( $this->post_type, 'category' ) )
			$terms = get_the_terms( $this, 'category' );

		if ( empty( $terms ) )
			return array();

		return wp_list_pluck( $terms, 'term_id' );
	}

	if ( 'tags_input' == $key ) {
		if ( is_object_in_taxonomy( $this->post_type, 'post_tag' ) )
			$terms = get_the_terms( $this, 'post_tag' );

		if ( empty( $terms ) )
			return array();

		return wp_list_pluck( $terms, 'name' );
	}

	// Rest of the values need filtering.
	if ( 'ancestors' == $key )
		$value = get_post_ancestors( $this );
	else
		$value = get_post_meta( $this->ID, $key, true );

	if ( $this->filter )
		$value = sanitize_post_field( $key, $value, $this->ID, $this->filter );

	return $value;
}

As you can see from the source code, when presented with a meta key the Getter method will ultimately call the get_post_meta function, which is exactly what we want. Using the Getter method to retrieve post meta data does require you to rely on the global $post (and that variable must exist or be declared before calling it). But if you've been using get_the_id() religiously to retrieve the post ID you should know that that function references to the global $post anyway, and will return boolean FALSE if that variable doesn't exist.

Pros and cons

The advantage of using the Getter method is obvious. Semantically it enables you to write succinct code that has less clutter and thus is easier to understand. There is however another, more subtle, advantage to using this method over our old companion get_post_meta(). Since you must refer to the Getter method via the global $post object it restricts your input and allows you to only pass string-type values to the __get magic method. A case that demonstrates the usefulness of this strictness is when someone tries to pass a falsy value as the meta key. Did you know that if the value of the $key parameter is falsy the get_post_meta will function will return the entire post meta array, even if $single is set to true?

get_post_meta( $post_id, FALSE, TRUE); //Returns all the post meta fields as an array.
get_post_meta( $post_id, '0', TRUE); //Will also return all the post meta fields as an array.

The Getter method on the other hand will always parse text into a string and will not accept numeric values, thus preventing such erroneous data from being returned.

$post->false; //Returns the value of the meta key false.
$post->'0' //Will generate a PHP parse syntax error.

It is still possible to pass the Getter method boolean values by using variable variables when needed.

Now let's go over this method one shortcoming - the Getter method strictly returns a single value. This can be observed on line 36 above:

$value = get_post_meta( $this->ID, $key, true );

Since the boolean value of the $single parameter is always set to TRUE. This can prevent multidimensional arrays from being retrieved correctly. To demonstrate this issue let's create a multidimensional array and then try to retrieve it.

//For this example we'll assume we have the following meta data structure inside a mata key called information.
$information = array(
	array(
		'name' => 'Johny Boy',
		'phone' => '999999'
	),
	array(
		'name' => 'Mason Hulk',
		'phone' => '8181123'
	),
);

//Now let's attempt to retrieve the value of the key using the two possible methods.
var_dump( get_post_meta(get_the_ID(), 'information', FALSE) );

//Result:
//array(2) {
//  [0]=>
//  array(2) {
//    ["name"]=>
//    string(11) "Johny Boy"
//    ["phone"]=>
//    string(6) "999999"
//  }
//  [1]=>
//  array(2) {
//    ["name"]=> 
//    string(10) "Mason Hulk"
//    ["phone"]=>
//    string(7) "8181123"
//  }
//}

var_dump( $post->information );

//result:
//string(5) "Array"

Overall it is clear that the Getter function is a useful addition to our Wordpress-coding arsenal. Its succinct and simple syntax means it helps code stay small and legible while providing almost the same functionality as the more senior get_post_meta() function.