WordPress Hooks vs Filters: The Practical Distinction

WordPress's hook system has two types: actions and filters. The terms are sometimes used interchangeably; the technical distinction matters when writing custom code.

The actions

Actions are events. They fire at specific points in WordPress's execution. Code attached to an action runs when the event happens but doesn't typically return values.

Examples: init (early in request), save_post (when a post is saved), wp_footer (when the footer renders).

Action handlers are added with add_action() and triggered with do_action().

add_action('save_post', function($post_id) {
    // Do something when a post saves
});

The filters

Filters are transformations. They pass a value through; code attached can modify the value and must return it.

Examples: the_content (modifies post content), the_title (modifies post title), wp_get_attachment_url (modifies media URLs).

Filter handlers are added with add_filter() and triggered with apply_filters().

add_filter('the_content', function($content) {
    // Modify content
    return $content;
});

The return is essential. Filters that don't return produce empty values where they were applied.

The practical difference

Actions are for side effects. The code does something but doesn't change a value being passed through.

Filters are for transformations. The code modifies a value.

The distinction guides which one to use. Adding tracking code: action (the code runs but doesn't return anything). Modifying displayed content: filter (the content is transformed and returned).

The priority parameter

Both add_action and add_filter accept a priority parameter. Default priority is 10. Lower numbers run earlier; higher numbers run later.

add_filter('the_content', 'my_function', 5); // Runs early
add_filter('the_content', 'other_function', 20); // Runs later

The priority matters when multiple handlers attach to the same hook. The order of execution affects the final result.

The arguments parameter

The fourth parameter specifies how many arguments the handler accepts. Default is 1; some hooks pass multiple arguments.

add_action('save_post', 'my_function', 10, 3); // Accepts 3 arguments
function my_function($post_id, $post, $update) {
    // Has access to all three
}

Forgetting the argument count produces handlers that don't receive the expected arguments.

The honest framing

The action-vs-filter distinction is fundamental WordPress development knowledge. Confusing them produces broken customizations.

The rule of thumb: if you're modifying a value, use filter and return. If you're triggering a side effect, use action.

For developers new to WordPress, this distinction is one of the first things to internalize.