Improve docs and tidiness

Author: westonruter

plugins/image-prioritizer/hooks.php

@@ -13,4 +13,4 @@
 add_action( 'od_init', 'image_prioritizer_init' );
 add_filter( 'od_extension_module_urls', 'image_prioritizer_filter_extension_module_urls' );
 add_filter( 'od_url_metric_schema_root_additional_properties', 'image_prioritizer_add_element_item_schema_properties' );
-add_filter( 'od_store_url_metric_validity', 'image_prioritizer_filter_store_url_metric_validity', 10, 2 );
+add_filter( 'od_url_metric_storage_validity', 'image_prioritizer_filter_store_url_metric_validity', 10, 2 );

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

@@ -14,6 +14,6 @@ public function test_hooks_added(): void {
 		$this->assertEquals( 10, has_action( 'od_init', 'image_prioritizer_init' ) );
 		$this->assertEquals( 10, has_filter( 'od_extension_module_urls', 'image_prioritizer_filter_extension_module_urls' ) );
 		$this->assertEquals( 10, has_filter( 'od_url_metric_schema_root_additional_properties', 'image_prioritizer_add_element_item_schema_properties' ) );
-		$this->assertEquals( 10, has_filter( 'od_store_url_metric_validity', 'image_prioritizer_filter_store_url_metric_validity' ) );
+		$this->assertEquals( 10, has_filter( 'od_url_metric_storage_validity', 'image_prioritizer_filter_store_url_metric_validity' ) );
 	}
 }

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

@@ -225,7 +225,7 @@ public function get_last_group(): OD_URL_Metric_Group {
 	}
 
 	/**
-	 * Clear result cache.
+	 * Clears result cache.
 	 *
 	 * @since 0.3.0
 	 */
@@ -234,7 +234,7 @@ public function clear_cache(): void {
 	}
 
 	/**
-	 * Create groups.
+	 * Creates groups.
 	 *
 	 * @since 0.1.0
 	 *

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

@@ -471,7 +471,7 @@ public function count(): int {
 	}
 
 	/**
-	 * Clear result cache.
+	 * Clears result cache.
 	 *
 	 * @since n.e.x.t
 	 */

plugins/optimization-detective/readme.txt

@@ -246,6 +246,20 @@ The ETag is a unique identifier that changes whenever the underlying data used t
 
 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.
 
+**Filter:** `od_url_metric_storage_validity` (default args: true)
+
+Filters whether a URL Metric is valid for storage.
+
+Three paramters are passed to this filter:
+
+1. `$validity` (`bool|WP_Error`): Validity. Invalid if false or a WP_Error with errors.
+2. `$url_metric` (`OD_Strict_URL_Metric`): URL Metric, already validated against the JSON Schema.
+3. `$url_metric_data` (`array<string, mixed>`): Original URL Metric data before any mutations.
+
+This allows for custom validation constraints to be applied beyond what can be expressed in JSON Schema. This filter only applies when storing a URL Metric via the REST API. It does not run when a stored URL Metric is loaded from the `od_url_metrics` post type. This means that validation logic enforced via this filter can be more expensive, such as doing filesystem checks or HTTP requests.
+
+In addition to having the filter return `false` or a non-empty `WP_Error` to block storing the URL Metric, a plugin may also mutate the `OD_URL_Metric` instance passed by reference to the filter callback. This is useful for plugins in particular to unset extended properties which couldn't be validated using JSON Schema alone.
+
 **Action:** `od_url_metric_stored` (argument: `OD_URL_Metric_Store_Request_Context`)
 
 Fires whenever a URL Metric was successfully stored.

plugins/optimization-detective/storage/rest-api.php

@@ -210,31 +210,31 @@ function od_handle_rest_request( WP_REST_Request $request ) {
 		);
 	}
 
