Merge branch 'trunk' of https://github.com/WordPress/performance into update/od-docs

* 'trunk' of https://github.com/WordPress/performance:
  Bump yoast/phpunit-polyfills from 3.1.1 to 4.0.0
  Bump phpstan/php-8-stubs from 0.4.9 to 0.4.10
  Add ETag explainer to od_url_metric_freshness_ttl hook docs
  Fix format for multisite active plugins
  Include active plugins in URL Metric ETag data
  Add missing getters for OD_URL_Metric_Group_Collection props
  Increase default freshness TTL from 1 day to 1 week

Author: westonruter

composer.json

@@ -30,7 +30,7 @@
     "szepeviktor/phpstan-wordpress": "^1.3",
     "wp-coding-standards/wpcs": "^3.1",
     "wp-phpunit/wp-phpunit": "^6.5",
-    "yoast/phpunit-polyfills": "^3.1",
+    "yoast/phpunit-polyfills": "^4.0",
     "phpstan/php-8-stubs": "^0.4.0",
     "phpstan/phpstan-strict-rules": "^1.6"
   },

composer.lock

@@ -192,6 +192,39 @@ public function get_current_etag(): string {
 		return $this->current_etag;
 	}
 
+	/**
+	 * Gets the breakpoints in max widths.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return positive-int[] Breakpoints in max widths.
+	 */
+	public function get_breakpoints(): array {
+		return $this->breakpoints;
+	}
+
+	/**
+	 * Gets the sample size for URL Metrics for a given breakpoint.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return int<1, max> Sample size for URL Metrics for a given breakpoint.
+	 */
+	public function get_sample_size(): int {
+		return $this->sample_size;
+	}
+
+	/**
+	 * Gets the freshness age (TTL) for a given URL Metric..
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return int<0, max> Freshness age (TTL) for a given URL Metric.
+	 */
+	public function get_freshness_ttl(): int {
+		return $this->freshness_ttl;
+	}
+
 	/**
 	 * Gets the first URL Metric group.
 	 *

plugins/optimization-detective/class-od-url-metric-group-collection.php

@@ -124,16 +124,18 @@ add_filter( 'od_metrics_storage_lock_ttl', function ( int $ttl ): int {
 } );
 ```
 
-### Filter: `od_url_metric_freshness_ttl` (default: 1 day in seconds)
+### Filter: `od_url_metric_freshness_ttl` (default: 1 week in seconds)
 
-Filters the freshness age (TTL) for a given URL Metric. The freshness TTL must be at least zero, in which it considers URL Metrics to always be stale. In practice, the value should be at least an hour. If your site content does not change frequently, you may want to increase the TTL to a week:
+Filters the freshness age (TTL) for a given URL Metric. The freshness TTL must be at least zero, in which it considers URL Metrics to always be stale. In practice, the value should be at least an hour. If your site content does not change frequently, you may want to increase the TTL even longer, say to a month:
 
 ```php
 add_filter( 'od_url_metric_freshness_ttl', static function (): int {
-	return WEEK_IN_SECONDS;
+	return MONTH_IN_SECONDS;
 } );
 ```
 
+Note that even if you have large freshness TTL a URL Metric can still become stale sooner; if the page state changes then this results in a change to the ETag associated with a URL Metric. This will allow new URL Metrics to be collected before the freshness TTL has transpired. See the `od_current_url_metrics_etag_data` filter to customize the ETag data.
+
 During development, this can be useful to set to zero so that you don't have to wait for new URL Metrics to be requested when engineering a new optimization:
 
 ```php
@@ -233,10 +235,17 @@ add_filter(
 
 See also [example usage](https://github.com/WordPress/performance/blob/6bb8405c5c446e3b66c2bfa3ae03ba61b188bca2/plugins/embed-optimizer/hooks.php#L128-L144) in Embed Optimizer. Note in particular the structure of the plugin’s [detect.js](https://github.com/WordPress/performance/blob/trunk/plugins/embed-optimizer/detect.js) script module, how it exports `initialize` and `finalize` functions which Optimization Detective then calls when the page loads and when the page unloads, at which time the URL Metric is constructed and sent to the server for storage. Refer also to the [TypeScript type definitions](https://github.com/WordPress/performance/blob/trunk/plugins/optimization-detective/types.ts).
 
-### Filter: `od_current_url_metrics_etag_data` (default: array with `tag_visitors` key)
+### Filter: `od_current_url_metrics_etag_data` (default: `array<string, mixed>`)
 
 Filters the data that goes into computing the current ETag for URL Metrics.
 
-The ETag is a unique identifier that changes whenever the underlying data used to generate it changes. By default, the ETag calculation includes the names of registered tag visitors. This ensures that when a new Optimization Detective-dependent plugin is activated (like [Image Prioritizer](https://wordpress.org/plugins/image-prioritizer/) or [Embed Optimizer](https://wordpress.org/plugins/embed-optimizer/)), any existing URL Metrics are immediately considered stale. This happens because the newly registered tag visitors alter the ETag calculation, making it different from the stored ones.
+The ETag is a unique identifier that changes whenever the underlying data used to generate it changes. By default, the ETag calculation includes:
+
+1. The active theme and current version (for both parent and child themes).
+2. The queried object ID, post type, and modified date.
+3. The list of registered tag visitors.
+4. The IDs and modified times of posts in The Loop.
+5. The current theme template used to render the page.
+6. The list of active plugins.
 
-When the ETag for URL Metrics in a complete viewport group no longer matches the current environment's ETag, new URL Metrics will then begin to be collected until there are no more stored URL Metrics with the old ETag. These new URL Metrics will include data relevant to the newly activated plugins and their tag visitors.
+A change in ETag means that any previously-collected URL Metrics will be immediately considered stale. When the ETag for URL Metrics in a complete viewport group no longer matches the current environment's ETag, new URL Metrics will then begin to be collected until there are no more stored URL Metrics with the old ETag.

plugins/optimization-detective/docs/hooks.md

@@ -31,9 +31,9 @@ function od_get_url_metric_freshness_ttl(): int {
 	 *
 	 * @since 0.1.0
 	 *
-	 * @param int $ttl Expiration TTL in seconds. Defaults to 1 day.
+	 * @param int $ttl Expiration TTL in seconds. Defaults to 1 week.
 	 */
