Using WordPress ‘add_filter()’ PHP function

by

The add_filter() WordPress PHP function enables plugins to modify internal data at runtime. This is achieved by binding a callback to a filter hook. When the filter is applied, each bound callback is run according to its priority, altering the original value by returning a new one.

Usage

To use the add_filter() function, you simply need to specify the filter you want to modify, and the callback function that will handle the modification. Here’s an example:

function modify_content( $content ) {
    // Modify $content in some way.
    return $content;
}
add_filter( 'the_content', 'modify_content' );

In this example, ‘the_content’ is the filter hook that we’re modifying, and ‘modify_content’ is our custom callback function that handles the modification.

Parameters

  • $hook_name (string – Required): The name of the filter to add the callback to.
  • $callback (callable – Required): The callback to be run when the filter is applied.
  • $priority (int – Optional): Used to specify the order in which the functions associated with a particular filter are executed. Lower numbers correspond with earlier execution. Default is 10.
  • $accepted_args (int – Optional): The number of arguments the function accepts. Default is 1.

More information

See WordPress Developer Resources: add_filter()

Examples

Modifying the number of front page sections in the TwentySeventeen theme

add_filter( 'twentyseventeen_front_page_sections', 'custom_front_page_sections' );

function custom_front_page_sections( $num_sections ) {
    return 6; // Changes the default 4 sections to 6.
}

Altering the length of post excerpts

add_filter( 'excerpt_length', 'custom_excerpt_length', 999 );

function custom_excerpt_length( $length ) {
    return 40; // Changes the default 57 characters to 40.
}

Adding a custom CSS class to post content

add_filter('the_content', 'add_custom_class');

function add_custom_class($content) {
    $content = str_replace( '<ul', '<ul class="detail-list"', $content );
    return $content; // Adds the 'detail-list' class to <ul> tags.
}

Pre-populating the global $wp_filter array when add_filter is not available

$GLOBALS['wp_filter'][ $tag ][ $priority ] = array( 'function' => $function_to_add, 'accepted_args' => $accepted_args );

Replacing the [caption] shortcode with HTML5 compliant code

add_filter('img_caption_shortcode', 'my_img_caption_shortcode_filter', 10, 3);

function my_img_caption_shortcode_filter($val, $attr, $content = null) {
    extract( shortcode_atts( array(
        'id' => '',
        'align' => '',
        'width' => '',
        'caption' => ''
    ), $attr ) );

    if ( 1 > (int) $width || empty($caption) ) return $val;

    $capid = '';
    if ( $id ) {
        $id = esc_attr( $id );
        $capid = 'id="figcaption_' . $id . '" ';
        $id = 'id="' . $id . '" aria-labelledby="figcaption_' . $id . '" ';
    }

    return '<figure ' . $id . 'class="wp-caption' . esc_attr($align) . '" style="width: ' . (10 + (int) $width) . 'px">' . do_shortcode( $content ) . '<figcaption ' . $capid . 'class="wp-caption-text">' . $caption . '</figcaption></figure>';
}

In this example, the add_filter() function is used to replace the default WordPress caption shortcode with a custom HTML5 compliant version. The filter function receives three arguments: the value to be modified (the shortcode), the attributes of the shortcode, and the content within the shortcode. It then uses these values to generate and return the new HTML for the caption.