add_filter() function misunderstanding

Question

I'm studying the theme "one page" and there is the following code:

function onepage_sections() {
$sections = array();

$sections['service_section'] = array(
    'id' => 'service_section',
    'label' => __('Service Section', 'one-page'),
    'callback' => 'onepage_service_section',
);

$sections['blog_section'] = array(
    'id' => 'blog_section',
    'label' => __('Blog Section', 'one-page'),
    'callback' => 'onepage_blog_section',
);

return apply_filters('onepage_sections', $sections);
}

From what I have read the function apply_filters creates a tag (a key name that can be accessed later) and a content that will be susceptible to change whenever someone uses add_filter(key_name, function_to_alter_content_in_key_name). Correct?

What I don't get is that in this theme, there are no calls to add_filter('onepage_sections'). It is simply declared in the preceding call to apply_filters. Could someone clarify the concept of these functions?

Answer 1

add_filter ( string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1 )

Hook a function or method to a specific filter action.

WordPress offers filter hooks to allow plugins to modify various types of internal data at runtime.

A plugin can modify data by binding a callback to a filter hook. When the filter is later applied, each bound callback is run in order of priority, and given the opportunity to modify a value by returning a new value.

The following example shows how a callback function is bound to a filter hook.

Note that $example is passed to the callback, (maybe) modified, then returned:

function example_callback( $example ) {
    // Maybe modify $example in some way.
    return $example;
}
add_filter( 'example_filter', 'example_callback' );

Bound callbacks can accept from none to the total number of arguments passed as parameters in the corresponding apply_filters() call.

In other words, if an apply_filters() call passes four total arguments, callbacks bound to it can accept none (the same as 1) of the arguments or up to four. The important part is that the $accepted_args value must reflect the number of arguments the bound callback actually opted to accept. If no arguments were accepted by the callback that is considered to be the same as accepting 1 argument. For example:

// Filter call.
$value = apply_filters( 'hook', $value, $arg2, $arg3 );

// Accepting zero/one arguments.
function example_callback() {
    ...
    return 'some value';
}
add_filter( 'hook', 'example_callback' ); // Where $priority is default 10, $accepted_args is default 1.

// Accepting two arguments (three possible).
function example_callback( $value, $arg2 ) {
    ...
    return $maybe_modified_value;
}
add_filter( 'hook', 'example_callback', 10, 2 ); // Where $priority is 10, $accepted_args is 2.

Note: The function will return true whether or not the callback is valid. It is up to you to take care. This is done for optimization purposes, so everything is as quick as possible.

Answer 2

I have met same spot and was looking for answer, after reading answers here it became even more confusing for me. I decided that using apply_filters('filter_name', $vars...) when 'filter_name' was never defined via add_filter('filter_name', function...) is adding new filter same as add_filter , but NO ! It doesnt work this way. In fact, it works as simply as you could imagine, just the same way as it was designed.

Note: explanations and answers provided before was just about how filters work, but not about what OP asked about. So let's continue.

In that case what "return apply_filters('filter_name', $sections) does is just works same as

return $sections;

with one difference , it, guess what, applies filters attached to 'filter_name'. If there is no filters 'filter_name' in apply_filters('filter_name', $sections)-call it returns $sections,but if user has attached filters to 'filter_name' it applies filters.

Only confusing part here is same name for filter and the function. That brings all confusion. I think there are some reasons why WP developers named it like that.

So, 'filter_name' never called add_filter('filter_name') because there was no reasong for that. And altering function does affect your results cuz function is used like FUNCTION, it's somewhere called like any other simple function - function_name($var1, $var2). Again, repeating, it just returns value along with applying filters in the end, so users(other developers) can add their own filters to that proccess and alter result.

Hope u got it :)