Finalize the tag registry after the od_register_tag_visitors action h…

…as fired
WordPress · westonruter · Mar 15, 2025 · Mar 12, 2025 · Mar 12, 2025 · Mar 12, 2025
commit 8bcfc13c88131515de70e6618f9daf074f93e698
diff --git a/plugins/optimization-detective/class-od-tag-visitor-registry.php b/plugins/optimization-detective/class-od-tag-visitor-registry.php
@@ -32,18 +32,43 @@ final class OD_Tag_Visitor_Registry implements Countable, IteratorAggregate {
 	 */
 	private $visitors = array();
 
+	/**
+	 * Whether finalized.
+	 *
+	 * @since n.e.x.t
+	 * @var bool
+	 */
+	private $is_finalized = false;
+
+	/**
+	 * Finalizes the registry to prevent further modifications.
+	 *
+	 * @since n.e.x.t
+	 * @access private
+	 */
+	public function finalize(): void {
+		$this->is_finalized = true;
+	}
+
 	/**
 	 * Registers a tag visitor.
 	 *
 	 * @since 0.3.0
+	 * @since n.e.x.t Returns boolean for whether registration is successful. Returns false if registry is finalized.
 	 *
 	 * @phpstan-param TagVisitorCallback $tag_visitor_callback
 	 *
 	 * @param non-empty-string $id                   Identifier for the tag visitor.
 	 * @param callable         $tag_visitor_callback Tag visitor callback.
+	 * @return bool Whether a tag visitor was registered.
 	 */
-	public function register( string $id, callable $tag_visitor_callback ): void {
+	public function register( string $id, callable $tag_visitor_callback ): bool {
+		if ( $this->is_finalized ) {
+			_doing_it_wrong( __METHOD__, esc_html( $this->get_finalized_message() ), 'optimization-detective 1.0.0' );
+			return false;
+		}
 		$this->visitors[ $id ] = $tag_visitor_callback;
+		return true;
 	}
 
 	/**
@@ -77,11 +102,16 @@ public function get_registered( string $id ): ?callable {
 	 * Unregisters a tag visitor.
 	 *
 	 * @since 0.3.0
+	 * @since n.e.x.t Returns false if the registry is finalized.
 	 *
 	 * @param non-empty-string $id Identifier for the tag visitor.
 	 * @return bool Whether a tag visitor was unregistered.
 	 */
 	public function unregister( string $id ): bool {
+		if ( $this->is_finalized ) {
+			_doing_it_wrong( __METHOD__, esc_html( $this->get_finalized_message() ), 'optimization-detective 1.0.0' );
+			return false;
+		}
 		if ( ! $this->is_registered( $id ) ) {
 			return false;
 		}
@@ -110,4 +140,19 @@ public function getIterator(): ArrayIterator {
 	public function count(): int {
 		return count( $this->visitors );
 	}
+
+	/**
+	 * Gets the finalized message when attempting to mutate the registry after the od_register_tag_visitors action.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return string Message.
+	 */
+	private function get_finalized_message(): string {
+		return sprintf(
+			/* translators: %s is the od_register_tag_visitors action */
+			__( 'The tag visitor registry has already been finalized. This method must be called during the %s action.', 'optimization-detective' ),
+			'od_register_tag_visitors'
+		);
+	}
 }
@@ -153,17 +153,21 @@ function od_add_template_output_buffer_filter( $template ) {
 	 */
 	do_action( 'od_register_tag_visitors', $tag_visitor_registry );
 
+	// Prevent modification of the tag visitor registry since doing so would invalidate the etag.
+	$tag_visitor_registry->finalize();
+
 	global $wp_the_query;
 	$current_theme_template = od_get_current_theme_template( is_string( $template ) ? $template : null );
 	$current_etag           = od_get_current_url_metrics_etag( $tag_visitor_registry, $wp_the_query, $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,
+		// TODO: Add the following values to the context as well.
 		od_get_breakpoint_max_widths(),
 		od_get_url_metrics_breakpoint_sample_size(),
 		od_get_url_metric_freshness_ttl()
-	);
-	$link_collection  = new OD_Link_Collection();
+	); // TODO: Also finalize the collection?
+	$link_collection = new OD_Link_Collection();
 
 	$context = new OD_Template_Optimization_Context(
 		$group_collection,