If you’ve spent any time hacking WordPress, you know that the WP_Post object is a critical part of the WordPress infrastructure. It contains all the data associated with a given post. However, WordPress gives you many ways of interacting with this object, and what method you use depends on what you need to do with the post. For instance, if you’re handling post objects in a template, you generally want to echo the post values to the page. However, if you’re writing a plugin, you must return a string that contains the processed post variables instead. The WordPress API is maddeningly inconsistent in handling these post objects, so I’ve put together a cheat sheet to make dealing with the funkyness easy.
As far as which method to use, it’s generally considered “bad form” in programming to access the fields of an object directly, if get/set methods are provided to interact with them. That said, WordPress (and PHP in general…) don’t really seem to enforce this. Still, the fields in an object are generally considered subject to change.
Post Attribute & Function Table
|WP_Post||Echo Function||No Echo Function|
|Author Name||n/a (post_author is an ID)||the_author();||get_the_author();|
|Publish Date/Time||post_date or post_date_gmt||the_date( $format, $before, $after, TRUE);||the_date( $format, $before, $after, FALSE); or get_the_date( $d );|
|Modified Date/Time||post_modified or post_modified_gmt||the_modified_date( $d, $before, $after, TRUE);||the_modified_date( $d, $before, $after, TRUE); or get_the_modified_date($d);|
|Title||post_title||the_title( $before, $after, TRUE);||the_title( $before, $after, FALSE); or get_the_title($ID);|
|Permalink||n/a||the_permalink();||get_permalink( $ID );|
|Thumbnail||n/a||the_post_thumbnail( $size, $attr );||get_the_post_thumbnail( $ID, $size, $attr );|
|Content||post_content||the_content( $more_link_text, $stripteaser );||get_the_content( $more_link_text, $stripteaser );|
- For the “WP_Post” column, you can get a
$postobject with a function like
get_post(), and then access the attribute by doing something like
$post->IDor similar. You can then use it as you see fit.
- For the “Echo” column, this function (or function/argument set) will echo the value to the page automatically, which is better for Templates.
- For the “No Echo” column, this function (or function/argument set) will return the value instead of echoing it.
Some functions can only be used inside a “WordPress Loop” as they rely on global variables that are set up by this loop. Many of the “No Echo” functions can be called with an
$ID argument, which can be
NULL inside a “WordPress Loop” in order to query the current
$post, or with a valid ID outside of a “WordPress Loop” in order to get an arbitrary post’s values.
The function naming and arguments tend to make my head spin. Sometimes, you just have to prepend “get_” to the function name in order to keep it from echoing automatically. Other times, “get” replaces “the.” Sometimes the function is the same, but there is an optional $echo argument that can be used. Sometimes you can pass an $ID, but not always. I didn’t include other fields, like “title attribute” in this table, but that function takes an *array* with arguments instead. This is one area where I’d like to see some standardization, and perhaps deprecation of some of the odder corner case functions. Unless you know the function name, searching the Codex can be painful. Trying to keep this straight drives me nuts!