class.wpcom-json-api-list-media-v1-1-endpoint.php — Jetpack – WP Security, Backup, Speed, & Growth 16.0.1

jetpack / json-endpoints / class.wpcom-json-api-list-media-v1-1-endpoint.php

jetpack / json-endpoints Last commit date

class.wpcom-json-api-list-media-v1-1-endpoint.php

358 lines

1	<?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName
2
3	if ( ! defined( 'ABSPATH' ) ) {
4	exit( 0 );
5	}
6
7	/**
8	* List Media v1_1 endpoint.
9	*/
10	new WPCOM_JSON_API_List_Media_v1_1_Endpoint(
11	array(
12	'description' => 'Get a list of items in the media library.',
13	'group' => 'media',
14	'stat' => 'media',
15	'min_version' => '1.1',
16	'max_version' => '1.1',
17	'method' => 'GET',
18	'path' => '/sites/%s/media/',
19	'path_labels' => array(
20	'$site' => '(int\|string) Site ID or domain',
21	),
22
23	'query_parameters' => array(
24	'number' => '(int=20) The number of media items to return. Limit: 100.',
25	'offset' => '(int=0) 0-indexed offset.',
26	'page' => '(int) Return the Nth 1-indexed page of posts. Takes precedence over the <code>offset</code> parameter.',
27	'page_handle' => '(string) A page handle, returned from a previous API call as a <code>meta.next_page</code> property. This is the most efficient way to fetch the next page of results.',
28	'order' => array(
29	'DESC' => 'Return files in descending order. For dates, that means newest to oldest.',
30	'ASC' => 'Return files in ascending order. For dates, that means oldest to newest.',
31	),
32	'order_by' => array(
33	'date' => 'Order by the uploaded time of each file.',
34	'title' => 'Order lexicographically by file titles.',
35	'ID' => 'Order by media ID.',
36	),
37	'search' => '(string) Search query.',
38	'post_ID' => '(int) Default is showing all items. The post where the media item is attached. 0 shows unattached media items.',
39	'mime_type' => "(string) Default is empty. Filter by mime type (e.g., 'image/jpeg', 'application/pdf'). Partial searches also work (e.g. passing 'image' will search for all image files).",
40	'after' => '(ISO 8601 datetime) Return media items uploaded after the specified datetime.',
41	'before' => '(ISO 8601 datetime) Return media items uploaded before the specified datetime.',
42	),
43
44	'response_format' => array(
45	'media' => '(array) Array of media objects',
46	'found' => '(int) The number of total results found',
47	'meta' => '(object) Meta data',
48	),
49
50	'example_request' => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/media',
51	'example_request_data' => array(
52	'headers' => array(
53	'authorization' => 'Bearer YOUR_API_TOKEN',
54	),
55	),
56	)
57	);
58
59	/**
60	* List media v1_1 endpoint class.
61	*
62	* @phan-constructor-used-for-side-effects
63	*/
64	class WPCOM_JSON_API_List_Media_v1_1_Endpoint extends WPCOM_JSON_API_Endpoint { // phpcs:ignore
65
66	/**
67	* Date range.
68	*
69	* @var array
70	*/
71	public $date_range = array();
72
73	/**
74	* The page handle.
75	*
76	* @var array
77	*/
78	public $page_handle = array();
79
80	/**
81	* Performed query
82	*
83	* @var array
84	*/
85	public $performed_query = array();
86
87	/**
88	* API callback.
89	*
90	* @param string $path - the path.
91	* @param string $blog_id - the blog ID.
92	*/
93	public function callback( $path = '', $blog_id = 0 ) {
94	$blog_id = $this->api->switch_to_blog_and_validate_user( $this->api->get_blog_id( $blog_id ) );
95	if ( is_wp_error( $blog_id ) ) {
96	return $blog_id;
97	}
98
99	// upload_files can probably be used for other endpoints but we want contributors to be able to use media too.
100	if ( ! current_user_can( 'edit_posts' ) ) {
101	return new WP_Error( 'unauthorized', 'User cannot view media', 403 );
102	}
103
104	$args = $this->query_args();
105	$is_eligible_for_page_handle = true;
106
107	if ( $args['number'] < 1 ) {
108	$args['number'] = 20;
109	} elseif ( 100 < $args['number'] ) {
110	return new WP_Error( 'invalid_number', 'The NUMBER parameter must be less than or equal to 100.', 400 );
111	}
112
113	if ( defined( 'IS_WPCOM' ) && IS_WPCOM ) {
114	$this->load_theme_functions();
115	}
116
117	if ( isset( $args['before'] ) ) {
118	$this->date_range['before'] = $args['before'];
119	}
120	if ( isset( $args['after'] ) ) {
121	$this->date_range['after'] = $args['after'];
122	}
123
124	$query = array(
125	'post_type' => 'attachment',
126	'post_status' => 'inherit',
127	'post_parent' => $args['post_ID'] ?? null,
128	'posts_per_page' => $args['number'],
129	'post_mime_type' => $args['mime_type'] ?? null,
130	'order' => $args['order'] ?? 'DESC',
131	'orderby' => $args['order_by'] ?? 'date',
132	's' => $args['search'] ?? null,
133	'meta_query' => array(
134	array(
135	'key' => 'videopress_poster_image',
136	'compare' => 'NOT EXISTS',
137	),
138	),
139	);
140
141	if ( isset( $args['page'] ) ) {
142	if ( $args['page'] < 1 ) {
143	$args['page'] = 1;
144	}
145
146	$query['paged'] = $args['page'];
147	if ( 1 !== $query['paged'] ) {
148	$is_eligible_for_page_handle = false;
149	}
150	} else {
151	if ( $args['offset'] < 0 ) {
152	$args['offset'] = 0;
153	}
154
155	$query['offset'] = $args['offset'];
156	if ( 0 !== $query['offset'] ) {
157	$is_eligible_for_page_handle = false;
158	}
159	}
160
161	if ( isset( $args['page_handle'] ) ) {
162	$page_handle = wp_parse_args( $args['page_handle'] );
163	if ( isset( $page_handle['value'] ) && isset( $page_handle['id'] ) ) {
164	// we have a valid looking page handle.
165	$this->page_handle = $page_handle;
166	add_filter( 'posts_where', array( $this, 'handle_where_for_page_handle' ) );
167	}
168	}
169
170	if ( $this->date_range ) {
171	add_filter( 'posts_where', array( $this, 'handle_date_range' ) );
172	}
173
174	$this->performed_query = $query;
175	add_filter( 'posts_orderby', array( $this, 'handle_orderby_for_page_handle' ) );
176
177	$media = new WP_Query( $query );
178
179	remove_filter( 'posts_orderby', array( $this, 'handle_orderby_for_page_handle' ) );
180
181	if ( $this->date_range ) {
182	remove_filter( 'posts_where', array( $this, 'handle_date_range' ) );
183	$this->date_range = array();
184	}
185
186	if ( $this->page_handle ) {
187	remove_filter( 'posts_where', array( $this, 'handle_where_for_page_handle' ) );
188	}
189
190	$response = array();
191
192	foreach ( $media->posts as $item ) {
193	$response[] = $this->get_media_item_v1_1( $item->ID );
194	}
195
196	$return = array(
197	'found' => (int) $media->found_posts,
198	'media' => $response,
199	);
200
201	if ( $is_eligible_for_page_handle && $return['media'] ) {
202	$last_post = end( $return['media'] );
203	reset( $return['media'] );
204
205	if ( ( $return['found'] > count( $return['media'] ) ) && $last_post ) {
206	$return['meta'] = array();
207	$return['meta']['next_page'] = $this->build_page_handle( $last_post, $query );
208	}
209	}
210
211	return $return;
212	}
213
214	/**
215	* Build the page handle.
216	*
217	* @param object $post - the post object.
218	* @param array $query - the query.
219	*/
220	public function build_page_handle( $post, $query ) {
221	$column = $query['orderby'];
222	if ( ! $column ) {
223	$column = 'date';
224	}
225	return build_query(
226	array(
227	'value' => rawurlencode( $post->$column ),
228	'id' => $post->ID,
229	)
230	);
231	}
232
233	/**
234	* Handle figuring out the page handler is.
235	*
236	* @param string $where - sql where clause.
237	*/
238	public function handle_where_for_page_handle( $where ) {
239	global $wpdb;
240
241	$column = $this->performed_query['orderby'];
242	if ( ! $column ) {
243	$column = 'date';
244	}
245	$order = $this->performed_query['order'];
246	if ( ! $order ) {
247	$order = 'DESC';
248	}
249
250	if ( ! in_array( $column, array( 'ID', 'title', 'date', 'modified', 'comment_count' ), true ) ) {
251	return $where;
252	}
253
254	if ( ! in_array( $order, array( 'DESC', 'ASC' ), true ) ) {
255	return $where;
256	}
257
258	$db_column = '';
259	$db_value = '';
260	switch ( $column ) {
261	case 'ID':
262	$db_column = 'ID';
263	$db_value = '%d';
264	break;
265	case 'title':
266	$db_column = 'post_title';
267	$db_value = '%s';
268	break;
269	case 'date':
270	$db_column = 'post_date';
271	$db_value = 'CAST( %s as DATETIME )';
272	break;
273	case 'modified':
274	$db_column = 'post_modified';
275	$db_value = 'CAST( %s as DATETIME )';
276	break;
277	case 'comment_count':
278	$db_column = 'comment_count';
279	$db_value = '%d';
280	break;
281	}
282
283	if ( 'DESC' === $order ) {
284	$db_order = '<';
285	} else {
286	$db_order = '>';
287	}
288
289	// Add a clause that limits the results to items beyond the passed item, or equivalent to the passed item
290	// but with an ID beyond the passed item. When we're ordering by the ID already, we only ask for items
291	// beyond the passed item.
292	$where .= $wpdb->prepare( " AND ( ( `$wpdb->posts`.`$db_column` $db_order $db_value ) ", $this->page_handle['value'] ); // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare
293	if ( 'ID' !== $db_column ) {
294	$where .= $wpdb->prepare( "OR ( `$wpdb->posts`.`$db_column` = $db_value AND `$wpdb->posts`.ID $db_order %d )", $this->page_handle['value'], $this->page_handle['id'] ); // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber, WordPress.DB.PreparedSQL.InterpolatedNotPrepared
295	}
296	$where .= ' )';
297
298	return $where;
299	}
300
301	/**
302	* Handle date range.
303	*
304	* @param string $where - sql where clause.
305	*/
306	public function handle_date_range( $where ) {
307	global $wpdb;
308
309	switch ( count( $this->date_range ) ) {
310	case 2:
311	$where .= $wpdb->prepare(
312	" AND `$wpdb->posts`.post_date BETWEEN CAST( %s AS DATETIME ) AND CAST( %s AS DATETIME ) ",
313	$this->date_range['after'],
314	$this->date_range['before']
315	);
316	break;
317	case 1:
318	if ( isset( $this->date_range['before'] ) ) {
319	$where .= $wpdb->prepare(
320	" AND `$wpdb->posts`.post_date <= CAST( %s AS DATETIME ) ",
321	$this->date_range['before']
322	);
323	} else {
324	$where .= $wpdb->prepare(
325	" AND `$wpdb->posts`.post_date >= CAST( %s AS DATETIME ) ",
326	$this->date_range['after']
327	);
328	}
329	break;
330	}
331
332	return $where;
333	}
334
335	/**
336	* Handle how page handle is ordered by.
337	*
338	* @param string $orderby - how we want to order things by.
339	*/
340	public function handle_orderby_for_page_handle( $orderby ) {
341	global $wpdb;
342	if ( 'ID' === $this->performed_query['orderby'] ) {
343	// bail if we're already ordering by ID.
344	return $orderby;
345	}
346
347	if ( $orderby ) {
348	$orderby .= ' ,';
349	}
350	$order = $this->performed_query['order'];
351	if ( ! $order ) {
352	$order = 'DESC';
353	}
354	$orderby .= " `$wpdb->posts`.ID $order";
355	return $orderby;
356	}
357	}
358