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 #10443

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

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


git-svn-id: https://develop.svn.wordpress.org/trunk@61111 602fd350-edb4-49c9-b593-d223f7449a82

Author: westonruter

src/wp-includes/class-wp.php

@@ -588,8 +588,8 @@ public function send_headers() {
 		/**
 		 * Fires once the requested HTTP headers for caching, content type, etc. have been sent.
 		 *
-		 * The {@see 'wp_send_late_headers'} action may be used to send headers after rendering the template into an
-		 * output buffer.
+		 * The {@see 'wp_finalized_template_enhancement_output_buffer'} action may be used to send
+		 * headers after rendering the template into an output buffer.
 		 *
 		 * @since 2.1.0
 		 *

src/wp-includes/default-filters.php

@@ -423,7 +423,7 @@
 add_action( 'do_all_pings', 'generic_ping', 10, 0 );
 add_action( 'do_robots', 'do_robots' );
 add_action( 'do_favicon', 'do_favicon' );
-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.
+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_finalized_template_enhancement_output_buffer` actions be registered.
 add_action( 'set_comment_cookies', 'wp_set_comment_cookies', 10, 3 );
 add_action( 'sanitize_comment_cookies', 'sanitize_comment_cookies' );
 add_action( 'init', 'smilies_init', 5 );

src/wp-includes/template.php

@@ -844,17 +844,17 @@ function wp_should_output_buffer_template_for_enhancement(): bool {
 	 * Filters whether the template should be output-buffered for enhancement.
 	 *
 	 * By default, an output buffer is only started if a {@see 'wp_template_enhancement_output_buffer'} filter has been
-	 * added or if a plugin has added a {@see 'wp_send_late_headers'} action. For this default to apply, either of the
-	 * hooks must be added by the time the template is included at the {@see 'wp_before_include_template'} action. This
-	 * allows template responses to be streamed unless the there is code which depends on an output buffer being opened.
-	 * This filter allows a site to opt in to adding such template enhancement filters later during the rendering of the
-	 * template.
+	 * added or if a plugin has added a {@see 'wp_finalized_template_enhancement_output_buffer'} action. For this
+	 * default to apply, either of the hooks must be added by the time the template is included at the
+	 * {@see 'wp_before_include_template'} action. This allows template responses to be streamed unless the there is
+	 * code which depends on an output buffer being opened. This filter allows a site to opt in to adding such template
+	 * enhancement filters later during the rendering of the template.
 	 *
 	 * @since 6.9.0
 	 *
 	 * @param bool $use_output_buffer Whether an output buffer is started.
 	 */
-	return (bool) apply_filters( 'wp_should_output_buffer_template_for_enhancement', has_filter( 'wp_template_enhancement_output_buffer' ) || has_action( 'wp_send_late_headers' ) );
+	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' ) );
 }
 
 /**
@@ -959,7 +959,7 @@ function wp_finalize_template_enhancement_output_buffer( string $output, int $ph
 	// If the content type is not HTML, short-circuit since it is not relevant for enhancement.
 	if ( ! $is_html_content_type ) {
 		/** This action is documented in wp-includes/template.php */
-		do_action( 'wp_send_late_headers', $output );
+		do_action( 'wp_finalized_template_enhancement_output_buffer', $output );
 		return $output;
 	}
 
