Now and then, whenever I’m working with pre-existing source code or performing a code audit, I’ll see others modifying the post content of a post object like this:
At this point, some will drop in and immediately say you’re doing it wrong. I hate that phrase (and it’s even littered throughout the WordPress codebase, but I digress).
There are ways to use other existing WordPress API functions to sanitize the data before setting it equal to the value of the post_content attribute, using those functions isn’t the best way to go about doing it.
Instead, we all should be using apply_filters. The problem? Some don’t know, some don’t know how it works, and some don’t know how to use it. That is it’s not clear how to go about properly filtering post content.
But for those who may fall into any of the categories above, then perhaps this can help.
Properly Filtering Post Content
At this point, I’m assuming that you know about WP_Post, its properties, and how to modify them through various API functions.
The primary issue I’m talking about is making sure the content that will be written to the database is formatted in the same way in which WordPress would do it if you were to be writing or updating a post.
And the way that happens is like this (and we’ll get to the details on this soon):
But the questions of what this function does, how it works, and when to use it remain.
What is apply_filters?
Sure, you can read all about this in the Developer Resources, and it gives this definition:
Call the functions added to a filter hook.
But that doesn’t always help. I mean we can read the documentation and still walk away confused, right?
Think about it this way:
- A filter is a function that accepts input to process.
- The input is processed based on the definition of the function.
- The function then returns the processed value.
What you do with the returned value is up to you, but when you apply a filter or call apply_filters to a piece of information, you’re telling WordPress: “I have this information, please apply the filter identified by this key and hand the result back to me.”
Not bad, right?
How Does It Work?
But there’s one part of the above that leads to a question. Specifically, I mention that “…please apply the filter identified by this key…” and the idea of a key can be confusing especially because a filter or action or, more generally speaking, a hook can be identified by what’s called a tag or a key.
They are synonyms. So when you see tag or key in the context of a hook, treat them as such.
With that said, here’s how it works:
- The apply_filters function accepts two arguments. The first is the tag or the key (depending on what you want to call it) associated with the filter (read: function) you want to use to process the work, the second is the value you want to process within said function.
- The filter will fire and return a result (or, remember, the function that we’ve defined).
- We then take the value that’s returned and apply it to whatever property we want.
So, for example, you’re likely to see something like this in someone else’s codebase (or perhaps even your own):
And now that you have a bit of context for how it works, you get the idea, right?
How Do We Use It?
This brings the post full circle to the initial question of how we can use apply_filters to post_content whenever we need to insert or update a post.
So let’s say that you have the content that you want to apply (or append) to the value of a post’s content. You could do something like this:
But that’s bad form. Instead, you do this:
And that’s how WordPress does it.
So given all of the information and code above, you should be well-armed not only to make sure you’re properly filtering data that will be inserted into the database, you’ve got the knowledge needed to define your filters and apply them to any data you see fit.
But examples for that is content for another post.
In the meantime, if you’re working with post content then make sure you are properly filtering the data before dropping it into the database.