Posted on Leave a comment

apply_filters() – Call the functions added to a filter hook.

apply_filters( string $tag, mixed $value )

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 );

Parameters:

$tag (string) (Required) 
The name of the filter hook.

$value (mixed) (Required) 
The value on which the filters hooked to $tag are applied on.

$var,… (mixed) (Required) 
Additional variables passed to the functions hooked to $tag.

Return:

(mixed) The filtered value after all hooked functions are applied to it.

Examples & Notes:

// Echo after Filtering:
echo apply_filters( $tag, $value );

// Get Filtered:
$myvar = apply_filters( $tag, $value );

// Additional Filter Arguments:
$myvar = apply_filters( $tag, $value, $param, $otherparam );

// For example:
$myvar = apply_filters( 'example_filter', 'filter me', 'arg1', 'arg2 ');

// With the_title filter:
$my_custom_title = apply_filters('the_title', '  My Custom Title (tm)  ');
$my_custom_title will now contain 'My Custom Title ™', since the_title filter applies wptexturize() and trim(), among others.

Tutorials:

01. How to Use apply_filters() and do_action() to Create Extensible WordPress Plugins

Source:

File: wp-includes/plugin.php (line: 178-213)

function apply_filters( $tag, $value ) {
    global $wp_filter, $wp_current_filter;
 
    $args = array();
 
    // Do 'all' actions first.
    if ( isset( $wp_filter['all'] ) ) {
        $wp_current_filter[] = $tag;
        $args                = func_get_args();
        _wp_call_all_hook( $args );
    }
 
    if ( ! isset( $wp_filter[ $tag ] ) ) {
        if ( isset( $wp_filter['all'] ) ) {
            array_pop( $wp_current_filter );
        }
        return $value;
    }
 
    if ( ! isset( $wp_filter['all'] ) ) {
        $wp_current_filter[] = $tag;
    }
 
    if ( empty( $args ) ) {
        $args = func_get_args();
    }
 
    // don't pass the tag name to WP_Hook
    array_shift( $args );
 
    $filtered = $wp_filter[ $tag ]->apply_filters( $value, $args );
 
    array_pop( $wp_current_filter );
 
    return $filtered;
}

View on Trac | Github | Codex

Change Log:

VersionDescription
0.71Introduced

Related:

apply_filters_ref_array,
apply_filters_deprecated,
has_filter, add_filter,
wp_list_filter

Posted on Leave a comment

get_theme_mod() – Retrieve theme modification value for the current theme

get_theme_mod( string $name, bool|string $default = false )

If the modification name does not exist, then the $default will be passed through sprintf() PHP function with the first string the template directory URI and the second string the stylesheet directory URI.

Parameters:

$default (bool|string) (Optional)
Default value: false

$name (string) (Required) 
Theme modification name.

Return:

(mixed)

Examples & Notes:

Calling the custom background color, This example could be used to add the custom background color as a border on the top of the footer. It would be CSS inserted in the header:

echo get_theme_mod( 'background_color' );

Tutorials:

01. Digging Into the Theme Customizer
02. Using the Customizer to Add Settings to Your WordPress Theme

Source:

File: wp-includes/theme.php (line: 901-926)

function get_theme_mod( $name, $default = false ) {
    $mods = get_theme_mods();
 
    if ( isset( $mods[ $name ] ) ) {
        /**
         * Filters the theme modification, or 'theme_mod', value.
         *
         * The dynamic portion of the hook name, `$name`, refers to
         * the key name of the modification array. For example,
         * 'header_textcolor', 'header_image', and so on depending
         * on the theme options.
         *
         * @since 2.2.0
         *
         * @param string $current_mod The value of the current theme modification.
         */
        return apply_filters( "theme_mod_{$name}", $mods[ $name ] );
    }
 
    if ( is_string( $default ) ) {
        $default = sprintf( $default, get_template_directory_uri(), get_stylesheet_directory_uri() );
    }
 
    /** This filter is documented in wp-includes/theme.php */
    return apply_filters( "theme_mod_{$name}", $default );
}

View on Trac | Github | Codex

Change Log:

VersionDescription
2.1.0Introduced

Related:

get_theme_mods,
get_theme,
get_theme_root,
get_theme_data