Overview

A filter hook passes a value through every function registered with add_filter() before WordPress uses it, so your plugin can change titles, content, excerpt lengths or query results without touching the code that produced them.

The golden rule: always return

<?php
function gdc_books_excerpt_length( $length ) {
    return 30; // Words. Default is 55.
}
add_filter( 'excerpt_length', 'gdc_books_excerpt_length' );

WordPress calls apply_filters( 'excerpt_length', 55 ). The value goes into your function, and whatever you return is what WordPress uses. Forget the return and the value becomes null — every excerpt on the site disappears.

Filters with extra context

Many filters pass the value plus extra arguments that describe it. Accept them by setting the fourth parameter:

<?php
/**
 * Prefixes the title of Book posts with a book emoji, on the front end only.
 *
 * @param string $title   The post title.
 * @param int    $post_id The post ID.
 * @return string
 */
function gdc_books_title_prefix( $title, $post_id = 0 ) {
    if ( is_admin() || ! $post_id ) {
        return $title;
    }

    if ( 'gdc_book' === get_post_type( $post_id ) ) {
        return '📘 ' . $title;
    }

    return $title;
}
add_filter( 'the_title', 'gdc_books_title_prefix', 10, 2 );

Notice the early returns that hand the value back unchanged when it is not one you want to modify. A filter should be a precise scalpel: change only what you mean to, and pass everything else straight through.

Filters you will use constantly

Adding a Settings link on the Plugins screen

<?php
function gdc_books_action_links( $links ) {
    $settings = sprintf(
        '<a href="%s">%s</a>',
        esc_url( admin_url( 'options-general.php?page=gdc-books' ) ),
        esc_html__( 'Settings', 'gdc-books' )
    );

    array_unshift( $links, $settings ); // Put it first.
    return $links;
}
add_filter( 'plugin_action_links_' . GDC_BOOKS_BASENAME, 'gdc_books_action_links' );

Common filter mistakes

• Echoing inside a filter. A filter returns; it never prints. Echoing sends output to the wrong place on the page.
• Changing the type. If the filter passes an array, return an array. Returning a string breaks the code that called it.
• Running too broadly. A the_content filter without checks also runs in feeds, excerpts and the REST API. Guard it with conditions like is_singular() and in_the_loop().

Practice

• Set the excerpt length to 25 words and change "[…]" to a "Read more" link with excerpt_more.
• Add the Settings link to the Plugins screen.
• Add a gdc-books-active class to <body> with the body_class filter.