desktop-mode / includes / media-query.php

media-query.php in OpenStation: Desktop Windows, Dock & Virtual Desktops for WP Admin 0.9.0, at includes/media-query.php

230 lines 8.6 KB

Raw Download Zip

1	<?php
2	/**
3	* Desktop Mode — Media dimension filtering for REST.
4	*
5	* Adds two opt-in query parameters to `/wp/v2/media`:
6	*
7	* - `desktop_mode_min_width` — only return images at least this many pixels wide.
8	* - `desktop_mode_min_height` — only return images at least this many pixels tall.
9	*
10	* The OS Settings wallpaper picker uses these to keep a site with thousands
11	* of small product images from burying the handful of desktop-worthy HD
12	* shots under an infinite-scroll slog. The client still applies the same
13	* filter locally as a belt-and-suspenders safeguard — if the server-side
14	* filter ever ships mis-stamped meta, the UI still hides too-small images.
15	*
16	* Why not `meta_query` on `_wp_attachment_metadata` directly? That key is
17	* stored serialized, so SQL can't compare its `width`/`height` members
18	* reliably. We stamp two flat numeric meta keys on every new attachment
19	* (and opportunistically backfill existing ones) so `WP_Meta_Query` can
20	* use a normal NUMERIC `>=` comparison.
21	*
22	* @package WPDesktopMode
23	* @since 0.5.0
24	*/
25
26	defined( 'ABSPATH' ) \|\| exit;
27
28	/** Numeric post-meta keys stamped on every image attachment. */
29	const DESKTOP_MODE_META_WIDTH = '_desktop_mode_width';
30	const DESKTOP_MODE_META_HEIGHT = '_desktop_mode_height';
31
32	/** Option key flipped to `1` once every image has been backfilled. */
33	const DESKTOP_MODE_BACKFILL_DONE_OPTION = 'desktop_mode_media_dims_backfilled';
34
35	/** How many legacy attachments to backfill per filtered REST request. */
36	const DESKTOP_MODE_MEDIA_BACKFILL_BATCH = 50;
37
38	/**
39	* Stamp numeric dimension meta whenever an attachment's metadata is
40	* generated or updated. Hooked on both `wp_generate_attachment_metadata`
41	* (new uploads) and `wp_update_attachment_metadata` (regenerated
42	* thumbnails, image editor saves) so the stamp stays in sync with
43	* whatever Core thinks the canonical dimensions are.
44	*
45	* @since 0.5.0
46	*
47	* @param array $metadata Attachment metadata.
48	* @param int $attachment_id Attachment post ID.
49	* @return array The metadata, unchanged — we only read from it.
50	*/
51	function desktop_mode_stamp_media_dimensions( $metadata, $attachment_id ) {
52	if ( ! is_array( $metadata ) ) {
53	return $metadata;
54	}
55
56	$width = isset( $metadata['width'] ) ? (int) $metadata['width'] : 0;
57	$height = isset( $metadata['height'] ) ? (int) $metadata['height'] : 0;
58
59	// Stamp zero for images we can't measure (SVGs, broken files) so the
60	// backfill sweep knows we've already inspected this row and doesn't
61	// re-check it on every subsequent filtered request.
62	update_post_meta( $attachment_id, DESKTOP_MODE_META_WIDTH, max( 0, $width ) );
63	update_post_meta( $attachment_id, DESKTOP_MODE_META_HEIGHT, max( 0, $height ) );
64
65	return $metadata;
66	}
67	add_filter( 'wp_generate_attachment_metadata', 'desktop_mode_stamp_media_dimensions', 10, 2 );
68	add_filter( 'wp_update_attachment_metadata', 'desktop_mode_stamp_media_dimensions', 10, 2 );
69
70	/**
71	* Register the `desktop_mode_min_width` / `desktop_mode_min_height` query parameters on
72	* the media collection so Core sanitizes them before they reach our
73	* query filter. Without this, the params would still work but would
74	* show up as unknown to any REST consumer introspecting the schema.
75	*
76	* @since 0.5.0
77	*
78	* @param array $params Existing collection params.
79	* @return array
80	*/
81	function desktop_mode_register_media_query_params( $params ) {
82	$params['desktop_mode_min_width'] = array(
83	'description' => __( 'Only return images at least this many pixels wide.', 'desktop-mode' ),
84	'type' => 'integer',
85	'minimum' => 1,
86	);
87	$params['desktop_mode_min_height'] = array(
88	'description' => __( 'Only return images at least this many pixels tall.', 'desktop-mode' ),
89	'type' => 'integer',
90	'minimum' => 1,
91	);
92	return $params;
93	}
94	add_filter( 'rest_attachment_collection_params', 'desktop_mode_register_media_query_params' );
95
96	/**
97	* Inject meta_query clauses on the attachment REST query when either
98	* dimension filter is present. Triggers a bounded backfill first so
99	* legacy attachments (uploaded before this filter existed) start
100	* participating without a one-shot CLI command.
101	*
102	* @since 0.5.0
103	*
104	* @param array $args WP_Query args built by the REST controller.
105	* @param WP_REST_Request $request The REST request.
106	* @return array The query args, possibly with extra meta_query entries.
107	*/
108	function desktop_mode_filter_media_by_dimensions( $args, $request ) {
109	$min_width = absint( $request->get_param( 'desktop_mode_min_width' ) );
110	$min_height = absint( $request->get_param( 'desktop_mode_min_height' ) );
111
112	if ( ! $min_width && ! $min_height ) {
113	return $args;
114	}
115
116	// Chip away at any remaining unstamped attachments before the query
117	// runs, so a site upgrading into this feature gets useful results on
118	// roughly the first few picker opens rather than after a CLI run.
119	desktop_mode_backfill_media_dimensions( DESKTOP_MODE_MEDIA_BACKFILL_BATCH );
120
121	$meta_query = isset( $args['meta_query'] ) && is_array( $args['meta_query'] )
122	? $args['meta_query']
123	: array();
124
125	$clauses = array();
126	if ( $min_width ) {
127	$clauses[] = array(
128	'key' => DESKTOP_MODE_META_WIDTH,
129	'value' => $min_width,
130	'compare' => '>=',
131	'type' => 'NUMERIC',
132	);
133	}
134	if ( $min_height ) {
135	$clauses[] = array(
136	'key' => DESKTOP_MODE_META_HEIGHT,
137	'value' => $min_height,
138	'compare' => '>=',
139	'type' => 'NUMERIC',
140	);
141	}
142
143	if ( count( $clauses ) > 1 ) {
144	$clauses['relation'] = 'AND';
145	}
146
147	// Compose with any existing meta_query so we don't stomp other
148	// filters (Core's own, or anything plugins have layered on).
149	if ( empty( $meta_query ) ) {
150	$args['meta_query'] = $clauses; // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_query -- NUMERIC >= dimension filter on indexed meta keys; canonical WP pattern for picker filtering.
151	} else {
152	$args['meta_query'] = array( // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_query -- composed AND clause merging caller meta_query with our dimension filter.
153	'relation' => 'AND',
154	$meta_query,
155	$clauses,
156	);
157	}
158
159	return $args;
160	}
161	add_filter( 'rest_attachment_query', 'desktop_mode_filter_media_by_dimensions', 10, 2 );
162
163	/**
164	* Stamp dimension meta on up to $batch image attachments that don't
165	* have it yet. Returns early once a site has been fully backfilled so
166	* filtered REST requests don't keep paying for an empty sweep query.
167	*
168	* Ordering by `ID DESC` so newest attachments get stamped first — the
169	* user is most likely to be looking for something they uploaded
170	* recently, so we prioritize the tail they're staring at.
171	*
172	* @since 0.5.0
173	*
174	* @param int $batch Maximum attachments to stamp this pass.
175	* @return int Number of attachments stamped (0 when nothing remained).
176	*/
177	function desktop_mode_backfill_media_dimensions( $batch ) {
178	if ( get_option( DESKTOP_MODE_BACKFILL_DONE_OPTION ) ) {
179	return 0;
180	}
181
182	$ids = get_posts(
183	array(
184	'post_type' => 'attachment',
185	'post_status' => 'inherit',
186	'post_mime_type' => 'image',
187	'posts_per_page' => (int) $batch,
188	'orderby' => 'ID',
189	'order' => 'DESC',
190	'fields' => 'ids',
191	'no_found_rows' => true,
192	'update_post_term_cache' => false,
193	// phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_query -- one-shot backfill targeting the small subset of attachments that lack our dimension stamp; runs at most $batch rows per filtered request and stops once the site option flips.
194	'meta_query' => array(
195	array(
196	'key' => DESKTOP_MODE_META_WIDTH,
197	'compare' => 'NOT EXISTS',
198	),
199	),
200	)
201	);
202
203	if ( empty( $ids ) ) {
204	// Flip the flag so future filtered requests skip this query.
205	// If a plugin ever adds new images via a back door that bypasses
206	// `wp_generate_attachment_metadata`, those can be picked up by
207	// manually deleting this option.
208	update_option( DESKTOP_MODE_BACKFILL_DONE_OPTION, 1, false );
209	return 0;
210	}
211
212	foreach ( $ids as $id ) {
213	// `wp_get_attachment_metadata()` hits the object cache if it was
214	// primed by the enclosing query; otherwise it's a single meta
215	// lookup per id. We're bounded at $batch per request so the
216	// per-request overhead stays predictable.
217	$metadata = wp_get_attachment_metadata( $id );
218
219	$width = is_array( $metadata ) && isset( $metadata['width'] ) ? (int) $metadata['width'] : 0;
220	$height = is_array( $metadata ) && isset( $metadata['height'] ) ? (int) $metadata['height'] : 0;
221
222	// Always stamp, even when zero — that's how the sweep query
223	// knows to skip this row on the next pass.
224	update_post_meta( $id, DESKTOP_MODE_META_WIDTH, max( 0, $width ) );
225	update_post_meta( $id, DESKTOP_MODE_META_HEIGHT, max( 0, $height ) );
226	}
227
228	return count( $ids );
229	}
230