Manipulating Posts and Terms

To complement the many ways to query and read the properties of single and multiple objects within WordPress, the MasterPress API also includes support for writing to these objects and committing the changes to your WordPress database.

Keeping in line with our goal of making this API as easy to use as possible, a lot of this manipulation happens through very natural property assignment statements, made possible by implementation of PHP 5’s __set magic method. First we’ll take a look at how to set properties of posts and terms that already exist, and later build on this to show how to create entirely new posts and terms, and relate them to each other.

Many of the examples presented here assume you know how to access single and multiple post and term objects using the MasterPress API. Please review Single Object Queries, Multiple Post Queries, and Multiple Term Queries if you’re unfamiliar.

Manipulating Posts

Let’s dive straight-in and look at an example of editing post properties and updating to the database, via the MasterPress API:

Example 1: Personalising Hello World

There are a few interesting things to note about this example:

The properties we set on line 5 through to 8 do not actually exist in WOOF_Post. These are then intercepted by the __set magic method, which handles them correctly
You need to be careful to specify the format of certain fields in the correct way, as in the date assignment on line 7. The correct format of post fields is explained well in the documentation for get_post in the Codex, but another quick way you could check is to use the debug method on your post object, to check the existing values in the field.
All three of the properties we’ve set use more concise property names which drop the “post_” prefix. WOOF_Post::__set can actually use a number of aliases of properties to make them a bit easier to work with, and these are listed in the class reference entry.
You need to call WOOF_Post::update once all properties have been set.

Be mindful that if you update posts via the methods mentioned here in the body area of a template which subsequently lists them, you may not see the changes you made, as the main query may have already been performed based on the original values. This is likely an unusual use-case, but If you need to do something like this you should perform updates inside a WordPress action that runs early, such as init.

Manipulating Taxonomy Terms

Editing taxonomy terms in the MasterPress API is very similar to the techniques used for posts. Here is an example where we edit a “fast” category:

Example 2: Editing a fast category

There’s not a whole lot we need to talk about here, apart from saying that the similarity of this to Example 1 is a very good thing – as soon as you can memorize how to maniuplate posts, it won’t take up much more of your brain to memorise how to do the same for terms.

Creating posts and terms

Now we’ll turn our attention to creating new posts and terms. But how to we approach this in an object-oriented way? While we could require developers to create new post and term objects via PHP’s new keyword, we can actually do better than this by taking advantage of 2 classes we already have which these objects belong to in a sense: WOOF_PostType and WOOF_Taxonomy.

Creating a new post

Creating a new post is just one more step beyond editing an existing post. Let’s take a look at an example:

Example 3: Creating a new post

The only difference to Example 1 is on lines 3 and 4 (which could be one one line, but we’ve separated them for clarity). We use the WOOF_PostType class as a vehicle to create a new post of that type, which we then populate with our data again, and update to commit our changes to the database.

If you dig design patterns, using WOOF_PostType as a means to create a WOOF_Post object is an example of the Factory Pattern. That is, our post type object is a factory for posts.

One of the benefits of using WOOF_PostType to create our post object is that it sets up the post type for us automatically. Another benefit is that we can offer a few more shorthand methods for doing more with less code. The following example revises Example 3 to create and update the post in one step, using the WOOF_PostType::insert method:

Example 4: Using the insert method to create a post

The WOOF_PostType::insert method is a lot more concise since it allows us to create the post, set its values, and update to the database in one method call.

Note: The database ID of the newly created post will be available in the “id” property of the post object immediately after using either WOOF_PostType::insert or WOOF_PostType::create followed by WOOF_Post::update.

Creating a new term

Creating new taxonomy terms is again very similar to the technique used for posts, except here we use the woof-taxomomy as a factory for our term objects. Here is the code to create a new category:

Example 5: Creating a new term

As you can see, this is very similar to example 3, except we request a taxonomy first rather than post type, and create our term from that. And just like we could use WOOF_PostType::insert to create and update posts immediately, so too we can use WOOF_Taxonomy::insert to create a term immediately:

Example 6: Using the insert method to create a term

Find or Create methods

Both WOOF_PostType and WOOF_Taxonomy have another method called find_or_create both of which take a $slug argument. This method will first try to find a post or term for that $id using the methods WOOF::post or WOOF::term respectively, and if not found will instead create a new post or term. Let’s see an example:

Example 7: Find OR Create methods

These patterns are very similar to editing existing posts or terms, except a post or term will be created for us using the $slug you’ve passed in if they’re not found. These methods could be very handy for some kind of import script that you run periodically to keep data in sync with another data source, where the posts or terms would be created the first time you run it, and then updated next time.

Deleting a post or term

Deleting posts or terms is very simple, by using the WOOF_Post::delete and WOOF_Term::delete methods respectively. Here’s a quick example:

Example 8: Deleting posts or terms

These methods delete posts and terms permanently, so take care.

Linking posts and terms

The MasterPress API also lets you attach and remove terms from posts, which is programmatically equivalent to assigning them or removing them with the standard term interfaces in the edit post screen:

Figure 1: The standard term interfaces

You can attach terms to posts in one of two ways: by calling the WOOF_Post::add_term method on a post object, or WOOF_Term::relate_to method on a term object:

Example 9: Linking terms to posts

Note that in either case, you can also use WOOF_Post and WOOF_Term objects as the first argument, if had already fetched them:

Example 10: Relating posts and terms via objects

Removing terms from posts can be done via the WOOF_Post::remove_term method, as in the example below:

MasterPress