-	$freshness_ttl = (int) apply_filters( 'od_url_metric_freshness_ttl', DAY_IN_SECONDS );
+	$freshness_ttl = (int) apply_filters( 'od_url_metric_freshness_ttl', WEEK_IN_SECONDS );
 
 	if ( $freshness_ttl < 0 ) {
 		_doing_it_wrong(
@@ -201,6 +201,17 @@ function od_get_current_url_metrics_etag( OD_Tag_Visitor_Registry $tag_visitor_r
 		$queried_object_data['type'] = $queried_object->name;
 	}
 
+	$active_plugins = (array) get_option( 'active_plugins', array() );
+	if ( is_multisite() ) {
+		$active_plugins = array_unique(
+			array_merge(
+				$active_plugins,
+				array_keys( (array) get_site_option( 'active_sitewide_plugins', array() ) )
+			)
+		);
+	}
+	sort( $active_plugins );
+
 	$data = array(
 		'xpath_version'    => 2, // Bump whenever a major change to the XPath format occurs so that new URL Metrics are proactively gathered.
 		'tag_visitors'     => array_keys( iterator_to_array( $tag_visitor_registry ) ),
@@ -232,6 +243,7 @@ static function ( $post ): ?array {
 				'version' => wp_get_theme()->get( 'Version' ),
 			),
 		),
+		'active_plugins'   => $active_plugins,
 		'current_template' => $current_template instanceof WP_Block_Template ? get_object_vars( $current_template ) : $current_template,
 	);
 

plugins/optimization-detective/storage/data.php

@@ -33,7 +33,7 @@ public function tear_down(): void {
 	 * @covers ::od_get_url_metric_freshness_ttl
 	 */
 	public function test_od_get_url_metric_freshness_ttl(): void {
-		$this->assertSame( DAY_IN_SECONDS, od_get_url_metric_freshness_ttl() );
+		$this->assertSame( WEEK_IN_SECONDS, od_get_url_metric_freshness_ttl() );
 
 		add_filter(
 			'od_url_metric_freshness_ttl',
@@ -486,6 +486,27 @@ static function ( $link, $author_id ) {
 					};
 				},
 			),
+
+			'plugin_activated'            => array(
+				'set_up' => function (): Closure {
+					$this->go_to( '/' );
+
+					return function ( array $etag_data, Closure $get_etag ): void {
+						$etag = $get_etag();
+						update_option(
+							'active_plugins',
+							array_merge(
+								get_option( 'active_plugins' ),
+								array(
+									'image-prioritizer/load.php',
+								)
+							)
+						);
+						$etag_after = $get_etag();
+						$this->assertNotEquals( $etag, $etag_after );
+					};
+				},
+			),
 		);
 	}
 
