WordPress.org
Get WordPress

Make WordPress Core

Changeset 48185


Ignore:
Timestamp:
06/26/2020 06:47:28 PM (5 years ago)
Author:
SergeyBiryukov
Message:

Docs: Standardize on "Returning a value from the filter" vs. "Passing a value to the filter".

The filter is the callback function added with add_filter(), therefore the hook passes a value to the filter, and the filter returns a value to change its behaviour.

The documentation is referring to the latter.

Props johnbillion.
See #49572, #16557.

Location:
trunk/src
Files:
17 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/includes/export.php

    r47808 r48185  
    329329             * Filters whether to selectively skip term meta used for WXR exports.
    330330             *
    331              * Returning a truthy value to the filter will skip the current meta
     331             * Returning a truthy value from the filter will skip the current meta
    332332             * object from being exported.
    333333             *
    … …  
    596596                     * Filters whether to selectively skip post meta used for WXR exports.
    597597                     *
    598                      * Returning a truthy value to the filter will skip the current meta
     598                     * Returning a truthy value from the filter will skip the current meta
    599599                     * object from being exported.
    600600                     *
    … …  
    639639                         * Filters whether to selectively skip comment meta used for WXR exports.
    640640                         *
    641                          * Returning a truthy value to the filter will skip the current meta
     641                         * Returning a truthy value from the filter will skip the current meta
    642642                         * object from being exported.
    643643                         *

  • trunk/src/wp-admin/includes/file.php

    r48184 r48185  
    881881     * Filters whether to short-circuit moving the uploaded file after passing all checks.
    882882     *
    883      * If a non-null value is passed to the filter, moving the file and any related error
    884      * reporting will be completely skipped.
     883     * If a non-null value is returned from the filter, moving the file and any related
     884     * error reporting will be completely skipped.
    885885     *
    886886     * @since 4.9.0

  • trunk/src/wp-admin/includes/media.php

    r48109 r48185  
    209209     * @since 2.6.0
    210210     *
    211      * @param bool $bool Whether to disable appending captions. Returning true to the filter
     211     * @param bool $bool Whether to disable appending captions. Returning true from the filter
    212212     *                   will disable captions. Default empty string.
    213213     */

  • trunk/src/wp-admin/includes/misc.php

    r48102 r48185  
    696696                     * settings. See the parent function for a full list of standard options.
    697697                     *
    698                      * Returning false to the filter will skip saving the current option.
     698                     * Returning false from the filter will skip saving the current option.
    699699                     *
    700700                     * @since 2.8.0
    … …  
    717717                 * The dynamic portion of the hook, `$option`, refers to the option name.
    718718                 *
    719                  * Returning false to the filter will skip saving the current option.
     719                 * Returning false from the filter will skip saving the current option.
    720720                 *
    721721                 * @since 5.4.2

  • trunk/src/wp-includes/blocks.php

    r48141 r48185  
    659659
    660660    /**
    661      * Allows render_block() to be shortcircuited, by returning a non-null value.
     661     * Allows render_block() to be short-circuited, by returning a non-null value.
    662662     *
    663663     * @since 5.1.0

  • trunk/src/wp-includes/canonical.php

    r48184 r48185  
    850850     * Filters whether to attempt to guess a redirect URL for a 404 request.
    851851     *
    852      * Passing a false value to the filter will disable the URL guessing
     852     * Returning a false value from the filter will disable the URL guessing
    853853     * and return early without performing a redirect.
    854854     *
    … …  
    856856     *
    857857     * @param bool $do_redirect_guess Whether to attempt to guess a redirect URL
    858      *                                for a 404 request. Default is true.
     858     *                                for a 404 request. Default true.
    859859     */
    860860    if ( false === apply_filters( 'do_redirect_guess_404_permalink', true ) ) {
    … …  
    865865     * Short-circuits the redirect URL guessing for 404 requests.
    866866     *
    867      * Passing a non-null value to the filter will effectively short-circuit
     867     * Returning a non-null value from the filter will effectively short-circuit
    868868     * the URL guessing, returning the passed value instead.
    869869     *
    … …  
    882882         * Filters whether to perform a strict guess for a 404 redirect.
    883883         *
    884          * Passing a truthy value to the filter will redirect only exact post_name matches.
     884         * Returning a truthy value from the filter will redirect only exact post_name matches.
    885885         *
    886886         * @since 5.5.0

  • trunk/src/wp-includes/class-wp-oembed.php

    r48121 r48185  
    382382         * replacing it with a routine that is more optimal for your setup.
    383383         *
    384          * Passing a non-null value to the filter will effectively short-circuit retrieval,
    385          * returning the passed value instead.
     384         * Returning a non-null value from the filter will effectively short-circuit retrieval
     385         * and return the passed value instead.
    386386         *
    387387         * @since 4.5.3

  • trunk/src/wp-includes/comment.php

    r48167 r48185  
    832832     *
    833833     * @since 2.1.0
    834      * @since 4.9.0 Returning a WP_Error value from the filter will shortcircuit comment insertion
     834     * @since 4.9.0 Returning a WP_Error value from the filter will short-circuit comment insertion
    835835     *              and allow skipping further processing.
    836836     *

  • trunk/src/wp-includes/formatting.php

    r48175 r48185  
    6565         * Filters whether to skip running wptexturize().
    6666         *
    67          * Passing false to the filter will effectively short-circuit wptexturize().
    68          * returning the original text passed to the function instead.
     67         * Returning false from the filter will effectively short-circuit wptexturize()
     68         * and return the original text passed to the function instead.
    6969         *
    7070         * The filter runs only once, the first time wptexturize() is called.

  • trunk/src/wp-includes/functions.php

    r48168 r48185  
    26552655     * Filters whether to treat the upload bits as an error.
    26562656     *
    2657      * Returning a non-array from the filter will effectively short-circuit preparing the upload
    2658      * bits, returning that value instead. An error message should be returned as a string.
     2657     * Returning a non-array from the filter will effectively short-circuit preparing the upload bits
     2658     * and return that value instead. An error message should be returned as a string.
    26592659     *
    26602660     * @since 3.0.0
    … …  
    45794579     * Filters whether to load the Widgets library.
    45804580     *
    4581      * Passing a falsey value to the filter will effectively short-circuit
     4581     * Returning a falsey value from the filter will effectively short-circuit
    45824582     * the Widgets library from loading.
    45834583     *
    … …  
    55815581         * Filters whether global terms are enabled.
    55825582         *
    5583          * Passing a non-null value to the filter will effectively short-circuit the function,
    5584          * returning the value of the 'global_terms_enabled' site option instead.
     5583         * Returning a non-null value from the filter will effectively short-circuit the function
     5584         * and return the value of the 'global_terms_enabled' site option instead.
    55855585         *
    55865586         * @since 3.0.0
    … …  
    64496449     * Filters whether to load the authentication check.
    64506450     *
    6451      * Passing a falsey value to the filter will effectively short-circuit
     6451     * Returning a falsey value from the filter will effectively short-circuit
    64526452     * loading the authentication check.
    64536453     *

  • trunk/src/wp-includes/link-template.php

    r48110 r48185  
    38583858     * Filters whether to preempt generating a shortlink for the given post.
    38593859     *
    3860      * Passing a truthy value to the filter will effectively short-circuit the
    3861      * shortlink-generation process, returning that value instead.
     3860     * Returning a truthy value from the filter will effectively short-circuit
     3861     * the shortlink generation process, returning that value instead.
    38623862     *
    38633863     * @since 3.0.0

  • trunk/src/wp-includes/media.php

    r48170 r48185  
    542542     * Filters whether to preempt calculating the image resize dimensions.
    543543     *
    544      * Passing a non-null value to the filter will effectively short-circuit
     544     * Returning a non-null value from the filter will effectively short-circuit
    545545     * image_resize_dimensions(), returning that value instead.
    546546     *
    … …  
    16261626 *
    16271627 * @param string $content The HTML content to be filtered.
    1628  * @param string $context Optional. Additional context to pass to the filters. Defaults to `current_filter()` when not set.
     1628 * @param string $context Optional. Additional context to pass to the filters.
     1629 *                        Defaults to `current_filter()` when not set.
    16291630 * @return string Converted content with images modified.
    16301631 */
    … …  
    23702371     * Filters the playlist output.
    23712372     *
    2372      * Passing a non-empty value to the filter will short-circuit generation
     2373     * Returning a non-empty value from the filter will short-circuit generation
    23732374     * of the default playlist output, returning the passed value instead.
    23742375     *

  • trunk/src/wp-includes/nav-menu-template.php

    r48109 r48185  
    9090     * Filters whether to short-circuit the wp_nav_menu() output.
    9191     *
    92      * Passing a non-null value to the filter will short-circuit
    93      * wp_nav_menu(), echoing that value if $args->echo is true,
    94      * returning that value otherwise.
     92     * Returning a non-null value from the filter will short-circuit wp_nav_menu(),
     93     * echoing that value if $args->echo is true, returning that value otherwise.
    9594     *
    9695     * @since 3.9.0

  • trunk/src/wp-includes/option.php

    r48121 r48185  
    4141     * The dynamic portion of the hook name, `$option`, refers to the option name.
    4242     *
    43      * Passing a truthy value to the filter will short-circuit retrieving
     43     * Returning a truthy value from the filter will short-circuit retrieving
    4444     * the option value, returning the passed value instead.
    4545     *
    … …  
    688688     * The dynamic portion of the hook name, `$transient`, refers to the transient name.
    689689     *
    690      * Passing a truthy value to the filter will effectively short-circuit retrieval
     690     * Returning a truthy value from the filter will effectively short-circuit retrieval
    691691     * of the transient, returning the passed value instead.
    692692     *
    … …  
    12381238     * The dynamic portion of the hook name, `$option`, refers to the option name.
    12391239     *
    1240      * Passing a truthy value to the filter will effectively short-circuit retrieval,
    1241      * returning the passed value instead.
     1240     * Returning a truthy value from the filter will effectively short-circuit retrieval
     1241     * and return the passed value instead.
    12421242     *
    12431243     * @since 2.9.0 As 'pre_site_option_' . $key
    … …  
    17511751     * The dynamic portion of the hook name, `$transient`, refers to the transient name.
    17521752     *
    1753      * Passing a truthy value to the filter will effectively short-circuit retrieval,
    1754      * returning the passed value instead.
     1753     * Returning a truthy value from the filter will effectively short-circuit retrieval
     1754     * and return the passed value instead.
    17551755     *
    17561756     * @since 2.9.0

  • trunk/src/wp-includes/post.php

    r48104 r48185  
    36863686     * 2. The title, editor, and excerpt fields are all empty
    36873687     *
    3688      * Passing a truthy value to the filter will effectively short-circuit
    3689      * the new post being inserted, returning 0. If $wp_error is true, a WP_Error
     3688     * Returning a truthy value from the filter will effectively short-circuit
     3689     * the new post being inserted and return 0. If $wp_error is true, a WP_Error
    36903690     * will be returned instead.
    36913691     *

  • trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php

    r48154 r48185  
    683683         *
    684684         * Allows modification of the comment right before it is inserted via wp_insert_comment().
    685          * Returning a WP_Error value from the filter will shortcircuit insertion and allow
     685         * Returning a WP_Error value from the filter will short-circuit insertion and allow
    686686         * skipping further processing.
    687687         *
    688688         * @since 4.7.0
    689          * @since 4.8.0 `$prepared_comment` can now be a WP_Error to shortcircuit insertion.
     689         * @since 4.8.0 `$prepared_comment` can now be a WP_Error to short-circuit insertion.
    690690         *
    691691         * @param array|WP_Error  $prepared_comment The prepared comment data for wp_insert_comment().

  • trunk/src/wp-includes/user.php

    r48121 r48185  
    609609     * Filters the list of a user's sites before it is populated.
    610610     *
    611      * Passing a non-null value to the filter will effectively short circuit
     611     * Returning a non-null value from the filter will effectively short circuit
    612612     * get_blogs_of_user(), returning that value instead.
    613613     *
Note: See TracChangeset for help on using the changeset viewer.