-	/**
-	 * Filters whether a URL Metric is valid for storage.
-	 *
-	 * This allows for custom validation constraints to be applied beyond what can be expressed in JSON Schema. This is
-	 * also necessary because the 'validate_callback' key in a JSON Schema is not respected when gathering the REST API
-	 * endpoint args via the {@see rest_get_endpoint_args_for_schema()} function. Besides this, the REST API doesn't
-	 * support 'validate_callback' for any nested arguments in any case, meaning that custom constraints would be able
-	 * to be applied to multidimensional objects, such as the items inside 'elements'.
-	 *
-	 * This filter only applies when storing a URL Metric via the REST API. It does not run when a stored URL Metric
-	 * loaded from the od_url_metric post type. This means that validation logic enforced via this filter can be more
-	 * expensive, such as doing filesystem checks or HTTP requests.
-	 *
-	 * In addition to having the filter return `false` or a non-empty `WP_Error` to block storing the URL Metric, a
-	 * plugin may also mutate the OD_URL_Metric instance passed by reference to the filter callback. This is useful
-	 * for plugins in particular to unset extended properties which couldn't be validated using JSON Schema alone.
-	 *
-	 * @since n.e.x.t
-	 *
-	 * @param bool|WP_Error        $validity        Validity. Valid if true or a WP_Error without any errors, or invalid otherwise.
-	 * @param OD_Strict_URL_Metric $url_metric      URL Metric, already validated against the JSON Schema.
-	 * @param array<string, mixed> $url_metric_data Original URL Metric data before any mutations.
-	 */
 	try {
-		$validity = apply_filters( 'od_store_url_metric_validity', true, $url_metric, $url_metric->jsonSerialize() ); // TODO: A better name might be `od_url_metric_storage_validity`.
+		/**
+		 * Filters whether a URL Metric is valid for storage.
+		 *
+		 * This allows for custom validation constraints to be applied beyond what can be expressed in JSON Schema. This is
+		 * also necessary because the 'validate_callback' key in a JSON Schema is not respected when gathering the REST API
+		 * endpoint args via the {@see rest_get_endpoint_args_for_schema()} function. Besides this, the REST API doesn't
+		 * support 'validate_callback' for any nested arguments in any case, meaning that custom constraints would be able
+		 * to be applied to multidimensional objects, such as the items inside 'elements'.
+		 *
+		 * This filter only applies when storing a URL Metric via the REST API. It does not run when a stored URL Metric is
+		 * loaded from the od_url_metrics post type. This means that validation logic enforced via this filter can be more
+		 * expensive, such as doing filesystem checks or HTTP requests.
+		 *
+		 * In addition to having the filter return `false` or a non-empty `WP_Error` to block storing the URL Metric, a
+		 * plugin may also mutate the OD_URL_Metric instance passed by reference to the filter callback. This is useful
+		 * for plugins in particular to unset extended properties which couldn't be validated using JSON Schema alone.
+		 *
+		 * @since n.e.x.t
+		 *
+		 * @param bool|WP_Error        $validity        Validity. Invalid if false or a WP_Error with errors.
+		 * @param OD_Strict_URL_Metric $url_metric      URL Metric, already validated against the JSON Schema.
+		 * @param array<string, mixed> $url_metric_data Original URL Metric data before any mutations.
+		 */
+		$validity = apply_filters( 'od_url_metric_storage_validity', true, $url_metric, $url_metric->jsonSerialize() );
 	} catch ( Exception $e ) {
 		$error_data = null;
 		if ( WP_DEBUG ) {
@@ -247,9 +247,9 @@ function od_handle_rest_request( WP_REST_Request $request ) {
 		$validity = new WP_Error(
 			'exception',
 			sprintf(
-				/* translators: %s is the filter name 'od_store_url_metric_validity' */
+				/* translators: %s is the filter name 'od_url_metric_storage_validity' */
 				__( 'An %s filter callback threw an exception.', 'optimization-detective' ),
-				'od_store_url_metric_validity'
+				'od_url_metric_storage_validity'
 			),
 			$error_data
 		);

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

@@ -226,9 +226,6 @@ public function test_clear_cache(): void {
 		$this->assertSame( array(), $collection_result_cache_reflection_property->getValue( $collection ) );
 
 		// Test that adding a URL metric to a collection clears the caches.
-		$collection_result_cache_reflection_property->setValue( $collection, $populated_value );
-		$group_result_cache_reflection_property->setValue( $group, $populated_value );
-
 		add_filter(
 			'od_url_metric_schema_root_additional_properties',
 			static function ( $schema ) {
@@ -247,7 +244,8 @@ static function ( $schema ) {
 				return $schema;
 			}
 		);
-
+		$collection_result_cache_reflection_property->setValue( $collection, $populated_value );
+		$group_result_cache_reflection_property->setValue( $group, $populated_value );
 		$collection->add_url_metric(
 			$this->get_sample_url_metric(
 				array(