@@ -498,6 +519,21 @@ static function ( $link, $author_id ) {
 	 * @covers ::od_get_current_theme_template
 	 */
 	public function test_od_get_current_url_metrics_etag( Closure $set_up ): void {
+		update_option(
+			'active_plugins',
+			array(
+				'optimization-detective/load.php',
+			)
+		);
+		if ( is_multisite() ) {
+			update_site_option(
+				'active_sitewide_plugins',
+				array(
+					'performance-lab/load.php' => time(),
+				)
+			);
+		}
+
 		$captured_etag_data = null;
 		add_filter(
 			'od_current_url_metrics_etag_data',
@@ -533,11 +569,17 @@ static function ( array $data ) use ( &$captured_etag_data ) {
 		$etag = $get_etag();
 		$this->assertMatchesRegularExpression( '/^[a-z0-9]{32}\z/', $etag );
 		$this->assertIsArray( $captured_etag_data );
-		$expected_keys = array( 'xpath_version', 'tag_visitors', 'queried_object', 'queried_posts', 'active_theme', 'current_template' );
+		$expected_keys = array( 'xpath_version', 'tag_visitors', 'queried_object', 'queried_posts', 'active_theme', 'current_template', 'active_plugins' );
 		foreach ( $expected_keys as $expected_key ) {
 			$this->assertArrayHasKey( $expected_key, $captured_etag_data );
 		}
 		$this->assertSame( $initial_active_theme, $captured_etag_data['active_theme'] );
+		$this->assertContains( 'optimization-detective/load.php', $captured_etag_data['active_plugins'] );
+		if ( is_multisite() ) {
+			$this->assertContains( 'performance-lab/load.php', $captured_etag_data['active_plugins'] );
+		} else {
+			$this->assertNotContains( 'performance-lab/load.php', $captured_etag_data['active_plugins'] );
+		}
 		$this->assertContains( 'foo', $captured_etag_data['tag_visitors'] );
 		$this->assertContains( 'bar', $captured_etag_data['tag_visitors'] );
 		$this->assertContains( 'baz', $captured_etag_data['tag_visitors'] );

plugins/optimization-detective/tests/storage/test-data.php

@@ -111,6 +111,9 @@ public function data_provider_test_construction(): array {
 	/**
 	 * @covers ::__construct
 	 * @covers ::get_current_etag
+	 * @covers ::get_breakpoints
+	 * @covers ::get_sample_size
+	 * @covers ::get_freshness_ttl
 	 * @covers ::create_groups
 	 * @covers ::count
 	 *
@@ -130,6 +133,9 @@ public function test_construction( array $url_metrics, string $current_etag, arr
 		$group_collection = new OD_URL_Metric_Group_Collection( $url_metrics, $current_etag, $breakpoints, $sample_size, $freshness_ttl );
 		$this->assertCount( count( $breakpoints ) + 1, $group_collection );
 		$this->assertSame( $current_etag, $group_collection->get_current_etag() );
+		$this->assertSame( $sample_size, $group_collection->get_sample_size() );
+		$this->assertSame( $breakpoints, $group_collection->get_breakpoints() );
+		$this->assertSame( $freshness_ttl, $group_collection->get_freshness_ttl() );
 	}
 
 	/**

plugins/optimization-detective/tests/test-class-od-url-metrics-group-collection.php

@@ -90,7 +90,7 @@ public function data_provider_od_get_detection_script(): array {
 					'storageLockTTL'      => MINUTE_IN_SECONDS,
 					'extensionModuleUrls' => array(),
 					'cachePurgePostId'    => null,
-					'freshnessTTL'        => DAY_IN_SECONDS,
+					'freshnessTTL'        => WEEK_IN_SECONDS,
 				),
 				'expected_standard_build' => true,
 			),