[FIXED] How can apply_filters be used to create a filter hook in wordpress?

Issue

Wordpress documentation about apply_filters mentions:

It is possible to create new filter hooks by simply calling this function, specifying the name of the new hook using the $hook_name parameter.

Ok, I want to create a filter hook called the_content2, so I do what the docs suggest:

$custom_hook = apply_filters("the_content2", the_content());

Now I assume the_content2 hook is created and is similar to the_content. So on a single post page I should be able to use the_content2 hook like the_content2:

the_content2()

This throws error, function is not defined. I am beginner in wordpress, can someone please explain comprehensively how apply_filters can be used to create your own filters.

Solution

Hooks (actions and filters) have two main components, the part that declares the hook, and the callbacks that implement the hook.

A very simple example is:

$name = "Chris";
$name = apply_filters("change_name", $name);
echo $name;

If no one registers a callback, then Chris will be outputted. However, if someone writes this:

add_filter(
    "change_name",
    function($name){ return "Steve";}
);

Then Steve will be outputted.

At no point, however, will a new function called change_name() be created.

As it relates to hooks, I would generally steer you away from thinking about a hook "being created", and instead think about it as "being called". A function always exists, but hooks are only used if they are actually called.

To your main issue as it relates to the_content(), I would determine what you want to do with that. If you want to transform the result of that function for all instances, a hook is probably a good idea. However, if you just want to use it differently sometimes, a custom function (without a hook) that calls the original, does something and returns it might be more appropriate.

EDIT

Below is a mock of how the hook system works. I've simplified it a bunch, but it should give you a gist of how it works.

function add_filter($name, $callback) {
    global $filters;
    $filters[$name][] = $callback;
}

function apply_filters($name, $value) {
    global $filters;
    if(array_key_exists($name, $filters)) {
        foreach($filters[$name] as $callback) {
            $value = $callback($value);
        }
    }
    return $value;
}

I can't stress this enough, no one is really declaring or registering things. At most, an array key is added with a name when the add_filter/add_action is used. Then, if someone calls the apply_filters/do_action then the key is looked up, and if it exists, the callbacks are run.

So add_filter/add_action has to happen first. It is "I'm interested in XYZ if it actually happens". There's many cases where it might not happen, but if it does, then the callback will fire.

The apply_filters can't/shouldn't throw an error if no one registered a callback, because that is totally a valid case. I often write code that is extensible for future callers but you'll notice that if no one adds a filter, the initial value is returned.

Answered By - Chris Haas

Answer Checked By - Mildred Charles (PHPFixing Admin)