Where is the best place to use add_filter

by

add_filter() and add_action() are available before any plugin is loaded. So you can use both in the first line of your plugin or theme.

For readability I recommend to group action and filter registrations at the very top of your main file:

  • in a plugin, the file with the plugin header
  • in a theme the functions.php

There are exceptions for that rule:

  • Chained callbacks. In this example I register an action for shutdown only when the first filter for wp_nav_menu_objects has been called. So the second callback cannot be registered at the same time as the first one.

  • OOP style. Sometimes you have to set up class members before you can register the callbacks. Using a very similar example …

    add_action(
    'plugins_loaded',
    array ( T5_Plugin_Class_Demo::get_instance(), 'plugin_setup' )
);
class T5_Plugin_Class_Demo
{
    public function plugin_setup()
    {
        $this->plugin_url    = plugins_url( "https://wordpress.stackexchange.com/", __FILE__ );
        $this->plugin_path   = plugin_dir_path( __FILE__ );
        $this->load_language( 'plugin_unique_name' );

        // more stuff: register actions and filters
    }
}

    … we see the instantiation of the class can be stopped by another plugin, and a child class could register more or different filters and actions.

In addition to grouping you can go a step further and offer a custom action to make customizations for other developers easier.
Here is an example from a theme I am working on:

add_action( 'activate_header',      't5_activate_screen' );
// wp_loaded is too late, WP customizer would not detect the features then.
add_action( 'after_setup_theme',    't5_setup_custom_background' );
add_action( 'after_setup_theme',    't5_setup_custom_header' );
add_filter( 'body_class',           't5_enhance_body_class' );
add_action( 'comment_form_before',  't5_enqueue_comment_reply' );
add_action( 'content_before',       't5_frontpage_widget' );
add_action( 'footer_before',        't5_loop_navigation' );
add_action( 'get_the_excerpt',      't5_excerpt_clean_up', 1 );
add_action( 'header_before',        't5_skiplink', 0, 0 );
add_filter( 'the_title',            't5_fill_empty_title', 20, 1 );
add_action( 'wp_enqueue_scripts',   't5_enqueue_style' );
add_action( 'wp_enqueue_scripts',   't5_enqueue_script' );
add_action( 'wp_loaded',            't5_setup' );
add_action( 'wp_loaded',            't5_page_enhancements' );
add_action( 'wp_loaded',            't5_post_format_support' );
add_action( 'wp_loaded',            't5_load_theme_language' );
add_action( 'wp_loaded',            't5_setup_sidebars' );
add_filter( 'wp_nav_menu_items',    't5_customize_top_menu', 10, 2 );
add_filter( 'wp_nav_menu_args',     't5_nav_menu_args', 10, 1 );
add_filter( 'wp_title',             't5_wp_title_filter', 20, 2 );

add_shortcode( 'gallery',    't5_shortcode_gallery' );
add_shortcode( 'wp_caption', 't5_shortcode_img_caption' );
add_shortcode( 'caption',    't5_shortcode_img_caption' );

// Use this action to unregister theme actions and filters.
do_action( 't5_theme_hooks_registered' );

The last line is important: A child theme or a plugin can hook into the action t5_theme_hooks_registered now and unregister any previous hook. That will save struggling with priorities, and I am free to change my callback priorities any time.

But do not rely on source code order alone. Document the hooks you are using in your doc block. I am using a custom tag wp-hook for that. Here is an example with chained hooks from the same theme:

/**
 * Register handler for auto-generated excerpt.
 *
 * @wp-hook get_the_excerpt
 * @param   string $excerpt
 * @return  string
 */
function t5_excerpt_clean_up( $excerpt )
{
    if ( ! empty ( $excerpt ) )
        return $excerpt;

    add_filter( 'the_content', 't5_excerpt_content' );

    return $excerpt;
}
/**
 * Strip parts from auto-generated excerpt.
 *
 * @wp-hook the_content
 * @param   string $content
 * @return  string
 */
function t5_excerpt_content( $content )
{
    remove_filter( current_filter(), __FUNCTION__ );

    return preg_replace( '~<(pre|table).*</\1>~ms', '', $content );
}

You don’t have to scroll up to see where these functions are called, one look at the doc block is enough. This requires some efforts, because you have to keep both in sync, the registration and the comment, but in the long run it saves valuable time.

Leave a Comment