Allow URL metric schema to be extended

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

@@ -0,0 +1,63 @@
+<?php
+/**
+ * Optimization Detective: OD_Strict_URL_Metric class
+ *
+ * @package optimization-detective
+ * @since n.e.x.t
+ */
+
+// Exit if accessed directly.
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Representation of the measurements taken from a single client's visit to a specific URL without additionalProperties allowed.
+ *
+ * This is used exclusively in the REST API endpoint for capturing new URL metrics to prevent invalid additional data from being
+ * submitted in the request. For URL metrics which have been stored the looser OD_URL_Metric class is used instead.
+ *
+ * @since n.e.x.t
+ * @access private
+ */
+final class OD_Strict_URL_Metric extends OD_URL_Metric {
+
+	/**
+	 * Gets JSON schema for URL Metric without additionalProperties.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return array<string, mixed> Schema.
+	 */
+	public static function get_json_schema(): array {
+		return self::falsify_additional_properties( parent::get_json_schema() );
+	}
+
+	/**
+	 * Recursively processes the schema to ensure that all objects have additionalProperties set to false.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param mixed $schema Schema.
+	 * @return mixed Processed schema.
+	 */
+	private static function falsify_additional_properties( $schema ) {
+		if ( ! isset( $schema['type'] ) ) {
+			return $schema;
+		}
+		if ( 'object' === $schema['type'] ) {
+			$schema['additionalProperties'] = false;
+			if ( isset( $schema['properties'] ) && is_array( $schema['properties'] ) ) {
+				$schema['properties'] = array_map(
+					static function ( $property_schema ) {
+						return self::falsify_additional_properties( $property_schema );
+					},
+					$schema['properties']
+				);
+			}
+		} elseif ( 'array' === $schema['type'] && isset( $schema['items'] ) && is_array( $schema['items'] ) ) {
+			$schema['items'] = self::falsify_additional_properties( $schema['items'] );
+		}
+		return $schema;
+	}
+}

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

@@ -44,45 +44,51 @@
  *                                elements: ElementData[]
  *                            }
  *
+ * @property-read string        $uuid
+ * @property-read string        $url
+ * @property-read float         $timestamp
+ * @property-read ViewportRect  $viewport
+ * @property-read ElementData[] $elements
+ *
  * @since 0.1.0
  * @access private
  */
