Merge branch 'trunk' into update/od-initialization-timing

Author: westonruter

plugins/image-prioritizer/helper.php

@@ -292,13 +292,21 @@ static function ( $host ) {
  *
  * @return WP_REST_Response|WP_HTTP_Response|WP_Error|mixed Result to send to the client.
  * @noinspection PhpDocMissingThrowsInspection
+ * @noinspection PhpDeprecationInspection
  */
 function image_prioritizer_filter_rest_request_before_callbacks( $response, array $handler, WP_REST_Request $request ) {
+	unset( $handler ); // Unused.
+
+	// Check for class existence and use constant or class method calls accordingly.
+	$route_endpoint = class_exists( 'OD_REST_URL_Metrics_Store_Endpoint' )
+						? OD_REST_URL_Metrics_Store_Endpoint::ROUTE_NAMESPACE . OD_REST_URL_Metrics_Store_Endpoint::ROUTE_BASE
+						: OD_REST_API_NAMESPACE . OD_URL_METRICS_ROUTE; // @phpstan-ignore constant.deprecated, constant.deprecated (To be replaced with class method calls in subsequent release.)
+
 	if (
 		$request->get_method() !== 'POST'
 		||
 		// The strtolower() and outer trim are due to \WP_REST_Server::match_request_to_handler() using case-insensitive pattern match and using '$' instead of '\z'.
-		OD_REST_API_NAMESPACE . OD_URL_METRICS_ROUTE !== rtrim( strtolower( ltrim( $request->get_route(), '/' ) ) )
+		( rtrim( strtolower( ltrim( $request->get_route(), '/' ) ) ) !== $route_endpoint )
 	) {
 		return $response;
 	}

plugins/image-prioritizer/tests/test-helper.php

@@ -727,7 +727,7 @@ public function data_provider_to_test_image_prioritizer_filter_rest_request_befo
 		};
 
 		$create_request = static function ( array $url_metric_data ): WP_REST_Request {
-			$request = new WP_REST_Request( 'POST', '/' . OD_REST_API_NAMESPACE . OD_URL_METRICS_ROUTE );
+			$request = new WP_REST_Request( 'POST', '/' . OD_REST_URL_Metrics_Store_Endpoint::ROUTE_NAMESPACE . OD_REST_URL_Metrics_Store_Endpoint::ROUTE_BASE );
 			$request->set_header( 'content-type', 'application/json' );
 			$request->set_body( wp_json_encode( $url_metric_data ) );
 			return $request;

plugins/optimization-detective/deprecated.php

@@ -0,0 +1,39 @@
+<?php
+/**
+ * Deprecated functions and constants.
+ *
+ * @package optimization-detective
+ *
+ * @since n.e.x.t
+ */
+
+// @codeCoverageIgnoreStart
+if ( ! defined( 'ABSPATH' ) ) {
+	exit; // Exit if accessed directly.
+}
+
+/**
+ * Namespace for optimization-detective.
+ *
+ * @since 0.1.0
+ * @access private
+ * @deprecated n.e.x.t This constant should not be used, instead use OD_REST_URL_Metrics_Store_Endpoint::ROUTE_NAMESPACE method.
+ * @var string
+ */
+const OD_REST_API_NAMESPACE = 'optimization-detective/v1';
+
+/**
+ * Route for storing a URL Metric.
+ *
+ * Note the `:store` art of the endpoint follows Google's guidance in AIP-136 for the use of the POST method in a way
+ * that does not strictly follow the standard usage. Namely, submitting a POST request to this endpoint will either
+ * create a new `od_url_metrics` post, or it will update an existing post if one already exists for the provided slug.
+ *
+ * @since 0.1.0
+ * @access private
+ * @link https://google.aip.dev/136
+ * @deprecated n.e.x.t This constant should not be used, instead use OD_REST_URL_Metrics_Store_Endpoint::ROUTE_BASE method.
+ * @var string
+ */
+const OD_URL_METRICS_ROUTE = '/url-metrics:store';
+// @codeCoverageIgnoreEnd

plugins/optimization-detective/detection.php

@@ -121,7 +121,7 @@ function od_get_detection_script( string $slug, OD_URL_Metric_Group_Collection $
 		'maxViewportAspectRatio' => od_get_maximum_viewport_aspect_ratio(),
 		'isDebug'                => WP_DEBUG,
 		'extensionModuleUrls'    => $extension_module_urls,
-		'restApiEndpoint'        => rest_url( OD_REST_API_NAMESPACE . OD_URL_METRICS_ROUTE ),
+		'restApiEndpoint'        => rest_url( OD_REST_URL_Metrics_Store_Endpoint::ROUTE_NAMESPACE . OD_REST_URL_Metrics_Store_Endpoint::ROUTE_BASE ),
 		'currentETag'            => $current_etag,
 		'currentUrl'             => $current_url,
 		'urlMetricSlug'          => $slug,
@@ -159,3 +159,67 @@ static function ( OD_URL_Metric_Group $group ): array {
 		array( 'type' => 'module' )
 	);
 }
+
+/**
+ * Registers the REST API endpoint for storing URL Metrics.
+ *
+ * @since n.e.x.t
+ * @access private
+ */
+function od_register_rest_url_metric_store_endpoint(): void {
+	$endpoint_controller = new OD_REST_URL_Metrics_Store_Endpoint();
+
+	register_rest_route(
+		$endpoint_controller::ROUTE_NAMESPACE,
+		$endpoint_controller::ROUTE_BASE,
+		$endpoint_controller->get_registration_args()
+	);
+
+	add_filter( 'rest_pre_dispatch', array( $endpoint_controller, 'decompress_rest_request_body' ), 10, 3 );
+}
+
+/**
+ * Triggers post update actions for page caches to invalidate their caches related to the supplied cache purge post ID.
+ *
+ * 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
+ *
+ * @param positive-int $cache_purge_post_id Cache purge post ID.
+ */
+function od_trigger_post_update_actions( int $cache_purge_post_id ): void {
+
+	$post = get_post( $cache_purge_post_id );
+	if ( ! ( $post instanceof WP_Post ) ) {
+		return;
+	}
+
+	// Fire actions that page caching plugins listen to flush caches.
+
+	/*
+	* The clean_post_cache action is used to flush page caches by:
+	* - Pantheon Advanced Cache <https://github.com/pantheon-systems/pantheon-advanced-page-cache/blob/e3b5552b0cb9268d9b696cb200af56cc044920d9/pantheon-advanced-page-cache.php#L185>
+	* - WP Super Cache <https://github.com/Automattic/wp-super-cache/blob/73b428d2fce397fd874b3056ad3120c343bc1a0c/wp-cache-phase2.php#L1615>
+	* - Batcache <https://github.com/Automattic/batcache/blob/ed0e6b2d9bcbab3924c49a6c3247646fb87a0957/batcache.php#L18>
+	*/
+	/** This action is documented in wp-includes/post.php. */
+	do_action( 'clean_post_cache', $post->ID, $post );
+
+	/*
+	* The transition_post_status action is used to flush page caches by:
+	* - Jetpack Boost <https://github.com/Automattic/jetpack-boost-production/blob/4090a3f9414c2171cd52d8a397f00b0d1151475f/app/modules/optimizations/page-cache/pre-wordpress/Boost_Cache.php#L76>
+	* - WP Super Cache <https://github.com/Automattic/wp-super-cache/blob/73b428d2fce397fd874b3056ad3120c343bc1a0c/wp-cache-phase2.php#L1616>
+	* - LightSpeed Cache <https://github.com/litespeedtech/lscache_wp/blob/7c707469b3c88b4f45d9955593b92f9aeaed54c3/src/purge.cls.php#L68>
+	*/
+	/** This action is documented in wp-includes/post.php. */
+	do_action( 'transition_post_status', $post->post_status, $post->post_status, $post );
+
+	/*
+	* The clean_post_cache action is used to flush page caches by:
+	* - W3 Total Cache <https://github.com/BoldGrid/w3-total-cache/blob/ab08f104294c6a8dcb00f1c66aaacd0615c42850/Util_AttachToActions.php#L32>
+	* - WP Rocket <https://github.com/wp-media/wp-rocket/blob/e5bca6673a3669827f3998edebc0c785210fe561/inc/common/purge.php#L283>
+	*/
+	/** This action is documented in wp-includes/post.php. */
+	do_action( 'save_post', $post->ID, $post, /* $update */ true );
+}

plugins/optimization-detective/hooks.php

@@ -24,5 +24,6 @@
 add_filter( 'site_status_tests', 'od_add_rest_api_availability_test' );
 add_action( 'admin_init', 'od_maybe_run_rest_api_health_check' );
 add_action( 'after_plugin_row_meta', 'od_render_rest_api_health_check_admin_notice_in_plugin_row', 30 );
-add_filter( 'rest_pre_dispatch', 'od_decompress_rest_request_body', 10, 3 );
+add_action( 'rest_api_init', 'od_register_rest_url_metric_store_endpoint' );
+add_action( 'od_trigger_page_cache_invalidation', 'od_trigger_post_update_actions' );
 // @codeCoverageIgnoreEnd

plugins/optimization-detective/load.php

@@ -99,6 +99,9 @@ static function ( string $version ): void {
 
 		require_once __DIR__ . '/helper.php';
 
+		// Deprecations.
+		require_once __DIR__ . '/deprecated.php';
+
 		// Core infrastructure classes.
 		require_once __DIR__ . '/class-od-data-validation-exception.php';
 		require_once __DIR__ . '/class-od-html-tag-processor.php';
@@ -114,7 +117,7 @@ class_alias( OD_URL_Metric_Group_Collection::class, 'OD_URL_Metrics_Group_Collec
 		require_once __DIR__ . '/storage/class-od-url-metrics-post-type.php';
 		require_once __DIR__ . '/storage/class-od-storage-lock.php';
 		require_once __DIR__ . '/storage/data.php';
-		require_once __DIR__ . '/storage/rest-api.php';
+		require_once __DIR__ . '/storage/class-od-rest-url-metrics-store-endpoint.php';
 		require_once __DIR__ . '/storage/class-od-url-metric-store-request-context.php';
 
 		// Detection logic.

plugins/optimization-detective/site-health.php

@@ -91,7 +91,7 @@ function od_compose_site_health_result( $response ): array {
 		sprintf(
 			/* translators: %s is the REST API endpoint */
 			__( 'To collect URL Metrics from visitors the REST API must be available to unauthenticated users. Specifically, visitors must be able to perform a <code>POST</code> request to the <code>%s</code> endpoint.', 'optimization-detective' ),
-			'/' . OD_REST_API_NAMESPACE . OD_URL_METRICS_ROUTE
+			'/' . OD_REST_URL_Metrics_Store_Endpoint::ROUTE_NAMESPACE . OD_REST_URL_Metrics_Store_Endpoint::ROUTE_BASE
 		),
 		array( 'code' => array() )
 	) . '</p>';
@@ -192,7 +192,7 @@ function od_get_rest_api_health_check_response( bool $use_cached ) {
 	if ( false !== $response ) {
 		return $response;
 	}
-	$rest_url = get_rest_url( null, OD_REST_API_NAMESPACE . OD_URL_METRICS_ROUTE );
+	$rest_url = get_rest_url( null, OD_REST_URL_Metrics_Store_Endpoint::ROUTE_NAMESPACE . OD_REST_URL_Metrics_Store_Endpoint::ROUTE_BASE );
 	$response = wp_remote_post(
 		$rest_url,
 		array(