Fire actions before and after Optimization Detective processes a document

plugins/image-prioritizer/class-image-prioritizer-background-image-styled-tag-visitor.php

@@ -143,6 +143,7 @@ private function get_common_lcp_element_external_background_image( OD_URL_Metric
 	private function maybe_preload_external_lcp_background_image( OD_Tag_Visitor_Context $context ): void {
 		// Gather the tuples of URL Metric group and the common LCP element external background image.
 		// Note the groups of URL Metrics do not change across invocations, we just need to compute this once for all.
+		// TODO: Instead of populating this here, it could be done once per invocation during the od_start_template_optimization action since the page's OD_URL_Metric_Group_Collection is available there.
 		if ( ! is_array( $this->group_common_lcp_element_external_background_images ) ) {
 			$this->group_common_lcp_element_external_background_images = array();
 			foreach ( $context->url_metric_group_collection as $group ) {

plugins/optimization-detective/class-od-template-optimization-context.php

@@ -0,0 +1,165 @@
+<?php
+/**
+ * Optimization Detective: OD_Template_Optimization_Context class
+ *
+ * @package optimization-detective
+ * @since n.e.x.t
+ */
+
+// @codeCoverageIgnoreStart
+if ( ! defined( 'ABSPATH' ) ) {
+	exit; // Exit if accessed directly.
+}
+// @codeCoverageIgnoreEnd
+
+/**
+ * Context for optimizing a template.
+ *
+ * @since n.e.x.t
+ *
+ * @property-read OD_URL_Metric_Group_Collection $url_metric_group_collection URL Metric group collection.
+ * @property-read OD_Tag_Visitor_Registry        $tag_visitor_registry        Tag visitor registry.
+ * @property-read positive-int|null              $url_metrics_id              ID for the od_url_metrics post which provided the URL Metrics in the collection.
+ * @property-read array<string, mixed>           $normalized_query_vars       Normalized query vars.
+ * @property-read non-empty-string               $url_metrics_slug            Slug for the od_url_metrics post.
+ * @property-read OD_Link_Collection             $link_collection             Link collection.
+ */
+final class OD_Template_Optimization_Context {
+
+	/**
+	 * URL Metric group collection.
+	 *
+	 * @since n.e.x.t
+	 * @var OD_URL_Metric_Group_Collection
+	 */
+	private $url_metric_group_collection;
+
+	/**
+	 * HTML Tag Processor.
+	 *
+	 * This object is not directly exposed with an accessor property. This class exposes {@see self::append_head_html()}
+	 * and {@see self::append_body_html()} methods which wrap calls to the underlying
+	 * {@see OD_HTML_Tag_Processor::append_head_html()} and {@see OD_HTML_Tag_Processor::append_body_html()}.s
+	 *
+	 * @since n.e.x.t
+	 * @var OD_HTML_Tag_Processor
+	 */
+	private $processor;
+
+	/**
+	 * ID for the od_url_metrics post which provided the URL Metrics in the collection.
+	 *
+	 * May be null if no post has been created yet.
+	 *
+	 * @since n.e.x.t
+	 * @var positive-int|null
+	 */
+	private $url_metrics_id;
+
+	/**
+	 * Normalized query vars.
+	 *
+	 * @since n.e.x.t
+	 * @var array<string, mixed>
+	 */
+	private $normalized_query_vars;
+
+	/**
+	 * Slug for the od_url_metrics post.
+	 *
+	 * @since n.e.x.t
+	 * @var non-empty-string
+	 */
+	private $url_metrics_slug;
+
+	/**
+	 * Link collection.
+	 *
+	 * @since n.e.x.t
+	 * @var OD_Link_Collection
+	 */
+	private $link_collection;
+
+	/**
+	 * Constructor.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param OD_HTML_Tag_Processor          $processor                   HTML Tag Processor.
+	 * @param OD_URL_Metric_Group_Collection $url_metric_group_collection URL Metric group collection.
+	 * @param OD_Link_Collection             $link_collection             Link collection.
+	 * @param array<string, mixed>           $normalized_query_vars       Normalized query vars.
+	 * @param non-empty-string               $url_metrics_slug            Slug for the od_url_metrics post.
+	 * @param positive-int|null              $url_metrics_id              ID for the od_url_metrics post which provided the URL Metrics in the collection. May be null if no post has been created yet.
+	 */
+	public function __construct( OD_HTML_Tag_Processor $processor, OD_URL_Metric_Group_Collection $url_metric_group_collection, OD_Link_Collection $link_collection, array $normalized_query_vars, string $url_metrics_slug, ?int $url_metrics_id ) {
+		$this->processor                   = $processor;
+		$this->url_metric_group_collection = $url_metric_group_collection;
+		$this->link_collection             = $link_collection;
+		$this->normalized_query_vars       = $normalized_query_vars;
+		$this->url_metrics_slug            = $url_metrics_slug;
+		$this->url_metrics_id              = $url_metrics_id;
+	}
+
+	/**
+	 * Append HTML to the HEAD.
+	 *
+	 * The provided HTML must be valid! No validation is performed.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param non-empty-string $html HTML to inject.
+	 */
+	public function append_head_html( string $html ): void {
+		$this->processor->append_head_html( $html );
+	}
+
+	/**
+	 * Append HTML to the BODY.
+	 *
+	 * The provided HTML must be valid! No validation is performed.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param non-empty-string $html HTML to inject.
+	 */
+	public function append_body_html( string $html ): void {
+		$this->processor->append_body_html( $html );
+	}
+
+	/**
+	 * Gets a property.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param string $name Property name.
+	 * @return mixed Property value.
+	 *
+	 * @throws Error When property is unknown.
+	 */
+	public function __get( string $name ) {
+		// Note: The $processor is intentionally not exposed.
+		switch ( $name ) {
+			case 'url_metrics_id':
+				return $this->url_metrics_id;
+			case 'url_metric_group_collection':
+				return $this->url_metric_group_collection;
+			case 'normalized_query_vars':
+				return $this->normalized_query_vars;
+			case 'url_metrics_slug':
+				return $this->url_metrics_slug;
+			case 'link_collection':
+				return $this->link_collection;
+			default:
+				throw new Error(
+					esc_html(
+						sprintf(
+							/* translators: %s is class member variable name */
+							__( 'Unknown property %s.', 'optimization-detective' ),
+							__CLASS__ . '::$' . $name
+						)
+					)
+				);
+		}
+	}
+}

plugins/optimization-detective/load.php

@@ -121,6 +121,7 @@
 		require_once __DIR__ . '/detection.php';
 
 		// Optimization logic.
+		require_once __DIR__ . '/class-od-template-optimization-context.php';
 		require_once __DIR__ . '/class-od-link-collection.php';
 		require_once __DIR__ . '/class-od-tag-visitor-registry.php';
 		require_once __DIR__ . '/class-od-visited-tag-state.php';

plugins/optimization-detective/optimization.php

@@ -245,8 +245,10 @@ function od_optimize_template_output_buffer( string $buffer ): string {
 		return $buffer;
 	}
 
-	$slug = od_get_url_metrics_slug( od_get_normalized_query_vars() );
-	$post = OD_URL_Metrics_Post_Type::get_post( $slug );
+	$query_vars = od_get_normalized_query_vars();
+	$slug       = od_get_url_metrics_slug( $query_vars );
+	$post       = OD_URL_Metrics_Post_Type::get_post( $slug );
+	$post_id    = $post instanceof WP_Post && $post->ID > 0 ? $post->ID : null;
 
 	$tag_visitor_registry = new OD_Tag_Visitor_Registry();
 
@@ -259,22 +261,41 @@ function od_optimize_template_output_buffer( string $buffer ): string {
 	 */
 	do_action( 'od_register_tag_visitors', $tag_visitor_registry );
 
-	$current_etag         = od_get_current_url_metrics_etag( $tag_visitor_registry, $wp_the_query, od_get_current_theme_template() );
-	$group_collection     = new OD_URL_Metric_Group_Collection(
+	$current_etag     = od_get_current_url_metrics_etag( $tag_visitor_registry, $wp_the_query, od_get_current_theme_template() );
+	$group_collection = new OD_URL_Metric_Group_Collection(
 		$post instanceof WP_Post ? OD_URL_Metrics_Post_Type::get_url_metrics_from_post( $post ) : array(),
 		$current_etag,
 		od_get_breakpoint_max_widths(),
 		od_get_url_metrics_breakpoint_sample_size(),
 		od_get_url_metric_freshness_ttl()
 	);
-	$link_collection      = new OD_Link_Collection();
+	$link_collection  = new OD_Link_Collection();
+
+	$context = new OD_Template_Optimization_Context(
+		$processor,
+		$group_collection,
+		$link_collection,
+		$query_vars,
+		$slug,
+		$post_id
+	);
+
+	/**
+	 * Fires before Optimization Detective starts optimizing the template.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param OD_Template_Optimization_Context $context Template optimization context.
+	 */
+	do_action( 'od_start_template_optimization', $context );
+
 	$visited_tag_state    = new OD_Visited_Tag_State();
 	$tag_visitor_context  = new OD_Tag_Visitor_Context(
 		$processor,
 		$group_collection,
 		$link_collection,
 		$visited_tag_state,
-		$post instanceof WP_Post && $post->ID > 0 ? $post->ID : null
+		$post_id
 	);
 	$current_tag_bookmark = 'optimization_detective_current_tag';
 	$visitors             = iterator_to_array( $tag_visitor_registry );
@@ -337,5 +358,14 @@ function od_optimize_template_output_buffer( string $buffer ): string {
 		$processor->append_body_html( od_get_detection_script( $slug, $group_collection ) );
 	}
 
+	/**
+	 * Fires after Optimization Detective finishes optimizing the template.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param OD_Template_Optimization_Context $context Template optimization context.
+	 */
+	do_action( 'od_finish_template_optimization', $context );
+
 	return $processor->get_updated_html();
 }