A filter passes a value through your function and takes back what you return.
Measured on a live WordPress 7.1 install on 2026-09-02: a filter doubling the
value at priority 10 and another adding 5 at priority 20, applied to 100,
answers 205. Lower priority runs first, and the second one
receives the first one's output.
Now the failure that produces most WordPress support tickets. A filter
callback that changes the value and forgets to return it makesapply_filters answer NULL. Not the original, not an
error: null, passed on to whatever the core was going to do with it. Every
filter callback ends in a return, without exception.
Actions and filters are the same machinery, used differently
- An action is a moment: something happened, do what you like,
nothing is expected back - A filter is a value in transit: change it or do not, and
return it either way - Both run in priority order, low numbers first, and both run every registered
callback - The fourth argument to
add_filteris how many arguments your
callback wants, and leaving it at the default of 1 while declaring two
parameters is a fatal error at the moment the hook fires
That last one is worth naming because the error appears somewhere unrelated:
the hook fires deep inside core, so the message names a file you have never
opened, and the cause is one missing number in your own plugin.
How crowded a hook already is
This install has 711 hooks registered at the point a page is built, andthe_content alone carries fourteen callbacks. Reading them in order
explains behaviour that otherwise looks like magic: do_blocks at 9
renders block markup, wptexturize and wpautop at 10 do
the typography and the paragraphs, do_shortcode at 11, andwp_filter_content_tags at 12 adds the image attributes.
Which is why priority is a real decision rather than a default. A callback at
9 sees raw block markup; the same callback at 20 sees fully rendered HTML with
paragraphs and shortcodes already expanded. Choosing the wrong side ofwpautop is why an inserted element ends up wrapped in a stray
paragraph tag.
What to run in 2026
Query Monitor is the tool, free and open source, and it is the one plugin
worth installing on every development site. It lists the hooks that fired for
the current request with their callbacks, the queries with their callers, and
the PHP notices, which turns all of this from reading to looking. It replaced
adding error_log calls inside core files.
WP_DEBUG with WP_DEBUG_LOG is the second, free with
WordPress, and it is off by default on every install. With it on, the missing
return above shows up as a notice in wp-content/debug.log rather
than as a blank area on the page. It replaced developing with the errors
hidden, which is the default and the reason most of these bugs live so long.
Where this stalls people
The stall is editing core or a theme's parent files because a hook could not
be found. The edit works, it survives until the next WordPress update, and then it is
gone with no record of the hook that was never found. Every such edit is a hook somebody did not find,
and there are more of them than anyone expects: 711 on this install, before a
single plugin of your own.
The search that finds one takes a minute:grep -rn "apply_filters\|do_action" wp-includes/ | grep -i <the thing. The hook names are descriptive, they are in the source, and
you want>
that grep is faster than the documentation. Where those callbacks live is
the template
hierarchy, and building one, the language they are written in is
syntax, requests and the shape
of a script, and the platform is
what runs a large share of the
web.