@@ -975,6 +975,10 @@ function wp_finalize_template_enhancement_output_buffer( string $output, int $ph
 	 * (either `WP_HTML_Tag_Processor` or `WP_HTML_Processor`), or else use {@see DOM\HtmlDocument} as of PHP 8.4 which
 	 * fully supports HTML5.
 	 *
+	 * Important: Because this filter is applied inside an output buffer callback (i.e. display handler), any callbacks
+	 * added to the filter must not attempt to start their own output buffers. Otherwise, PHP will raise a fatal error:
+	 * "Cannot use output buffering in output buffering display handlers."
+	 *
 	 * @since 6.9.0
 	 *
 	 * @param string $filtered_output HTML template enhancement output buffer.
@@ -983,22 +987,28 @@ function wp_finalize_template_enhancement_output_buffer( string $output, int $ph
 	$filtered_output = (string) apply_filters( 'wp_template_enhancement_output_buffer', $filtered_output, $output );
 
 	/**
-	 * Fires at the last moment HTTP headers may be sent.
+	 * Fires after the template enhancement output buffer has been finalized.
 	 *
-	 * This happens immediately before the template enhancement output buffer is flushed. This is in contrast with
-	 * the {@see 'send_headers'} action which fires after the initial headers have been sent before the template
-	 * has begun rendering, and thus does not depend on output buffering. This action does not fire if the "template
-	 * enhancement output buffer" was not started. This output buffer is automatically started if this action is added
-	 * before {@see wp_start_template_enhancement_output_buffer()} runs at the {@see 'wp_before_include_template'}
-	 * action with priority 1000. Before this point, the output buffer will also be started automatically if there was a
+	 * This happens immediately before the template enhancement output buffer is flushed. No output may be printed at
+	 * this action. However, HTTP headers may be sent, which makes this action complimentary to the
+	 * {@see 'send_headers'} action, in which headers may be sent before the template has started rendering. In
+	 * contrast, this `wp_finalized_template_enhancement_output_buffer` action is the possible point at which HTTP
+	 * headers can be sent. This action does not fire if the "template enhancement output buffer" was not started. This
+	 * output buffer is automatically started if this action is added before
+	 * {@see wp_start_template_enhancement_output_buffer()} runs at the {@see 'wp_before_include_template'} action with
+	 * priority 1000. Before this point, the output buffer will also be started automatically if there was a
 	 * {@see 'wp_template_enhancement_output_buffer'} filter added, or if the
 	 * {@see 'wp_should_output_buffer_template_for_enhancement'} filter is made to return `true`.
 	 *
+	 * Important: Because this action fires inside an output buffer callback (i.e. display handler), any callbacks added
+	 * to the action must not attempt to start their own output buffers. Otherwise, PHP will raise a fatal error:
+	 * "Cannot use output buffering in output buffering display handlers."
+	 *
 	 * @since 6.9.0
 	 *
-	 * @param string $output Output buffer.
+	 * @param string $output Finalized output buffer.
 	 */
-	do_action( 'wp_send_late_headers', $filtered_output );
+	do_action( 'wp_finalized_template_enhancement_output_buffer', $filtered_output );
 
 	return $filtered_output;
 }

tests/phpunit/tests/template.php

@@ -646,7 +646,7 @@ public function test_wp_start_template_enhancement_output_buffer_for_html(): voi
 
 		$mock_action_callback = new MockAction();
 		add_filter(
-			'wp_send_late_headers',
+			'wp_finalized_template_enhancement_output_buffer',
 			array( $mock_action_callback, 'action' ),
 			10,
 			PHP_INT_MAX
@@ -733,11 +733,11 @@ static function ( string $buffer ): string {
 		$this->assertStringContainsString( '<h1>¡Hola, mundo!</h1>', $processed_output, 'Expected processed output to contain string.' );
 		$this->assertStringContainsString( '</html>', $processed_output, 'Expected processed output to contain string.' );
 
-		$this->assertSame( 1, did_action( 'wp_send_late_headers' ), 'Expected the wp_send_late_headers action to have fired.' );
-		$this->assertSame( 1, $mock_action_callback->get_call_count(), 'Expected wp_send_late_headers action callback to have been called once.' );
+		$this->assertSame( 1, did_action( 'wp_finalized_template_enhancement_output_buffer' ), 'Expected the wp_finalized_template_enhancement_output_buffer action to have fired.' );
+		$this->assertSame( 1, $mock_action_callback->get_call_count(), 'Expected wp_finalized_template_enhancement_output_buffer action callback to have been called once.' );
 		$action_args = $mock_action_callback->get_args()[0];
-		$this->assertCount( 1, $action_args, 'Expected the wp_send_late_headers action to have been passed only one argument.' );
-		$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.' );
+		$this->assertCount( 1, $action_args, 'Expected the wp_finalized_template_enhancement_output_buffer action to have been passed only one argument.' );
+		$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.' );
 	}
 
 	/**
@@ -772,7 +772,7 @@ static function ( string $buffer ): string {
 
 		$mock_action_callback = new MockAction();
 		add_filter(
-			'wp_send_late_headers',
+			'wp_finalized_template_enhancement_output_buffer',
 			array( $mock_action_callback, 'action' ),
 			10,
 			PHP_INT_MAX
@@ -818,8 +818,8 @@ static function ( string $buffer ): string {
 		$this->assertStringNotContainsString( '<title>Processed</title>', $output, 'Expected output buffer to not have string since the filter did not apply.' );
 		$this->assertStringContainsString( '<title>Output Buffer Not Processed</title>', $output, 'Expected output buffer to have string since the output buffer was ended with cleaning.' );
 
-		$this->assertSame( 0, did_action( 'wp_send_late_headers' ), 'Expected the wp_send_late_headers action to not have fired.' );
-		$this->assertSame( 0, $mock_action_callback->get_call_count(), 'Expected wp_send_late_headers action callback to have been called once.' );
+		$this->assertSame( 0, did_action( 'wp_finalized_template_enhancement_output_buffer' ), 'Expected the wp_finalized_template_enhancement_output_buffer action to not have fired.' );
+		$this->assertSame( 0, $mock_action_callback->get_call_count(), 'Expected wp_finalized_template_enhancement_output_buffer action callback to have been called once.' );
 	}
 
 	/**
@@ -854,7 +854,7 @@ static function ( string $buffer ): string {
 
 		$mock_action_callback = new MockAction();
 		add_filter(
-			'wp_send_late_headers',
+			'wp_finalized_template_enhancement_output_buffer',
 			array( $mock_action_callback, 'action' ),
 			10,
 			PHP_INT_MAX
@@ -905,11 +905,11 @@ static function ( string $buffer ): string {
 		$this->assertStringContainsString( '<title>Processed</title>', $output, 'Expected output buffer to have string due to filtering.' );
 		$this->assertStringContainsString( '<h1>Template Replaced</h1>', $output, 'Expected output buffer to have string due to replaced template.' );
 
-		$this->assertSame( 1, did_action( 'wp_send_late_headers' ), 'Expected the wp_send_late_headers action to have fired.' );
-		$this->assertSame( 1, $mock_action_callback->get_call_count(), 'Expected wp_send_late_headers action callback to have been called once.' );
+		$this->assertSame( 1, did_action( 'wp_finalized_template_enhancement_output_buffer' ), 'Expected the wp_finalized_template_enhancement_output_buffer action to have fired.' );
+		$this->assertSame( 1, $mock_action_callback->get_call_count(), 'Expected wp_finalized_template_enhancement_output_buffer action callback to have been called once.' );
 		$action_args = $mock_action_callback->get_args()[0];
-		$this->assertCount( 1, $action_args, 'Expected the wp_send_late_headers action to have been passed only one argument.' );
-		$this->assertSame( $output, $action_args[0], 'Expected the arg passed to wp_send_late_headers to be the same as the processed output buffer.' );
+		$this->assertCount( 1, $action_args, 'Expected the wp_finalized_template_enhancement_output_buffer action to have been passed only one argument.' );
+		$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.' );
 	}
 
 	/**
@@ -930,7 +930,7 @@ public function test_wp_start_template_enhancement_output_buffer_for_json(): voi
 
 		$mock_action_callback = new MockAction();
 		add_filter(
-			'wp_send_late_headers',
+			'wp_finalized_template_enhancement_output_buffer',
 			array( $mock_action_callback, 'action' ),
 			10,
 			PHP_INT_MAX
@@ -970,11 +970,11 @@ public function test_wp_start_template_enhancement_output_buffer_for_json(): voi
 		$this->assertIsString( $output, 'Expected ob_get_clean() to return a string.' );
 		$this->assertSame( $json, $output, 'Expected output to not be processed.' );
 
-		$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.' );
-		$this->assertSame( 1, $mock_action_callback->get_call_count(), 'Expected wp_send_late_headers action callback to have been called once.' );
+		$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.' );
+		$this->assertSame( 1, $mock_action_callback->get_call_count(), 'Expected wp_finalized_template_enhancement_output_buffer action callback to have been called once.' );
 		$action_args = $mock_action_callback->get_args()[0];
-		$this->assertCount( 1, $action_args, 'Expected the wp_send_late_headers action to have been passed only one argument.' );
-		$this->assertSame( $output, $action_args[0], 'Expected the arg passed to wp_send_late_headers to be the same as the processed output buffer.' );
+		$this->assertCount( 1, $action_args, 'Expected the wp_finalized_template_enhancement_output_buffer action to have been passed only one argument.' );
+		$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.' );
 	}
 
 	/**