optimization-detective / class-od-element.php

class-od-element.php in Optimization Detective trunk, at class-od-element.php

238 lines 5.1 KB

Raw Download Zip

1	<?php
2	/**
3	* Optimization Detective: OD_Element class
4	*
5	* @package optimization-detective
6	* @since 0.7.0
7	*/
8
9	declare( strict_types = 1 );
10
11	// @codeCoverageIgnoreStart
12	if ( ! defined( 'ABSPATH' ) ) {
13	exit; // Exit if accessed directly.
14	}
15	// @codeCoverageIgnoreEnd
16
17	/**
18	* Data for a single element in a URL Metric.
19	*
20	* @phpstan-import-type ElementData from OD_URL_Metric
21	* @phpstan-import-type DOMRect from OD_URL_Metric
22	* @implements ArrayAccess<key-of<ElementData>, ElementData[key-of<ElementData>]>
23	* @todo The above implements tag should account for additional undefined keys which can be supplied by extending the element schema. May depend on <https://github.com/phpstan/phpstan/issues/8438>.
24	*
25	* @since 0.7.0
26	*/
27	class OD_Element implements ArrayAccess, JsonSerializable {
28
29	/**
30	* Data.
31	*
32	* @since 0.7.0
33	* @var ElementData
34	*/
35	protected array $data;
36
37	/**
38	* URL Metric that this element belongs to.
39	*
40	* @since 0.7.0
41	* @var OD_URL_Metric
42	*/
43	protected OD_URL_Metric $url_metric;
44
45	/**
46	* Constructor.
47	*
48	* @since 0.7.0
49	*
50	* @phpstan-param ElementData $data
51	*
52	* @param array<string, mixed> $data Element data.
53	* @param OD_URL_Metric $url_metric URL Metric.
54	*/
55	public function __construct( array $data, OD_URL_Metric $url_metric ) {
56	$this->data = $data;
57
58	$this->url_metric = $url_metric;
59	}
60
61	/**
62	* Gets the URL Metric that this element belongs to.
63	*
64	* @since 0.7.0
65	*
66	* @return OD_URL_Metric URL Metric.
67	*/
68	public function get_url_metric(): OD_URL_Metric {
69	return $this->url_metric;
70	}
71
72	/**
73	* Gets the group that this element's URL Metric is a part of (which may not be any).
74	*
75	* @since 0.7.0
76	*
77	* @return OD_URL_Metric_Group\|null Group.
78	*/
79	public function get_url_metric_group(): ?OD_URL_Metric_Group {
80	return $this->url_metric->get_group();
81	}
82
83	/**
84	* Gets property value for an arbitrary key.
85	*
86	* This is particularly useful in conjunction with the `od_url_metric_schema_element_item_additional_properties` filter.
87	*
88	* @since 0.7.0
89	*
90	* @param string $key Property.
91	* @return mixed\|null The property value, or null if not set.
92	*/
93	public function get( string $key ) {
94	return $this->data[ $key ] ?? null;
95	}
96
97	/**
98	* Determines whether element was detected as LCP.
99	*
100	* @since 0.7.0
101	*
102	* @return bool Whether LCP.
103	*/
104	public function is_lcp(): bool {
105	return $this->data['isLCP'];
106	}
107
108	/**
109	* Determines whether element was detected as an LCP candidate.
110	*
111	* @since 0.7.0
112	*
113	* @return bool Whether LCP candidate.
114	*/
115	public function is_lcp_candidate(): bool {
116	return $this->data['isLCPCandidate'];
117	}
118
119	/**
120	* Gets XPath for element.
121	*
122	* @since 0.7.0
123	*
124	* @return non-empty-string XPath.
125	*/
126	public function get_xpath(): string {
127	return $this->data['xpath'];
128	}
129
130	/**
131	* Gets intersectionRatio for element.
132	*
133	* @since 0.7.0
134	*
135	* @return float Intersection ratio.
136	*/
137	public function get_intersection_ratio(): float {
138	return $this->data['intersectionRatio'];
139	}
140
141	/**
142	* Gets intersectionRect for element.
143	*
144	* @since 0.7.0
145	*
146	* @phpstan-return DOMRect
147	*
148	* @return array Intersection rect.
149	*/
150	public function get_intersection_rect(): array {
151	return $this->data['intersectionRect'];
152	}
153
154	/**
155	* Gets boundingClientRect for element.
156	*
157	* @since 0.7.0
158	*
159	* @phpstan-return DOMRect
160	*
161	* @return array Bounding client rect.
162	*/
163	public function get_bounding_client_rect(): array {
164	return $this->data['boundingClientRect'];
165	}
166
167	/**
168	* Checks whether an offset exists.
169	*
170	* @since 0.7.0
171	*
172	* @param mixed $offset Key.
173	* @return bool Whether the offset exists.
174	*/
175	public function offsetExists( $offset ): bool {
176	return isset( $this->data[ $offset ] );
177	}
178
179	/**
180	* Retrieves an offset.
181	*
182	* @since 0.7.0
183	*
184	* @template T of key-of<ElementData>
185	* @phpstan-param T $offset
186	* @phpstan-return ElementData[T]\|null
187	* @todo This should account for additional undefined keys which can be supplied by extending the element schema. May depend on <https://github.com/phpstan/phpstan/issues/8438>.
188	*
189	* @param mixed $offset Key.
190	* @return mixed May return any value from ElementData including possible extensions.
191	*/
192	#[ReturnTypeWillChange]
193	public function offsetGet( $offset ) {
194	return $this->data[ $offset ] ?? null;
195	}
196
197	/**
198	* Sets an offset.
199	*
200	* This is disallowed. Attempting to set a property will throw an error.
201	*
202	* @since 0.7.0
203	*
204	* @param mixed $offset Key.
205	* @param mixed $value Value.
206	*
207	* @throws Exception When attempting to set a property.
208	*/
209	public function offsetSet( $offset, $value ): void {
210	throw new Exception( 'Element data may not be set.' );
211	}
212
213	/**
214	* Offset to unset.
215	*
216	* This is disallowed. Attempting to unset a property will throw an error.
217	*
218	* @since 0.7.0
219	*
220	* @param mixed $offset Offset.
221	*
222	* @throws Exception When attempting to unset a property.
223	*/
224	public function offsetUnset( $offset ): void {
225	throw new Exception( 'Element data may not be unset.' );
226	}
227
228	/**
229	* Specifies data which should be serialized to JSON.
230	*
231	* @since 0.7.0
232	* @return ElementData Exports to be serialized by json_encode().
233	*/
234	public function jsonSerialize(): array {
235	return $this->data;
236	}
237	}
238