Merge pull request #1932 from WordPress/publish/2025-03-17

Prepare 2025-03-17 release

Author: westonruter

plugins/embed-optimizer/load.php

@@ -5,7 +5,7 @@
  * Description: Optimizes the performance of embeds through lazy-loading, preconnecting, and reserving space to reduce layout shifts.
  * Requires at least: 6.6
  * Requires PHP: 7.2
- * Version: 1.0.0-beta1
+ * Version: 1.0.0-beta2
  * Author: WordPress Performance Team
  * Author URI: https://make.wordpress.org/performance/
  * License: GPLv2 or later
@@ -71,7 +71,7 @@ static function ( string $global_var_name, string $version, Closure $load ): voi
 	}
 )(
 	'embed_optimizer_pending_plugin',
-	'1.0.0-beta1',
+	'1.0.0-beta2',
 	static function ( string $version ): void {
 		if ( defined( 'EMBED_OPTIMIZER_VERSION' ) ) {
 			return;

plugins/embed-optimizer/readme.txt

@@ -2,7 +2,7 @@
 
 Contributors: wordpressdotorg
 Tested up to: 6.7
-Stable tag:   1.0.0-beta1
+Stable tag:   1.0.0-beta2
 License:      GPLv2 or later
 License URI:  https://www.gnu.org/licenses/gpl-2.0.html
 Tags:         performance, embeds
@@ -67,6 +67,13 @@ The [plugin source code](https://github.com/WordPress/performance/tree/trunk/plu
 
 == Changelog ==
 
+= 1.0.0-beta2 =
+
+**Enhancements**
+
+* Update `OD_HTML_Tag_Processor::next_tag()` to allow `$query` arg and prepare to skip visiting tag closers by default. ([1872](https://github.com/WordPress/performance/pull/1872))
+* Expose the logging functions to client-side extensions and automatically account for the value of `isDebug`. ([1895](https://github.com/WordPress/performance/pull/1895))
+
 = 1.0.0-beta1 =
 
 **Enhancements**

plugins/image-prioritizer/load.php

@@ -6,7 +6,7 @@
  * Requires at least: 6.6
  * Requires PHP: 7.2
  * Requires Plugins: optimization-detective
- * Version: 1.0.0-beta1
+ * Version: 1.0.0-beta2
  * Author: WordPress Performance Team
  * Author URI: https://make.wordpress.org/performance/
  * License: GPLv2 or later
@@ -72,7 +72,7 @@ static function ( string $global_var_name, string $version, Closure $load ): voi
 	}
 )(
 	'image_prioritizer_pending_plugin',
-	'1.0.0-beta1',
+	'1.0.0-beta2',
 	static function ( string $version ): void {
 		if ( defined( 'IMAGE_PRIORITIZER_VERSION' ) ) {
 			return;

plugins/image-prioritizer/readme.txt

@@ -2,7 +2,7 @@
 
 Contributors: wordpressdotorg
 Tested up to: 6.7
-Stable tag:   1.0.0-beta1
+Stable tag:   1.0.0-beta2
 License:      GPLv2 or later
 License URI:  https://www.gnu.org/licenses/gpl-2.0.html
 Tags:         performance, optimization, image, lcp, lazy-load
@@ -72,6 +72,18 @@ The [plugin source code](https://github.com/WordPress/performance/tree/trunk/plu
 
 == Changelog ==
 
+= 1.0.0-beta2 =
+
+**Enhancements**
+
+* Update `OD_HTML_Tag_Processor::next_tag()` to allow `$query` arg and prepare to skip visiting tag closers by default. ([1872](https://github.com/WordPress/performance/pull/1872))
+* Expose the logging functions to client-side extensions and automatically account for the value of `isDebug`. ([1895](https://github.com/WordPress/performance/pull/1895))
+
+**Bug Fixes**
+
+* Fix URL encoding in Link HTTP response header. ([1907](https://github.com/WordPress/performance/pull/1907))
+* Fix unpredictable LCP element being identified in a URL Metric Group. ([1903](https://github.com/WordPress/performance/pull/1903))
+
 = 1.0.0-beta1 =
 
 **Enhancements**

plugins/optimization-detective/class-od-html-tag-processor.php

@@ -239,7 +239,7 @@ final class OD_HTML_Tag_Processor extends WP_HTML_Tag_Processor {
 	 *
 	 * @inheritDoc
 	 * @since 0.4.0
-	 * @since n.e.x.t Passing a $query is now allowed. In the 1.0.0 release, this will default to skipping tag closers.
+	 * @since 1.0.0 Passing a $query is now allowed. TODO: In the final non-beta 1.0.0 release, also note that this will default to skipping tag closers.
 	 *
 	 * @param array{tag_name?: string|null, match_offset?: int|null, class_name?: string|null, tag_closers?: string|null}|null $query Query.
 	 * @return bool Whether a tag was matched.

plugins/optimization-detective/class-od-link-collection.php

@@ -323,7 +323,7 @@ function ( $image_candidate ) {
 	/**
 	 * Encodes a URL for serving in an HTTP response header.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @param string $url URL to percent encode.
 	 * @return string Percent-encoded URL.

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

@@ -3,7 +3,7 @@
  * Optimization Detective: OD_Template_Optimization_Context class
  *
  * @package optimization-detective
- * @since n.e.x.t
+ * @since 1.0.0
  */
 
 // @codeCoverageIgnoreStart
@@ -15,7 +15,7 @@
 /**
  * Context for optimizing a template.
  *
- * @since n.e.x.t
+ * @since 1.0.0
  *
  * @property-read OD_URL_Metric_Group_Collection $url_metric_group_collection URL Metric group collection.
  * @property-read positive-int|null              $url_metrics_id              ID for the od_url_metrics post which provided the URL Metrics in the collection.
@@ -28,7 +28,7 @@ final class OD_Template_Optimization_Context {
 	/**
 	 * URL Metric group collection.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 * @var OD_URL_Metric_Group_Collection
 	 */
 	private $url_metric_group_collection;
@@ -38,39 +38,39 @@ final class OD_Template_Optimization_Context {
 	 *
 	 * May be null if no post has been created yet.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 * @var positive-int|null
 	 */
 	private $url_metrics_id;
 
 	/**
 	 * Normalized query vars.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 * @var array<string, mixed>
 	 */
 	private $normalized_query_vars;
 
 	/**
 	 * Slug for the od_url_metrics post.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 * @var non-empty-string
 	 */
 	private $url_metrics_slug;
 
 	/**
 	 * Link collection.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 * @var OD_Link_Collection
 	 */
 	private $link_collection;
 
 	/**
 	 * Constructor.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 * @access private
 	 *
 	 * @param OD_URL_Metric_Group_Collection $url_metric_group_collection URL Metric group collection.
@@ -90,7 +90,7 @@ public function __construct( OD_URL_Metric_Group_Collection $url_metric_group_co
 	/**
 	 * Gets a property.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @param string $name Property name.
 	 * @return mixed Property value.

plugins/optimization-detective/deprecated.php

@@ -4,7 +4,7 @@
  *
  * @package optimization-detective
  *
- * @since n.e.x.t
+ * @since 1.0.0
  */
 
 // @codeCoverageIgnoreStart

plugins/optimization-detective/detection.php

@@ -161,7 +161,7 @@ static function ( OD_URL_Metric_Group $group ): array {
 /**
  * Registers the REST API endpoint for storing URL Metrics.
  *
- * @since n.e.x.t
+ * @since 1.0.0
  * @access private
  */
 function od_register_rest_url_metric_store_endpoint(): void {
@@ -180,7 +180,7 @@ function od_register_rest_url_metric_store_endpoint(): void {
  * This is intended to flush any page cache for the URL after the new URL Metric was submitted so that the optimizations
  * which depend on that URL Metric can start to take effect.
  *
- * @since n.e.x.t
+ * @since 1.0.0
  *
  * @param positive-int $cache_purge_post_id Cache purge post ID.
  */

plugins/optimization-detective/docs/hooks.md

@@ -105,6 +105,52 @@ Refer to [Image Prioritizer](https://github.com/WordPress/performance/tree/trunk
 [Embed Optimizer](https://github.com/WordPress/performance/tree/trunk/plugins/embed-optimizer) for additional
 examples of how tag visitors are used.
 
+### Action: `od_start_template_optimization` (argument: `OD_Template_Optimization_Context`)
+
+Fires before Optimization Detective starts iterating over the document in the output buffer.
+
+This is before any of the registered tag visitors have been invoked.
+
+It is important to note that this action fires _after_ the entire template has been rendered into the output buffer. In
+other words, it will fire after the `wp_footer` action.
+
+This action runs before any of the registered tag visitors have been invoked in the current response. It is useful for
+an extension to gather the required information from the currently-stored URL Metrics for tag visitors to later leverage.
+See [example](https://github.com/WordPress/performance/pull/1921) from the Image Prioritizer plugin where it can be used
+to determine what the common external LCP background-image is for each viewport group up front so that this doesn't have
+to be computed when a tag visitor is invoked.
+
+This action can be used if a site wants to prevent storing a response in the page cache until it has collected URL Metrics
+from both mobile and desktop:
+
+```php
+add_action(
+	'od_start_template_optimization',
+	static function ( OD_Template_Optimization_Context $context ) {
+		if ( 
+			$context->url_metric_group_collection->get_first_group()->count() === 0
+			||
+			$context->url_metric_group_collection->get_last_group()->count() === 0
+		 ) {
+			header( 'Cache-Control: private' );
+		}
+	}
+);
+```
+
+This could just as well be done at `od_finish_template_optimization` since the headers are not sent until after that
+action completes and the output buffer is returned.
+
+### Action: `od_finish_template_optimization` (argument: `OD_Template_Optimization_Context`)
+
+Fires after Optimization Detective has finished iterating over the document in the output buffer.
+
+This is after all the registered tag visitors have been invoked.
+
+This action runs after all the tags in a document have been visited and so no additional tag visitor will be invoked.
+This action has limited usefulness at the moment, but see [#1931](https://github.com/WordPress/performance/issues/1931)
+for possibilities for what it could be used for in the future.
+
 ### Action: `od_url_metric_stored` (argument: `OD_URL_Metric_Store_Request_Context`)
 
 Fires whenever a URL Metric was successfully stored.

plugins/optimization-detective/optimization.php

@@ -286,9 +286,11 @@ function od_optimize_template_output_buffer( string $buffer ): string {
 	);
 
 	/**
-	 * Fires before Optimization Detective starts optimizing the template.
+	 * Fires before Optimization Detective starts iterating over the document in the output buffer.
 	 *
-	 * @since n.e.x.t
+	 * This is before any of the registered tag visitors have been invoked.
+	 *
+	 * @since 1.0.0
 	 *
 	 * @param OD_Template_Optimization_Context $template_optimization_context Template optimization context.
 	 */
@@ -355,9 +357,11 @@ function od_optimize_template_output_buffer( string $buffer ): string {
 	}
 
 	/**
-	 * Fires after Optimization Detective finishes optimizing the template.
+	 * Fires after Optimization Detective has finished iterating over the document in the output buffer.
+	 *
+	 * This is after all the registered tag visitors have been invoked.
 	 *
-	 * @since n.e.x.t
+	 * @since 1.0.0
 	 *
 	 * @param OD_Template_Optimization_Context $template_optimization_context Template optimization context.
 	 */

plugins/optimization-detective/readme.txt

@@ -2,7 +2,7 @@
 
 Contributors: wordpressdotorg
 Tested up to: 6.7
-Stable tag:   1.0.0-beta2
+Stable tag:   1.0.0-beta3
 License:      GPLv2 or later
 License URI:  https://www.gnu.org/licenses/gpl-2.0.html
 Tags:         performance, optimization, rum
@@ -13,11 +13,11 @@ Provides a framework for leveraging real user metrics to detect optimizations fo
 
 This plugin captures real user metrics about what elements are displayed on the page across a variety of device form factors (e.g. desktop, tablet, and phone) in order to apply loading optimizations which are not possible with WordPress’s current server-side heuristics.
 
-This plugin is a dependency which does not provide end-user functionality on its own. For that, please install the dependent plugin [Image Prioritizer](https://wordpress.org/plugins/image-prioritizer/) or [Embed Optimizer](https://wordpress.org/plugins/embed-optimizer/) (among [others](https://github.com/WordPress/performance/labels/%5BPlugin%5D%20Optimization%20Detective) to come from the WordPress Core Performance team). There are currently **no settings** and no user interface for this plugin since it is designed to work without any configuration.
+This plugin is a framework dependency which does not provide optimization functionality on its own. For that, please install the [Image Prioritizer](https://wordpress.org/plugins/image-prioritizer/) and [Embed Optimizer](https://wordpress.org/plugins/embed-optimizer/) dependent plugins (among [others](https://github.com/WordPress/performance/labels/%5BPlugin%5D%20Optimization%20Detective) to come from the WordPress Core Performance team). There are currently **no settings** and no user interface for this plugin since it is designed to work without any configuration.
 
-Your site must have the **REST API accessible** to frontend visitors since this is how metrics are collected about how a page should be optimized.
+Your site must currently have the **REST API accessible** to unauthenticated frontend visitors since this is how real user metrics are collected about pages on your site; nevertheless, [exploration](https://github.com/WordPress/performance/issues/1311) is underway for providing alternative mechanisms for collecting the metrics. Also, please note that no metrics are currently collected from Safari since it does not yet support the [Largest Contentful Paint](https://developer.mozilla.org/en-US/docs/Web/API/LargestContentfulPaint) metric, but support for this [Core Web Vitals](https://web.dev/explore/learn-core-web-vitals) metric is coming this year [via Interop 2025](https://webkit.org/blog/16458/announcing-interop-2025/#core-web-vitals).
 
-Please refer to the [full plugin documentation](https://github.com/WordPress/performance/blob/trunk/plugins/optimization-detective/docs/README.md) for a [technical introduction](https://github.com/WordPress/performance/blob/trunk/plugins/optimization-detective/docs/introduction.md), [filter/action hooks](https://github.com/WordPress/performance/blob/trunk/plugins/optimization-detective/docs/hooks.md), and [extensions](https://github.com/WordPress/performance/blob/trunk/plugins/optimization-detective/docs/extensions.md) that show use cases and examples.
+Please refer to the [full plugin documentation](https://github.com/WordPress/performance/blob/trunk/plugins/optimization-detective/docs/README.md) for a [technical introduction](https://github.com/WordPress/performance/blob/trunk/plugins/optimization-detective/docs/introduction.md), [filter/action hooks](https://github.com/WordPress/performance/blob/trunk/plugins/optimization-detective/docs/hooks.md), and [extensions](https://github.com/WordPress/performance/blob/trunk/plugins/optimization-detective/docs/extensions.md) that show use cases and examples. You can also watch the talk from WordCamp Asia 2025: [Boosting Performance with Optimization Detective](https://weston.ruter.net/2025/02/21/boosting-performance-with-optimization-detective/).
 
 == Installation ==
 
@@ -55,6 +55,23 @@ The [plugin source code](https://github.com/WordPress/performance/tree/trunk/plu
 
 == Changelog ==
 
+= 1.0.0-beta3 =
+
+**Enhancements**
+
+* Fire actions before and after Optimization Detective processes a document. ([1919](https://github.com/WordPress/performance/pull/1919))
+* Update `OD_HTML_Tag_Processor::next_tag()` to allow `$query` arg and prepare to skip visiting tag closers by default. ([1872](https://github.com/WordPress/performance/pull/1872))
+* Expose the logging functions to client-side extensions and automatically account for the value of `isDebug`. ([1895](https://github.com/WordPress/performance/pull/1895))
+* Update URL Metric storage REST API endpoint to return status code `423 Locked` instead of `403 Forbidden`. ([1863](https://github.com/WordPress/performance/pull/1863))
+* De-duplicate logic between REST API and URL Metrics post type. ([1867](https://github.com/WordPress/performance/pull/1867))
+
+**Bug Fixes**
+
+* Fix URL encoding in Link HTTP response header. ([1907](https://github.com/WordPress/performance/pull/1907))
+* Fix triggering post update actions after storing a URL Metric and refactor REST API endpoint logic into class. ([1865](https://github.com/WordPress/performance/pull/1865))
+* Fix unpredictable LCP element being identified in a URL Metric Group. ([1903](https://github.com/WordPress/performance/pull/1903))
+* Handle missing Web Crypto API in non-HTTPS contexts when generating the already-submitted `sessionStorage` key. ([1911](https://github.com/WordPress/performance/pull/1911))
+
 = 1.0.0-beta2 =
 
 **Enhancements**