Revamp Server-Timing API to simplify API usage.

Author: felixarntz

server-timing/class-perflab-server-timing-metric.php

@@ -22,13 +22,21 @@ class Perflab_Server_Timing_Metric {
 	private $slug;
 
 	/**
-	 * The metric value.
+	 * The metric value in milliseconds.
 	 *
 	 * @since n.e.x.t
 	 * @var int|float|null
 	 */
 	private $value;
 
+	/**
+	 * The value measured before relevant execution logic in seconds, if used.
+	 *
+	 * @since n.e.x.t
+	 * @var float|null
+	 */
+	private $before_value;
+
 	/**
 	 * Constructor.
 	 *
@@ -54,6 +62,9 @@ public function get_slug() {
 	/**
 	 * Sets the metric value.
 	 *
+	 * Alternatively to setting the metric value directly, the {@see Perflab_Server_Timing_Metric::measure_before()}
+	 * and {@see Perflab_Server_Timing_Metric::measure_after()} methods can be used to further simplify measuring.
+	 *
 	 * @since n.e.x.t
 	 *
 	 * @param int|float $value The metric value to set, in milliseconds.
@@ -90,4 +101,38 @@ public function set_value( $value ) {
 	public function get_value() {
 		return $this->value;
 	}
+
+	/**
+	 * Captures the current time, as a reference point to calculate the duration of a task afterwards.
+	 *
+	 * This should be used in combination with {@see Perflab_Server_Timing_Metric::measure_after()}. Alternatively,
+	 * {@see Perflab_Server_Timing_Metric::set_value()} can be used to set a calculated value manually.
+	 *
+	 * @since n.e.x.t
+	 */
+	public function measure_before() {
+		$this->before_value = microtime( true );
+	}
+
+	/**
+	 * Captures the current time and compares it to the reference point to calculate a task's duration.
+	 *
+	 * This should be used in combination with {@see Perflab_Server_Timing_Metric::measure_before()}. Alternatively,
+	 * {@see Perflab_Server_Timing_Metric::set_value()} can be used to set a calculated value manually.
+	 *
+	 * @since n.e.x.t
+	 */
+	public function measure_after() {
+		if ( ! $this->before_value ) {
+			_doing_it_wrong(
+				__METHOD__,
+				/* translators: %s: PHP method name */
+				sprintf( __( 'The %s method must be called before.', 'performance-lab' ), __CLASS__ . '::measure_before()' ),
+				''
+			);
+			return;
+		}
+
+		$this->set_value( ( microtime( true ) - $this->before_value ) * 1000.0 );
+	}
 }

server-timing/class-perflab-server-timing.php

@@ -32,6 +32,8 @@ class Perflab_Server_Timing {
 	/**
 	 * Registers a metric to calculate for the Server-Timing header.
 	 *
+	 * This method must be called before the {@see 'perflab_server_timing_send_header'} hook.
+	 *
 	 * @since n.e.x.t
 	 *
 	 * @param string $metric_slug The metric slug.
@@ -47,6 +49,16 @@ class Perflab_Server_Timing {
 	 * }
 	 */
 	public function register_metric( $metric_slug, array $args ) {
+		if ( did_action( 'perflab_server_timing_send_header' ) && ! doing_action( 'perflab_server_timing_send_header' ) ) {
+			_doing_it_wrong(
+				__METHOD__,
+				/* translators: %s: WordPress action name */
+				sprintf( __( 'The method must be called before or during the %s action.', 'performance-lab' ), 'perflab_server_timing_send_header' ),
+				''
+			);
+			return;
+		}
+
 		$args = wp_parse_args(
 			$args,
 			array(
@@ -93,7 +105,7 @@ public function register_metric( $metric_slug, array $args ) {
 	 *
 	 * @since n.e.x.t
 	 */
-	public function add_header() {
+	public function send_header() {
 		if ( headers_sent() ) {
 			_doing_it_wrong(
 				__METHOD__,
@@ -103,6 +115,15 @@ public function add_header() {
 			return;
 		}
 
+		/**
+		 * Fires right before the Server-Timing header is sent.
+		 *
+		 * This action is the last possible point to register a Server-Timing metric.
+		 *
+		 * @since n.e.x.t
+		 */
+		do_action( 'perflab_server_timing_send_header' );
+
 		$header_value = $this->get_header_value();
 		if ( ! $header_value ) {
 			return;
@@ -145,6 +166,55 @@ function( $value ) {
 		return implode( ', ', $metric_header_values );
 	}
 
+	/**
+	 * Returns whether an output buffer should be used to gather Server-Timing metrics during template rendering.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return bool True if an output buffer should be used, false otherwise.
+	 */
+	public function use_output_buffer() {
+		/**
+		 * Filters whether an output buffer should be used to be able to gather additional Server-Timing metrics.
+		 *
+		 * @since n.e.x.t
+		 *
+		 * @param bool $use_output_buffer Whether to use an output buffer.
+		 */
+		return apply_filters( 'perflab_server_timing_use_output_buffer', false );
+	}
+
+	/**
+	 * Hook callback for the 'template_include' filter.
+	 *
+	 * This effectively initializes the class to send the Server-Timing header at the right point.
+	 *
+	 * This method is solely intended for internal use within WordPress.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param mixed $passthrough Optional. Filter value. Default null.
+	 * @return mixed Unmodified value of $passthrough.
+	 */
+	public function on_template_include( $passthrough = null ) {
+		if ( ! $this->use_output_buffer() ) {
+			$this->send_header();
+			return $passthrough;
+		}
+
+		ob_start();
+		add_action(
+			'shutdown',
+			function() {
+				$output = ob_get_clean();
+				$this->send_header();
+				echo $output;
+			},
+			-1000
+		);
+		return $passthrough;
+	}
+
 	/**
 	 * Formats the header segment for a single metric.
 	 *