plugin-check / includes / Checker / Default_Check_Collection.php

Default_Check_Collection.php in Plugin Check (PCP) 1.5.0, at includes/Checker/Default_Check_Collection.php

263 lines 6.6 KB

Raw Download Zip

1	<?php
2	/**
3	* Class WordPress\Plugin_Check\Checker\Default_Check_Collection
4	*
5	* @package plugin-check
6	*/
7
8	namespace WordPress\Plugin_Check\Checker;
9
10	use ArrayIterator;
11	use Traversable;
12	use WordPress\Plugin_Check\Checker\Exception\Invalid_Check_Slug_Exception;
13
14	/**
15	* Default Check Collection class.
16	*
17	* @since 1.0.0
18	*/
19	class Default_Check_Collection implements Check_Collection {
20
21	/**
22	* Map of `$check_slug => $check_obj` pairs.
23	*
24	* @since 1.0.0
25	* @var array
26	*/
27	private $checks;
28
29	/**
30	* List of check slugs, in the same order as `$checks` - effectively the keys of that array.
31	*
32	* @since 1.0.0
33	* @var array
34	*/
35	private $slugs;
36
37	/**
38	* Constructor.
39	*
40	* @since 1.0.0
41	*
42	* @param array $checks Map of `$check_slug => $check_obj` pairs for the collection.
43	*/
44	public function __construct( array $checks ) {
45	$this->checks = $checks;
46	$this->slugs = array_keys( $this->checks );
47	}
48
49	/**
50	* Returns the raw indexed array representation of this collection.
51	*
52	* @since 1.0.0
53	*
54	* @return array The indexed array of check objects.
55	*/
56	public function to_array(): array {
57	return array_values( $this->checks );
58	}
59
60	/**
61	* Returns the raw map of check slugs and their check objects as a representation of this collection.
62	*
63	* @since 1.0.0
64	*
65	* @return array Map of `$check_slug => $check_obj` pairs.
66	*/
67	public function to_map(): array {
68	return $this->checks;
69	}
70
71	/**
72	* Returns a new check collection containing the subset of checks based on the given check filter function.
73	*
74	* @since 1.0.0
75	*
76	* @phpstan-param callable(Check,string): bool $filter_fn
77	*
78	* @param callable $filter_fn Filter function that accepts a Check object and a Check slug and
79	* should return a boolean for whether to include the check in the new collection.
80	* @return Check_Collection New check collection, effectively a subset of this one.
81	*/
82	public function filter( callable $filter_fn ): Check_Collection {
83	return new self(
84	array_filter(
85	$this->checks,
86	$filter_fn,
87	ARRAY_FILTER_USE_BOTH
88	)
89	);
90	}
91
92	/**
93	* Returns a new check collection containing the subset of checks based on the given check slugs.
94	*
95	* If the given list is empty, the same collection will be returned without any change.
96	*
97	* @since 1.0.0
98	*
99	* @param array $check_slugs List of slugs to limit to only those. If empty, the same collection is returned.
100	* @return Check_Collection New check collection, effectively a subset of this one.
101	*/
102	public function include( array $check_slugs ): Check_Collection {
103	// Return unmodified collection if no check slugs to limit to are given.
104	if ( ! $check_slugs ) {
105	return $this;
106	}
107
108	$check_slugs = array_flip( $check_slugs );
109
110	$checks = array();
111	foreach ( $this->checks as $slug => $check ) {
112	if ( ! isset( $check_slugs[ $slug ] ) ) {
113	continue;
114	}
115
116	$checks[ $slug ] = $check;
117	}
118
119	return new self( $checks );
120	}
121
122	/**
123	* Returns a new check collection excluding the provided checks.
124	*
125	* If the given list is empty, the same collection will be returned without any change.
126	*
127	* @since 1.0.0
128	*
129	* @param array $check_slugs List of slugs to exclude. If empty, the same collection is returned.
130	* @return Check_Collection New check collection, effectively a subset of this one.
131	*/
132	public function exclude( array $check_slugs ): Check_Collection {
133	// Return unmodified collection if no check slugs to exclude are given.
134	if ( ! $check_slugs ) {
135	return $this;
136	}
137
138	return $this->filter(
139	static function ( Check $check, $slug ) use ( $check_slugs ) {
140	return ! in_array( $slug, $check_slugs, true );
141	}
142	);
143	}
144
145	/**
146	* Throws an exception if any of the given check slugs are not present, or returns the same collection otherwise.
147	*
148	* @since 1.0.0
149	*
150	* @param array $check_slugs List of slugs to limit to only those. If empty, the same collection is returned.
151	* @return Check_Collection The unchanged check collection.
152	*
153	* @throws Invalid_Check_Slug_Exception Thrown when any of the given check slugs is not present in the collection.
154	*/
155	public function require( array $check_slugs ): Check_Collection {
156	foreach ( $check_slugs as $slug ) {
157	if ( ! isset( $this->checks[ $slug ] ) ) {
158	throw new Invalid_Check_Slug_Exception(
159	sprintf(
160	/* translators: %s: The Check slug. */
161	__( 'Check with the slug "%s" does not exist.', 'plugin-check' ),
162	$slug
163	)
164	);
165	}
166	}
167
168	return $this;
169	}
170
171	/**
172	* Counts the checks in the collection.
173	*
174	* @since 1.0.0
175	*
176	* @return int Number of checks in the collection.
177	*/
178	public function count(): int {
179	return count( $this->checks );
180	}
181
182	/**
183	* Returns an iterator for the checks in the collection.
184	*
185	* @since 1.0.0
186	*
187	* @return Traversable Checks iterator.
188	*/
189	public function getIterator(): Traversable {
190	return new ArrayIterator( $this->checks );
191	}
192
193	/**
194	* Checks whether a check exists with the given slug or index.
195	*
196	* @since 1.0.0
197	*
198	* @param string\|int $offset Either a check slug (string) or index (integer).
199	* @return bool True if a check exists at the given slug or index, false otherwise.
200	*/
201	#[\ReturnTypeWillChange]
202	public function offsetExists( $offset ) {
203	if ( is_string( $offset ) ) {
204	return isset( $this->checks[ $offset ] );
205	}
206
207	return isset( $this->slugs[ $offset ] );
208	}
209
210	/**
211	* Retrieves the check with the given slug or index.
212	*
213	* @since 1.0.0
214	*
215	* @param string\|int $offset Either a check slug (string) or index (integer).
216	* @return Check\|null Check with the given slug or index, or null if it does not exist.
217	*/
218	#[\ReturnTypeWillChange]
219	public function offsetGet( $offset ) {
220	if ( is_string( $offset ) ) {
221	if ( isset( $this->checks[ $offset ] ) ) {
222	return $this->checks[ $offset ];
223	}
224	return null;
225	}
226
227	if ( isset( $this->slugs[ $offset ] ) ) {
228	return $this->checks[ $this->slugs[ $offset ] ];
229	}
230
231	return null;
232	}
233
234	/**
235	* Sets a check in the collection.
236	*
237	* This method does nothing as the collection is read-only.
238	*
239	* @since 1.0.0
240	*
241	* @param string\|int $offset Either a check slug (string) or index (integer).
242	* @param mixed $value Value to set.
243	*/
244	#[\ReturnTypeWillChange]
245	public function offsetSet( $offset, $value ) {
246	// Not implemented as this is a read-only collection.
247	}
248
249	/**
250	* Removes a check from the collection.
251	*
252	* This method does nothing as the collection is read-only.
253	*
254	* @since 1.0.0
255	*
256	* @param string\|int $offset Either a check slug (string) or index (integer).
257	*/
258	#[\ReturnTypeWillChange]
259	public function offsetUnset( $offset ) {
260	// Not implemented as this is a read-only collection.
261	}
262	}
263