WordPress codex: apply_filters – clarification on creating a new hook on the fly. How do we use it?

I have read the WordPress Codex on add_filter and apply_filter countless times, but it wasn’t until reading woocommerce source code today that something clicked in the way that maybe I don’t understand the way apply_filter works or maybe I don’t quite understand how it creates a new hook and when/where is the function defined for the new hook?

Review the wordpress codex again

CODEX: apply_filters( string $tag, mixed $value ) Call the functions
added to a filter hook.

The callback functions attached to filter hook $tag are invoked by
calling this function. This function can be used to create a new
filter hook by simply calling this function with the name of the new
hook specified using the $tag parameter.

The function allows for additional arguments to be added and passed to
hooks.

// Our filter callback function

function example_callback( $string,
> $arg1, $arg2 ) {
>     // (maybe) modify $string
>     return $string; } add_filter( 'example_filter', 'example_callback', 10, 3 );

/* Apply the filters by calling the ‘example_callback’ function we
“hooked” to ‘example_filter’ using the add_filter() function above.
-> ‘example_filter’ is the filter hook $tag.
-> ‘filter me’ is the value being filtered.
-> $arg1 and $arg2 are the additional arguments passed to the callback.

$value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 );

You can see they show one way to use apply_filters: that is in combination with add_filters where the function is defined and linked to the $tag.
The use is intuitive. You define it, you use it.

So what about the other scenario, creating a new filter hook on the fly … If some of you are still saying what? lets reread that part of the codex one more time.

This function can be used to create a new filter hook by simply
calling this function with the name of the new hook specified using
the $tag parameter.

So add_filter isn’t used in this circumstance. Which leads to my question ‘what are we trying to accomplish here? Why are we creating a filter hook here? How do we associate a function with a filter hook that gets created on-the-fly?

The apply_filter codex doesn’t give us an example of how or why we would want to do this which is an oversight, but I keep finding instances of these filter hooks as I was walk my way through woocommerce source over at github.

In woocommerce, for example, I see apply_filter used as follows:

function woocommerce_get_product_thumbnail( $size="woocommerce_thumbnail", $deprecated1 = 0, $deprecated2 = 0 ) {
    global $product;

    $image_size = apply_filters( 'single_product_archive_thumbnail_size', $size );

    return $product ? $product->get_image( $image_size ) : '';
}

I’ve searched for the tag ‘

single_product_archive_thumbnail_size

‘ in woocommerce repository on github. There is only the single occurrence of it as you see here. So how do we use it?

How to use the filter single_product_archive_thumbnail_size

I’ve searched for the tag single_product_archive_thumbnail_size in
woocommerce repository on github. There is only the single occurrence
of it as you see here. So how do we use it?

The author’s of WooCommerce added this filter so that other developers would be able to modify the product’s archive thumbnail size. WooCommerce may not be using this filter itself, but they could.

Here’s how you could use the single_product_archive_thumbnail_size filter. In this hypothetical scenario, we want to override the single_product_archive_thumbnail_size defined by WooCommerce with the image size kruddock_archive_thumbnail defined in the kruddock theme if that theme happens to be active.

/**
 * If the kruddock theme is active, use the kruddock_archive_thumbnail
 * image size for WooCommerce's single_product_archive_thumbnail_size
 *
 * @param string $size name of thumbnail size
 */
add_filter( 'single_product_archive_thumbnail_size', 'single_product_archive_thumbnail_size' );
function wpse_single_product_archive_thumbnail_size( $size ) {
    $theme = wp_get_theme();
    if ( 'kruddock' == $theme->name || 'kruddock' == $theme->parent_theme ) {
        $size="kruddock_archive_thumbnail";
    }


    return $size;
}

Dynamic hooks

A good example of a dynamic hook is the one defined for options, e.g.:

apply_filters( "option_{$option}", mixed $value, string $option )

Let’s say you have a plugin named Kruddock API. In this plugin, you have an option that uses the WP settings API to save a setting named kruddock_api_url.

A developer using your plugin could use the option_kruddock_api_url filter to modify the value returned by get_option( 'kruddock_api_url' ) without actually modifying the stored value of kruddock_api_url (as is the nature with filters; we’re modifying the value on the fly) and without you as the developer of the Kruddock API plugin ever having provided a specific filter for modifying the value of kruddock_api_url.

The WP Settings API allows us to modify any option on the fly using the dynamic filter option_{$option}. Here is how the dynamic hook in this example could be used by another developer:

add_filter( 'option_kruddock_api_url', 'wpse_option_kruddock_api_url' );
function wpse_option_kruddock_api_url( $value ) {
    // Use a different API URL than the default.
    $value="https://subdomain.example.com";

    return $value;
}