WordPress.org

Forums

apply_filters - how does it work (9 posts)

  1. chibis
    Member
    Posted 1 year ago #

    Can someone please explain to me in plain English or point in right direction (other than documentation) how apply_filters work. Please keep in mind I am less than a beginner in php.
    If I understand the documentation correctly (which apparently I don't) what apply_filters is doing, is calling a function the name of which is passed as a first parameter, passing to this function parameters that were passed to apply_filters as 2nd and more. There are 2 things I don't understand here. How come it can pass as the 1st param. "some_name", while "some_name" is not defined anywhere in the code. And how can apply_filters be returned from within "some_func" with the 1st param. set to "some_func" as in:

    function some_func($blah){
      $blah='blah';
      return ('some_func', $blah);
    }

    This doesn't make sense to me. Will highly appreciate your help.
    Thank you.

  2. esmi
    Forum Moderator
    Posted 1 year ago #

    How come it can pass as the 1st param. "some_name", while "some_name" is not defined anywhere in the code.

    The first parameter is a filter/function that is defined by core, a plugin or your theme. Commonly such filters are intended to parse and re-format content in some way before it is displayed. The second parameter is the default value to be used if there are no customisations applied using add_filter()..

    So when you use $my_content = apply_filters( $tag, $value );, what you are saying is "when the $tag filter runs, check for a new value added by add_filter(), otherwise use $value.".

    For example, in one of my themes, I set up some filters for the header & background customisations:

    // Header & background customisation
    	$zenlite_header = array(
    		'default-text-color' => apply_filters( 'zenlite_header_color', '606060'),
    		'width' => apply_filters( 'zenlite_header_image_width', 1000 ),
    		'height' => apply_filters( 'zenlite_header_image_height', 150 ),
    		'default-image' =>  apply_filters( 'zenlite_header_image', get_stylesheet_directory_uri() . '/images/banner.jpg'),
    		'wp-head-callback' => 'zenlite_custom_header_style',
    		'admin-head-callback' => 'zenlite_admin_header_style',
    		'admin-preview-callback' => '',
    	);
    	add_theme_support( 'custom-header', $zenlite_header );

    Then in a child of this theme, I can change the height of the header image by using:

    // Increase header image height to 250px
    function zenlite_new_header_height($height) {
    	$height = 250;
    	return $height;
    }
    add_filter( 'zenlite_header_image_height', 'zenlite_new_header_height' );

    Now the header in the child theme is 250px instead of 150px.

    Does that help?

  3. chibis
    Member
    Posted 1 year ago #

    Thank you, it does make a little more sense now. So now when I search for my "some_func" or specifically "bbp_get_reply_content" I do see a lot of places where this name is passed as a parameter to add_filter. Is there a way to find out which one of these add_filter-s is used when apply_filters( 'bbp_get_reply_content', ...) is called?
    The piece I am talking about looks like this:

    function bbp_get_reply_content( $reply_id = 0 ) {
    	$reply_id = bbp_get_reply_id( $reply_id );
    
    	// Check if password is required
    	if ( post_password_required( $reply_id ) )
    		return get_the_password_form();
    	$content = get_post_field( 'post_content', $reply_id );
    	return apply_filters( 'bbp_get_reply_content', $content, $reply_id );
    }
  4. esmi
    Forum Moderator
    Posted 1 year ago #

    The function bbp_get_reply_content() runs the bbp_get_reply_content() filter right at the end. So any other function (e.g. some_new_function) that is hooked using:

    add_filter( 'bbp_get_reply_content', 'some_new_function' );

    will be run whenever bbp_get_reply_content() runs.

  5. esmi
    Forum Moderator
    Posted 1 year ago #

    Think of it like a train. apply_filters() is the train engine and you can hook carriages (functions) onto it using add_filter(). So when the engines moves/runs, the carriages all move/run too.

  6. chibis
    Member
    Posted 1 year ago #

    so add_filter doesn't overwrite the already added function, but rather adds to it. So if I have

    add_filter( 'bbp_get_reply_content', 'some_new_function1');
    add_filter( 'bbp_get_reply_content', 'some_new_function2' );

    then whenever apply_filter( 'bbp_get_reply_content',...) is called, both "some_new_function1" and "some_new_function2" will be executed? In which order? What happens when both of these functions save something (say some same field in the database), which one will be saved?

  7. esmi
    Forum Moderator
    Posted 1 year ago #

    so add_filter doesn't overwrite the already added function, but rather adds to it.

    Almost. add_filter adds functions to a queue that can then be triggered by apply_filter().

    then whenever apply_filter( 'bbp_get_reply_content',...) is called, both "some_new_function1" and "some_new_function2" will be executed?

    Bingo!

    What happens when both of these functions save something (say some same field in the database), which one will be saved?

    In theory, the last one to be executed would over-write any earlier ones. Figuring out the order in which they were executed could be tricky - which is why you can apply a priority value to add_filter() to try & control the order of execution.

    $priority
    (integer) (optional) Used to specify the order in which the functions associated with a particular action are executed. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the filter.
    Default: 10

    http://codex.wordpress.org/Function_Reference/add_filter

  8. chibis
    Member
    Posted 1 year ago #

    I guess, I just got an answer to my questions. The add_filter takes the priority parameter
    Can't say it's all that clear now, but it's a lot clearER. THANK YOU.

  9. esmi
    Forum Moderator
    Posted 1 year ago #

    No problem.

    I think the whole "using filters" thing gets easier the more you try them out. A lot of plugins use filters to modify their own output or to allow add-on plugins to modify the output of the core plugin. But more and more theme developers are starting to implement filters in their themes to allow for easier child theming etc. The example I gave above is a case in point. Without add_filter and apply_filter, it can be very difficult for a child theme to change custom header or background handling. With filters it becomes extremely easy.

Topic Closed

This topic has been closed to new replies.

About this Topic