云策 WordPress 开发者社区

函数文档

wp_start_template_enhancement_output_buffer()

查看官方原文 ↗
💡 云策文档标注

概述

wp_start_template_enhancement_output_buffer() 函数用于启动模板增强输出缓冲区，在包含模板前调用，以捕获整个响应进行处理。

关键要点

  • 函数在模板包含前立即调用，启动输出缓冲区以支持模板增强功能。
  • 返回布尔值，指示输出缓冲区是否成功启动。
  • 内部检查 wp_should_output_buffer_template_for_enhancement() 决定是否启动缓冲区。
  • 使用 ob_start() 启动缓冲区，指定回调函数为 wp_finalize_template_enhancement_output_buffer，缓冲区大小无限制。
  • 缓冲区标志设置为 PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_FLUSHABLE，确保不可刷新以处理完整输出。
  • 成功启动时触发 wp_template_enhancement_output_buffer_started 动作钩子。

代码示例

function wp_start_template_enhancement_output_buffer(): bool {
    if ( ! wp_should_output_buffer_template_for_enhancement() ) {
        return false;
    }

    $started = ob_start(
        'wp_finalize_template_enhancement_output_buffer',
        0,
        PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_FLUSHABLE
    );

    if ( $started ) {
        do_action( 'wp_template_enhancement_output_buffer_started' );
    }

    return $started;
}

注意事项

  • 缓冲区不可刷新（PHP_OUTPUT_HANDLER_FLUSHABLE 被移除），以确保整个输出能被处理，例如优化完整 HTML 文档。
  • 缓冲区需可移除，以兼容 WordPress 的 wp_ob_end_flush_all() 和 wp_cache_close() 调用。
  • 如果添加 PHP_OUTPUT_HANDLER_FLUSHABLE 标志，回调函数需检查处理阶段并可能触发 _doing_it_wrong()。
📄 原文内容

Starts the template enhancement output buffer.

Description

This function is called immediately before the template is included.

Return

bool Whether the output buffer successfully started.

Source

function wp_start_template_enhancement_output_buffer(): bool {
	if ( ! wp_should_output_buffer_template_for_enhancement() ) {
		return false;
	}

	$started = ob_start(
		'wp_finalize_template_enhancement_output_buffer',
		0, // Unlimited buffer size so that entire output is passed to the filter.
		/*
		 * Instead of the default PHP_OUTPUT_HANDLER_STDFLAGS (cleanable, flushable, and removable) being used for
		 * flags, the PHP_OUTPUT_HANDLER_FLUSHABLE flag must be omitted. If the buffer were flushable, then each time
		 * that ob_flush() is called, a fragment of the output would be sent into the output buffer callback. This
		 * output buffer is intended to capture the entire response for processing, as indicated by the chunk size of 0.
		 * So the buffer does not allow flushing to ensure the entire buffer can be processed, such as for optimizing an
		 * entire HTML document, where markup in the HEAD may need to be adjusted based on markup that appears late in
		 * the BODY.
		 *
		 * If this ends up being problematic, then PHP_OUTPUT_HANDLER_FLUSHABLE could be added to the $flags and the
		 * output buffer callback could check if the phase is PHP_OUTPUT_HANDLER_FLUSH and abort any subsequent
		 * processing while also emitting a _doing_it_wrong().
		 *
		 * The output buffer needs to be removable because WordPress calls wp_ob_end_flush_all() and then calls
		 * wp_cache_close(). If the buffers are not all flushed before wp_cache_close() is closed, then some output buffer
		 * handlers (e.g. for caching plugins) may fail to be able to store the page output in the object cache.
		 * See <https://github.com/WordPress/performance/pull/1317#issuecomment-2271955356>.
		 */
		PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_FLUSHABLE
	);

	if ( $started ) {
		/**
		 * Fires when the template enhancement output buffer has started.
		 *
		 * @since 6.9.0
		 */
		do_action( 'wp_template_enhancement_output_buffer_started' );
	}

	return $started;
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘wp_template_enhancement_output_buffer_started’ )

Fires when the template enhancement output buffer has started.

Uses Description
wp_should_output_buffer_template_for_enhancement()wp-includes/template.php

Checks whether the template should be output buffered for enhancement.
do_action()wp-includes/plugin.php

Calls the callback functions that have been added to an action hook.

Changelog

Version Description
6.9.0 Introduced.