Introduce wp_send_late_headers action for sending headers right before template enhancement output buffer is flushed

[westonruter]

• Introduce wp_send_late_headers action which fires right right after wp_template_enhancement_output_buffer filters have applied, and right before the output buffer is flushed. The output buffer is passed as an argument to the function so that plugins may do things like send an ETag header calculated from the content.
• The template enhancement output buffer now is enabled by default if either there is a wp_template_enhancement_output_buffer filter added or there is a wp_send_late_headers action added.
• The wp_start_template_enhancement_output_buffer() callback for the wp_before_include_template action is increased from the default 10 to 1000. This goes with the previous point, so that plugins can add those filters and actions during the wp_before_include_template action without having to worry about adding them too late, that is, after wp_start_template_enhancement_output_buffer() has run.
• The wp_send_late_headers action fires regardless of whether the buffered response is HTML.

Trac ticket: https://core.trac.wordpress.org/ticket/64126

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• The Plugin and Theme Directories cannot be accessed within Playground.
• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props westonruter, johnbillion.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[westonruter]

@dmsnell @johnbillion Here's two example use cases for this action.

Sending Server-Timing

This shows how to measure how long it takes a template to render and to send that as a Server-Timing header. Note that if there is an wp_send_late_headers action added, then the template enhancement buffer will automatically be opened, the same as if there are any wp_template_enhancement_output_buffer filters added:

add_action(
	'wp_before_include_template',
	static function (): void {
		$start_time = hrtime( true );

		add_action(
			'wp_send_late_headers',
			static function () use ( $start_time ): void {
				$server_timing_header = sprintf(
					'Server-Timing: wpTemplate; desc="Template render"; dur=%f',
					( hrtime( true ) - $start_time ) / 1000000
				);
				header( $server_timing_header, false );
			}
		);
	}
);

The wp_before_include_template action was newly introduced with the template enhancement output buffer.

HTTP Conditional Requests

The wp_send_late_headers action can be used to implement conditional requests. Since the wp_send_late_headers action proposed in this PR sends the output buffer as an argument this can be used to compute an ETag to send as a header. In the same action, it can check to see if the client has sent that same ETag in an If-None-Match request header, and of so, send back a 304 Not Modified response:

add_action(
	'wp_send_late_headers',
	static function ( string $response ) {
		$etag = '"' . md5( $response ) . '"';
		header( "ETag: $etag" );
		header( 'Cache-Control: public, max-age=3600' );

		if ( isset( $_SERVER['HTTP_IF_NONE_MATCH'] ) ) {
			$client_etag = wp_unslash( $_SERVER['HTTP_IF_NONE_MATCH'] );
			if ( $client_etag === $etag ) {
				status_header( 304 );
			}
		}
	}
);

I find that if PHP sends a 304 response header, that it also omits sending any response body. This prevents the need to try to use the wp_before_include_template filter to empty out the response. But if need be, this could be made explicit:

diff --git a/src/wp-includes/template.php b/src/wp-includes/template.php
index 035b7e16b9..19984ca9ab 100644
--- a/src/wp-includes/template.php
+++ b/src/wp-includes/template.php
@@ -998,5 +998,9 @@ function wp_finalize_template_enhancement_output_buffer( string $output, int $ph
 
 	$do_send_late_headers( $filtered_output );
 
+	if ( 304 === http_response_code() ) {
+		$filtered_output = '';
+	}
+
 	return $filtered_output;
 }