-final class OD_URL_Metric implements JsonSerializable {
+class OD_URL_Metric implements JsonSerializable {
 
 	/**
 	 * Data.
 	 *
 	 * @var Data
 	 */
-	private $data;
+	protected $data;
 
 	/**
 	 * Constructor.
 	 *
 	 * @phpstan-param Data|array<string, mixed> $data Valid data or invalid data (in which case an exception is thrown).
 	 *
-	 * @param array<string, mixed> $data URL metric data.
-	 *
 	 * @throws OD_Data_Validation_Exception When the input is invalid.
+	 *
+	 * @param array<string, mixed> $data URL metric data.
 	 */
 	public function __construct( array $data ) {
 		if ( ! isset( $data['uuid'] ) ) {
 			$data['uuid'] = wp_generate_uuid4();
 		}
-		$this->validate_data( $data );
-		$this->data = $data;
+		$this->data = $this->prepare_data( $data );
 	}
 
 	/**
-	 * Validate data.
+	 * Prepares data with validation and sanitization.
 	 *
-	 * @phpstan-assert Data $data
+	 * @throws OD_Data_Validation_Exception When the input is invalid.
 	 *
 	 * @param array<string, mixed> $data Data to validate.
-	 * @throws OD_Data_Validation_Exception When the input is invalid.
+	 * @return Data Validated and sanitized data.
 	 */
-	private function validate_data( array $data ): void {
-		$valid = rest_validate_object_value_from_schema( $data, self::get_json_schema(), self::class );
+	private function prepare_data( array $data ): array {
+		$schema = static::get_json_schema();
+		$valid  = rest_validate_object_value_from_schema( $data, $schema, self::class );
 		if ( is_wp_error( $valid ) ) {
 			throw new OD_Data_Validation_Exception( esc_html( $valid->get_error_message() ) );
 		}
@@ -105,6 +111,7 @@ private function validate_data( array $data ): void {
 				)
 			);
 		}
+		return rest_sanitize_value_from_schema( $data, $schema, self::class );
 	}
 
 	/**
@@ -116,12 +123,12 @@ private function validate_data( array $data ): void {
 	 */
 	public static function get_json_schema(): array {
 		/*
-		 * The intersectionRect and clientBoundingRect are both instances of the DOMRectReadOnly, which
+		 * The intersectionRect and boundingClientRect are both instances of the DOMRectReadOnly, which
 		 * the following schema describes. See <https://developer.mozilla.org/en-US/docs/Web/API/DOMRectReadOnly>.
 		 * Note that 'number' is used specifically instead of 'integer' because the values are all specified as
 		 * floats/doubles.
 		 */
-		$properties = array_fill_keys(
+		$dom_rect_properties = array_fill_keys(
 			array(
 				'width',
 				'height',
@@ -139,17 +146,17 @@ public static function get_json_schema(): array {
 		);
 
 		// The spec allows these to be negative but this doesn't make sense in the context of intersectionRect and boundingClientRect.
-		$properties['width']['minimum']  = 0.0;
-		$properties['height']['minimum'] = 0.0;
+		$dom_rect_properties['width']['minimum']  = 0.0;
+		$dom_rect_properties['height']['minimum'] = 0.0;
 
 		$dom_rect_schema = array(
 			'type'                 => 'object',
 			'required'             => true,
-			'properties'           => $properties,
+			'properties'           => $dom_rect_properties,
 			'additionalProperties' => false,
 		);
 
-		return array(
+		$schema = array(
 			'$schema'              => 'http://json-schema.org/draft-04/schema#',
 			'title'                => 'od-url-metric',
 			'type'                 => 'object',
@@ -225,12 +232,141 @@ public static function get_json_schema(): array {
 							'intersectionRect'   => $dom_rect_schema,
 							'boundingClientRect' => $dom_rect_schema,
 						),
-						'additionalProperties' => false,
+
+						// Additional properties may be added to the schema for items of elements via the od_url_metric_schema_element_item_additional_properties filter.
+						// See further explanation below.
+						'additionalProperties' => true,
 					),
 				),
 			),
-			'additionalProperties' => false,
+			// Additional root properties may be added to the schema via the od_url_metric_schema_root_additional_properties filter.
+			// Therefore, additionalProperties is set to true so that additional properties defined in the extended schema may persist
+			// in a stored URL Metric even when the extension is deactivated. For REST API requests, the OD_Strict_URL_Metric
+			// which sets this to false so that newly-submitted URL Metrics only ever include the known properties.
+			'additionalProperties' => true,
 		);
+
+		/**
+		 * Filters additional schema properties which should be allowed at the root of a URL metric.
+		 *
+		 * @since n.e.x.t
+		 *
+		 * @param array<string, array{type: string}> $additional_properties Additional properties.
+		 */
+		$additional_properties = (array) apply_filters( 'od_url_metric_schema_root_additional_properties', array() );
+		if ( count( $additional_properties ) > 0 ) {
+			$schema['properties'] = self::extend_schema_with_optional_properties( $schema['properties'], $additional_properties, 'od_url_metric_schema_root_additional_properties' );
+		}
+
+		/**
+		 * Filters additional schema properties which should be allowed for an elements item in a URL metric.
+		 *
+		 * @since n.e.x.t
+		 *
+		 * @param array<string, array{type: string}> $additional_properties Additional properties.
+		 */
+		$additional_properties = (array) apply_filters( 'od_url_metric_schema_element_item_additional_properties', array() );
+		if ( count( $additional_properties ) > 0 ) {
+			$schema['properties']['elements']['items']['properties'] = self::extend_schema_with_optional_properties(
+				$schema['properties']['elements']['items']['properties'],
+				$additional_properties,
+				'od_url_metric_schema_root_additional_properties'
+			);
+		}
+
+		return $schema;
+	}
+
+	/**
+	 * Extends a schema with additional optional properties.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param array<string, mixed> $properties_schema     Properties schema to extend.
+	 * @param array<string, mixed> $additional_properties Additional properties.
+	 * @param string               $filter_name           Filter name used to extend.
+	 *
+	 * @return array<string, mixed> Extended schema.
+	 */
+	protected static function extend_schema_with_optional_properties( array $properties_schema, array $additional_properties, string $filter_name ): array {
+		$doing_it_wrong = static function ( string $message ) use ( $filter_name ): void {
+			_doing_it_wrong(
+				esc_html( "Filter: '{$filter_name}'" ),
+				esc_html( $message ),
+				'Optimization Detective n.e.x.t'
+			);
+		};
+		foreach ( $additional_properties as $property_key => $property_schema ) {
+			if ( ! is_array( $property_schema ) ) {
+				continue;
+			}
+			if ( isset( $properties_schema[ $property_key ] ) ) {
+				$doing_it_wrong(
+					sprintf(
+						/* translators: property name */
+						__( 'Disallowed override of existing schema property "%s".', 'optimization-detective' ),
+						$property_key
+					)
+				);
+				continue;
+			}
+			if ( ! isset( $property_schema['type'] ) || ! ( is_string( $property_schema['type'] ) || is_array( $property_schema['type'] ) ) ) {
+				$doing_it_wrong(
+					sprintf(
+						/* translators: 1: property name, 2: 'type' */
+						__( 'Supplied schema property "%1$s" with missing "%2$s" key.', 'optimization-detective' ),
+						'type',
+						$property_key
+					)
+				);
+				continue;
+			}
+			// TODO: Should 'default' be required?
+			if ( isset( $property_schema['required'] ) && false !== $property_schema['required'] ) {
+				$doing_it_wrong(
+					sprintf(
+						/* translators: 1: property name, 2: 'required' */
+						__( 'Supplied schema property "%1$s" has a truthy value for "%2$s". All extended properties must be optional so that URL Metrics are not all immediately invalidated once an extension is deactivated..', 'optimization-detective' ),
+						$property_key,
+						'required'
+					)
+				);
+			}
+			$property_schema['required'] = false;
+
+			$properties_schema[ $property_key ] = $property_schema;
+		}
+		return $properties_schema;
+	}
+
+	/**
+	 * Gets property value for an arbitrary key.
+	 *
+	 * This is particularly useful in conjunction with the `od_url_metric_schema_root_additional_properties` filter.
+	 *
+	 * @since n.e.x.t
+	 * @todo Instead of returning null when the key doesn't exist, should the `default` value be returned as defined in the schema?
+	 *
+	 * @param string $key Property.
+	 * @return mixed|null
+	 */
+	public function get( string $key ) {
+		return $this->data[ $key ] ?? null;
+	}
+
+	/**
+	 * Gets property value for an arbitrary key.
+	 *
+	 * This is useful with the `@property-read` annotations for the class. For accessing other data,
+	 * it's likely the `get()` method will be more useful for static analysis reasons.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param string $key Property.
+	 * @return mixed|null
+	 */
+	public function __get( string $key ) {
+		return $this->get( $key );
 	}
 
 	/**

plugins/optimization-detective/load.php

@@ -99,6 +99,7 @@ static function ( string $version ): void {
 		require_once __DIR__ . '/class-od-data-validation-exception.php';
 		require_once __DIR__ . '/class-od-html-tag-processor.php';
 		require_once __DIR__ . '/class-od-url-metric.php';
+		require_once __DIR__ . '/class-od-strict-url-metric.php';
 		require_once __DIR__ . '/class-od-url-metrics-group.php';
 		require_once __DIR__ . '/class-od-url-metrics-group-collection.php';
 

plugins/optimization-detective/storage/class-od-url-metrics-post-type.php

@@ -188,6 +188,7 @@ static function ( $url_metric_data ) use ( $trigger_error ) {
 	 * Stores URL metric by merging it with the other URL metrics which share the same normalized query vars.
 	 *
 	 * @since 0.1.0
+	 * @todo There is duplicate logic here with od_handle_rest_request().
 	 *
 	 * @param string        $slug           Slug (hash of normalized query vars).
 	 * @param OD_URL_Metric $new_url_metric New URL metric.