Merge pull request #1979 from ShyamGadde/update/od-meta-generator-tag

Enhance Optimization Detective meta generator tag with all disabled reasons

Author: westonruter

plugins/optimization-detective/docs/hooks.md

@@ -9,7 +9,7 @@
 Fires when the Optimization Detective is initializing.
 
 This action is useful for loading extension code that depends on Optimization Detective to be running. The version
-of the plugin is passed as the sole argument so that if the required version is not present, the callback can short circuit.
+of the plugin is passed as the sole argument so that if the required version is not present, the callback can short-circuit.
 
 Example:
 
@@ -115,7 +115,7 @@ It is important to note that this action fires _after_ the entire template has b
 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.
+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.
@@ -187,32 +187,46 @@ The additional attribution data is made available to client-side extension scrip
 Filters the breakpoint max widths to group URL Metrics for various viewports. 
 
 Each number represents the maximum width (inclusive) for a given breakpoint. So if there is one number, 480, then this means there will be two viewport groupings, one for 0\<=480, and another \>480. If instead there are the two breakpoints defined, 480 and 782, then this means there will be three viewport groups of URL Metrics, one for 0\<=480 (i.e. mobile), another 481\<=782 (i.e. phablet/tablet), and another \>782 (i.e. desktop).
-This array may be empty in which case there are no responsive breakpoints and all URL Metrics are collected in a single group.
+This array may be empty, in which case there are no responsive breakpoints, and all URL Metrics are collected in a single group.
 A breakpoint must be greater than zero or else a usage warning will occur.
 
-These default breakpoints are reused from Gutenberg which appear to be used the most in media queries that affect frontend styles.
+These default breakpoints are reused from Gutenberg, which appear to be used the most in media queries that affect frontend styles.
 
 ### Filter: `od_can_optimize_response` (default: boolean condition, see below)
 
 Filters whether the current response can be optimized. By default, detection and optimization are only performed when:
 
 1. It’s not a search template (`is_search()`).
 2. It’s not a post embed template (`is_embed()`).
-3. It’s not the Customizer preview (`is_customize_preview()`)
-4. It’s not the response to a `POST` request.
-5. There is at least one queried post on the page. This is used to facilitate the purging of page caches after a new URL Metric is stored.
+3. It’s not a preview (`is_preview()`).
+4. It’s not the Customizer preview (`is_customize_preview()`).
+5. It’s not the response to a `POST` request.
+6. There is at least one queried post on the page. This is used to facilitate the purging of page caches after a new URL Metric is stored.
 
-To force every response to be optimized regardless of the conditions above, you can do:
+The filter now receives an additional `$disabled_flags` parameter that contains information about which specific conditions are preventing optimization. This allows for more granular control.
+
+For example, to enable optimization specifically for search pages:
 
 ```php
-add_filter( 'od_can_optimize_response', '__return_true' );
+add_filter( 'od_can_optimize_response', function( $can_optimize, array $disabled_flags ): bool {
+    if ( ! $can_optimize && $disabled_flags['is_search'] ) {
+        unset( $disabled_flags['is_search'] );
+        $can_optimize = count( array_filter( $disabled_flags ) ) === 0;
+    }
+    return $can_optimize;
+}, 10, 2 );
 ```
 
+Note that this filter cannot override some conditions. Even if the filter returns `true`, optimization will still be disabled when:
+
+1. The REST API for storing URL Metrics is not available.
+2. The URL has the `optimization_detective_disabled` query parameter.
+
 ### Filter: `od_url_metrics_breakpoint_sample_size` (default: 3)
 
 Filters the sample size for a breakpoint's URL Metrics on a given URL. 
 
-The filtered value must be greater than zero; otherwise it will be ignored and a usage warning will result.
+The filtered value must be greater than zero; otherwise it will be ignored, and a usage warning will result.
 
 You can increase the sample size if you want better guarantees that the applied optimizations will be accurate. During development, it may be helpful to reduce the sample size to 1 (along with setting the `od_url_metric_storage_lock_ttl` and `od_url_metric_freshness_ttl` filters below) so that you don't have to keep reloading the page to collect new URL Metrics to flush out stale ones during active development:
 
@@ -226,7 +240,7 @@ add_filter( 'od_url_metrics_breakpoint_sample_size', function (): int {
 
 Filters how long the current IP is locked from submitting another URL metric storage REST API request.
 
-Filtering the TTL to zero will disable any URL Metric storage locking. This is useful, for example, to disable locking when a user is logged-in with code like the following:
+Filtering the TTL to zero will disable any URL Metric storage locking. This is useful, for example, to disable locking when a user is logged in with code like the following:
 
 ```php
 add_filter( 'od_metrics_storage_lock_ttl', function ( int $ttl ): int {
@@ -236,7 +250,7 @@ add_filter( 'od_metrics_storage_lock_ttl', function ( int $ttl ): int {
 
 By default, the TTL is zero (0) for authorized users and sixty (60) for everyone else. Whether the current user is authorized is determined by whether the user has the `od_store_url_metric_now` capability. This custom capability by default maps to the `manage_options` primitive capability via the `user_has_cap` filter.
 
-During development this is useful to set to zero so you can quickly collect new URL Metrics by reloading the page without having to wait for the storage lock to release:
+During development this is useful to set to zero, so you can quickly collect new URL Metrics by reloading the page without having to wait for the storage lock to release:
 
 ```php
 add_filter( 'od_metrics_storage_lock_ttl', function ( int $ttl ): int {
@@ -274,7 +288,7 @@ add_filter( 'od_url_metric_freshness_ttl', '__return_zero' );
 
 Filters the minimum allowed viewport aspect ratio for URL Metrics.
 
-The 0.4 value is intended to accommodate the phone with the greatest known aspect ratio at 21:9 when rotated 90 degrees to 9:21 (0.429). During development when you have the DevTools console open on the right, the viewport aspect ratio will be smaller than normal. In this case, you may want to set this to 0:
+The 0.4 value is intended to accommodate the phone with the greatest known aspect ratio at 21:9 when rotated 90 degrees to 9:21 (0.429). During development, when you have the DevTools console open on the right, the viewport aspect ratio will be smaller than normal. In this case, you may want to set this to 0:
 
 ```php
 add_filter( 'od_minimum_viewport_aspect_ratio', static function (): int {
@@ -298,13 +312,15 @@ add_filter( 'od_maximum_viewport_aspect_ratio', static function (): int {
 
 ### Filter: `od_template_output_buffer` (default: the HTML response)
 
-Filters the template output buffer prior to sending to the client. This filter is added to implement [\#43258](https://core.trac.wordpress.org/ticket/43258) in WordPress core.
+Filters the template output buffer before sending it to the client. 
+
+This filter is added to implement [\#43258](https://core.trac.wordpress.org/ticket/43258) in WordPress core.
 
 ### Filter: `od_url_metric_schema_element_item_additional_properties` (default: empty array)
 
 Filters additional schema properties which should be allowed for an element's item in a URL Metric.
 
-For example to add a `resizedBoundingClientRect` property:
+For example, to add a `resizedBoundingClientRect` property:
 
 ```php
 <?php
@@ -396,7 +412,7 @@ add_filter( 'od_url_metric_garbage_collection_ttl', '__return_zero' );
 
 Filters the maximum allowed size in bytes for a URL Metric serialized to JSON.
 
-The filtered value must be greater than zero; otherwise it will be ignored and a usage warning will result.
+The filtered value must be greater than zero; otherwise it will be ignored, and a usage warning will result.
 
 ### Filter: `od_gzip_url_metric_store_request_payloads` (default: `true` if the `gzdecode()` function exists)
 

plugins/optimization-detective/helper.php

@@ -61,7 +61,122 @@ function od_generate_media_query( ?int $minimum_viewport_width, ?int $maximum_vi
 }
 
 /**
- * Displays the HTML generator meta tag for the Optimization Detective plugin.
+ * Gets the reasons why Optimization Detective is disabled for the current response.
+ *
+ * @since n.e.x.t
+ * @access private
+ *
+ * @return array{
+ *     is_search?: string,
+ *     is_embed?: string,
+ *     is_preview?: string,
+ *     is_customize_preview?: string,
+ *     non_get_request?: string,
+ *     no_cache_purge_post_id?: string,
+ *     filter_disabled?: string,
+ *     rest_api_unavailable?: string,
+ *     query_param_disabled?: string
+ * } Array of disabled reason codes and their messages.
+ */
+function od_get_disabled_reasons(): array {
+	$disabled_flags = array(
+		'is_search'              => false,
+		'is_embed'               => false,
+		'is_preview'             => false,
+		'is_customize_preview'   => false,
+		'non_get_request'        => false,
+		'no_cache_purge_post_id' => false,
+	);
+
+	// Disable the search template since there is no predictability in whether posts in the loop will have featured images assigned or not. If a
+	// theme template for search results doesn't even show featured images, then this wouldn't be an issue.
+	if ( is_search() ) {
+		$disabled_flags['is_search'] = true;
+	}
+
+	// Avoid optimizing embed responses because the Post Embed iframes include a sandbox attribute with the value of
+	// "allow-scripts" but without "allow-same-origin". This can result in an error in the console:
+	// > Access to script at '.../detect.js?ver=0.4.1' from origin 'null' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
+	// So it's better to just avoid attempting to optimize Post Embed responses (which don't need optimization anyway).
+	if ( is_embed() ) {
+		$disabled_flags['is_embed'] = true;
+	}
+
+	// Skip posts that aren't published yet.
+	if ( is_preview() ) {
+		$disabled_flags['is_preview'] = true;
+	}
+
+	// Disable in Customizer preview since injection of inline-editing controls can interfere with XPath. Optimization is also not necessary in this context.
+	if ( is_customize_preview() ) {
+		$disabled_flags['is_customize_preview'] = true;
+	}
+
+	// Disable for POST responses since they cannot, by definition, be cached.
+	if ( isset( $_SERVER['REQUEST_METHOD'] ) && 'GET' !== $_SERVER['REQUEST_METHOD'] ) {
+		$disabled_flags['non_get_request'] = true;
+	}
+
+	// Disable when there is no post ID available for cache purging. Page caching plugins can only reliably be told to invalidate a cached page when a post is available to trigger
+	// the relevant actions on.
+	if ( null === od_get_cache_purge_post_id() ) {
+		$disabled_flags['no_cache_purge_post_id'] = true;
+	}
+
+	// Check if any flags are set to true.
+	$has_disabled_flags = count( array_filter( $disabled_flags ) ) > 0;
+
+	/**
+	 * Filters whether the current response can be optimized.
+	 *
+	 * @since 0.1.0
+	 * @since n.e.x.t Added $disabled_flags parameter
+	 * @link https://github.com/WordPress/performance/blob/trunk/plugins/optimization-detective/docs/hooks.md#:~:text=Filter%3A%20od_can_optimize_response
+	 *
+	 * @param bool $can_optimize Whether response can be optimized.
+	 * @param array{
+	 *     is_search: bool,
+	 *     is_embed: bool,
+	 *     is_preview: bool,
+	 *     is_customize_preview: bool,
+	 *     non_get_request: bool,
+	 *     no_cache_purge_post_id: bool
+	 * } $disabled_flags Flags indicating which conditions are disabling optimization.
+	 */
+	$can_optimize = (bool) apply_filters( 'od_can_optimize_response', ! $has_disabled_flags, $disabled_flags );
+
+	$reasons = array();
+	if ( ! $can_optimize ) {
+		$reason_messages = array(
+			'is_search'              => __( 'Page is not optimized because it is a search results page.', 'optimization-detective' ),
+			'is_embed'               => __( 'Page is not optimized because it is an embed.', 'optimization-detective' ),
+			'is_preview'             => __( 'Page is not optimized because it is a preview.', 'optimization-detective' ),
+			'is_customize_preview'   => __( 'Page is not optimized because it is a customize preview.', 'optimization-detective' ),
+			'non_get_request'        => __( 'Page is not optimized because it is not a GET request.', 'optimization-detective' ),
+			'no_cache_purge_post_id' => __( 'Page is not optimized because there is no post ID available for cache purging.', 'optimization-detective' ),
+		);
+
+		$reasons = wp_array_slice_assoc( $reason_messages, array_keys( array_filter( $disabled_flags ) ) );
+
+		// If no technical reasons but optimization still disabled, it's because of the filter.
+		if ( 0 === count( $reasons ) ) {
+			$reasons['filter_disabled'] = __( 'Page is not optimized because the od_can_optimize_response filter returned false.', 'optimization-detective' );
+		}
+	}
+
+	if ( od_is_rest_api_unavailable() && ! ( wp_get_environment_type() === 'local' && ! function_exists( 'tests_add_filter' ) ) ) {
+		$reasons['rest_api_unavailable'] = __( 'Page is not optimized because the REST API for storing URL Metrics is not available.', 'optimization-detective' );
+	}
+
+	if ( isset( $_GET['optimization_detective_disabled'] ) ) { // phpcs:ignore WordPress.Security.NonceVerification.Recommended
+		$reasons['query_param_disabled'] = __( 'Page is not optimized because the URL has the optimization_detective_disabled query parameter.', 'optimization-detective' );
+	}
+
+	return $reasons;
+}
+
+/**
+ * Displays the HTML generator META tag for the Optimization Detective plugin.
  *
  * See {@see 'wp_head'}.
  *
@@ -72,9 +187,11 @@ function od_render_generator_meta_tag(): void {
 	// Use the plugin slug as it is immutable.
 	$content = 'optimization-detective ' . OPTIMIZATION_DETECTIVE_VERSION;
 
-	// Indicate that the plugin will not be doing anything because the REST API is unavailable.
-	if ( od_is_rest_api_unavailable() ) {
-		$content .= '; rest_api_unavailable';
+	// Add any reasons why Optimization Detective is disabled.
+	$disabled_reasons = od_get_disabled_reasons();
+	if ( count( $disabled_reasons ) > 0 ) {
+		$flags    = array_keys( $disabled_reasons );
+		$content .= '; ' . implode( '; ', $flags );
 	}
 
 	echo '<meta name="generator" content="' . esc_attr( $content ) . '">' . "\n";
@@ -86,7 +203,7 @@ function od_render_generator_meta_tag(): void {
  * @since 0.9.0
  * @access private
  *
- * @param string      $src_path Source path, relative to plugin root.
+ * @param string      $src_path Source path, relative to the plugin root.
  * @param string|null $min_path Minified path. If not supplied, then '.min' is injected before the file extension in the source path.
  * @return string URL to script or stylesheet.
  *