gallery-management-functions.php — Gallery : FooGallery 3.2.6

foogallery / includes / gallery-management-functions.php

foogallery / includes Last commit date

gallery-management-functions.php

592 lines

1	<?php
2
3	if ( ! defined( 'ABSPATH' ) ) {
4	exit;
5	}
6
7	/**
8	* FooGallery gallery-management functions.
9	*
10	* @package FooGallery
11	*/
12
13	/**
14	* Normalize a list of attachment IDs.
15	*
16	* Authorization is the caller's responsibility.
17	*
18	* @param mixed $attachment_ids Attachment IDs as an array or comma-separated string.
19	*
20	* @return int[]
21	*/
22	function foogallery_normalize_attachment_ids( $attachment_ids ) {
23	if ( is_string( $attachment_ids ) ) {
24	$attachment_ids = array_filter( array_map( 'trim', explode( ',', $attachment_ids ) ) );
25	} elseif ( ! is_array( $attachment_ids ) ) {
26	$attachment_ids = array( $attachment_ids );
27	}
28
29	$normalized = array();
30
31	foreach ( $attachment_ids as $attachment_id ) {
32	if ( ! is_scalar( $attachment_id ) ) {
33	continue;
34	}
35
36	$attachment_id = absint( $attachment_id );
37
38	if ( $attachment_id > 0 && ! in_array( $attachment_id, $normalized, true ) ) {
39	$normalized[] = $attachment_id;
40	}
41	}
42
43	return $normalized;
44	}
45
46	/**
47	* Validate a list of attachment IDs.
48	*
49	* Authorization is the caller's responsibility.
50	*
51	* @param mixed $attachment_ids Attachment IDs as an array or comma-separated string.
52	*
53	* @return int[]\|WP_Error
54	*/
55	function foogallery_validate_attachment_ids( $attachment_ids ) {
56	if ( is_string( $attachment_ids ) ) {
57	$candidates = array_filter( array_map( 'trim', explode( ',', $attachment_ids ) ), 'strlen' );
58	} elseif ( is_array( $attachment_ids ) ) {
59	$candidates = $attachment_ids;
60	} elseif ( null === $attachment_ids \|\| false === $attachment_ids \|\| '' === $attachment_ids ) {
61	$candidates = array();
62	} else {
63	$candidates = array( $attachment_ids );
64	}
65
66	$attachment_ids = foogallery_normalize_attachment_ids( $candidates );
67	$invalid_ids = array();
68
69	foreach ( $candidates as $candidate ) {
70	if ( ! is_scalar( $candidate ) ) {
71	$invalid_ids[] = 0;
72	continue;
73	}
74
75	$attachment_id = absint( $candidate );
76	$post = get_post( $attachment_id );
77
78	if ( ! $attachment_id \|\| ! $post \|\| 'attachment' !== $post->post_type ) {
79	$invalid_ids[] = $attachment_id;
80	}
81	}
82
83	if ( ! empty( $invalid_ids ) ) {
84	$invalid_ids = array_values( array_unique( $invalid_ids ) );
85
86	return new WP_Error(
87	'foogallery_invalid_attachments',
88	__( 'One or more attachment IDs are invalid.', 'foogallery' ),
89	array(
90	'invalid_attachment_ids' => $invalid_ids,
91	)
92	);
93	}
94
95	return $attachment_ids;
96	}
97
98	/**
99	* Clear all cached state for a gallery after a write.
100	*
101	* Authorization is the caller's responsibility.
102	*
103	* @param int $gallery_id Gallery ID.
104	*
105	* @return void
106	*/
107	function foogallery_clear_gallery_cache( $gallery_id ) {
108	$gallery_id = absint( $gallery_id );
109
110	if ( ! $gallery_id ) {
111	return;
112	}
113
114	delete_post_meta( $gallery_id, FOOGALLERY_META_CACHE );
115	clean_post_cache( $gallery_id );
116	}
117
118	/**
119	* Create a media-library-backed FooGallery.
120	*
121	* Authorization is the caller's responsibility.
122	*
123	* @param array $args {
124	* Optional gallery arguments.
125	*
126	* @type string $title Gallery title. Default "Untitled Gallery".
127	* @type string $status draft, publish, or private. Default draft.
128	* @type int $author_id Post author. Default current user ID.
129	* @type string $template Registered gallery template slug.
130	* @type array $settings Complete storage-format settings array.
131	* @type array $attachment_ids Media Library attachment IDs.
132	* @type int $source_gallery_id Gallery whose configuration should be copied.
133	* @type string $sort Optional gallery sort value.
134	* @type string $custom_css Optional gallery custom CSS.
135	* }
136	* @param array $context Optional caller-provided context passed to hooks.
137	*
138	* @return int\|WP_Error New gallery ID or an error.
139	*/
140	function foogallery_insert_gallery( $args = array(), $context = array() ) {
141	$args = apply_filters( 'foogallery_insert_gallery_args', $args, $context );
142
143	if ( ! is_array( $args ) \|\| ! is_array( $context ) ) {
144	return new WP_Error(
145	'foogallery_invalid_gallery',
146	__( 'Gallery arguments and context must be arrays.', 'foogallery' )
147	);
148	}
149
150	$has_template_arg = array_key_exists( 'template', $args );
151	$explicit_template = $has_template_arg && is_scalar( $args['template'] ) && '' !== trim( (string) $args['template'] );
152	$explicit_settings = array_key_exists( 'settings', $args ) && null !== $args['settings'];
153	$explicit_sort = array_key_exists( 'sort', $args );
154	$explicit_custom_css = array_key_exists( 'custom_css', $args );
155	$explicit_source = array_key_exists( 'source_gallery_id', $args );
156	$defaults = array(
157	'title' => __( 'Untitled Gallery', 'foogallery' ),
158	'status' => 'draft',
159	'author_id' => get_current_user_id(),
160	'template' => '',
161	'settings' => null,
162	'attachment_ids' => array(),
163	'source_gallery_id' => 0,
164	);
165	$args = wp_parse_args( $args, $defaults );
166	$title = is_scalar( $args['title'] ) ? sanitize_text_field( (string) $args['title'] ) : '';
167	$status = is_scalar( $args['status'] ) ? sanitize_key( (string) $args['status'] ) : '';
168	$author_id = is_scalar( $args['author_id'] ) ? absint( $args['author_id'] ) : 0;
169	$template = is_scalar( $args['template'] ) ? sanitize_key( (string) $args['template'] ) : '';
170	$source_gallery_id = is_scalar( $args['source_gallery_id'] ) ? absint( $args['source_gallery_id'] ) : 0;
171
172	if ( '' === $title ) {
173	$title = $defaults['title'];
174	}
175
176	if ( ! in_array( $status, array( 'draft', 'publish', 'private' ), true ) ) {
177	return new WP_Error(
178	'foogallery_invalid_status',
179	__( 'Gallery status must be draft, publish, or private.', 'foogallery' )
180	);
181	}
182
183	if ( $has_template_arg && ! is_scalar( $args['template'] ) ) {
184	return new WP_Error(
185	'foogallery_invalid_template',
186	__( 'The requested gallery template is not registered.', 'foogallery' )
187	);
188	}
189
190	if ( $explicit_template && '' === $template ) {
191	return new WP_Error(
192	'foogallery_invalid_template',
193	__( 'The requested gallery template is not registered.', 'foogallery' )
194	);
195	}
196
197	$empty_source_values = array( 0, '0', '', null );
198
199	if ( $explicit_source && ! in_array( $args['source_gallery_id'], $empty_source_values, true ) && ( ! is_scalar( $args['source_gallery_id'] ) \|\| ! is_numeric( $args['source_gallery_id'] ) \|\| (int) $args['source_gallery_id'] <= 0 ) ) {
200	return new WP_Error(
201	'foogallery_invalid_source_gallery',
202	__( 'A valid source gallery ID is required.', 'foogallery' )
203	);
204	}
205
206	if ( $explicit_settings && ! is_array( $args['settings'] ) ) {
207	return new WP_Error(
208	'foogallery_invalid_gallery',
209	__( 'Gallery settings must be an array.', 'foogallery' )
210	);
211	}
212
213	$attachment_ids = foogallery_validate_attachment_ids( $args['attachment_ids'] );
214
215	if ( is_wp_error( $attachment_ids ) ) {
216	return $attachment_ids;
217	}
218
219	$settings = $explicit_settings ? $args['settings'] : array();
220	$sort = $explicit_sort && is_scalar( $args['sort'] ) ? sanitize_text_field( (string) $args['sort'] ) : '';
221	$custom_css = $explicit_custom_css && is_scalar( $args['custom_css'] ) ? foogallery_sanitize_full( (string) $args['custom_css'] ) : '';
222
223	if ( $source_gallery_id > 0 ) {
224	$source_post = get_post( $source_gallery_id );
225
226	if ( ! $source_post \|\| FOOGALLERY_CPT_GALLERY !== $source_post->post_type ) {
227	return new WP_Error(
228	'foogallery_invalid_source_gallery',
229	__( 'The requested source gallery could not be found.', 'foogallery' )
230	);
231	}
232
233	$source_datasource = get_post_meta( $source_gallery_id, FOOGALLERY_META_DATASOURCE, true );
234
235	if ( '' === $source_datasource ) {
236	$source_datasource = foogallery_default_datasource();
237	}
238
239	if ( foogallery_default_datasource() !== $source_datasource ) {
240	return new WP_Error(
241	'foogallery_unsupported_datasource',
242	__( 'Only media-library-backed source galleries are supported.', 'foogallery' )
243	);
244	}
245
246	$source_template = sanitize_key( (string) get_post_meta( $source_gallery_id, FOOGALLERY_META_TEMPLATE, true ) );
247
248	if ( ! $explicit_template ) {
249	$template = $source_template;
250	}
251
252	if ( ! $explicit_settings && ( ! $explicit_template \|\| $template === $source_template ) ) {
253	$source_settings = get_post_meta( $source_gallery_id, FOOGALLERY_META_SETTINGS, true );
254	$settings = is_array( $source_settings ) ? $source_settings : array();
255	}
256
257	if ( ! $explicit_sort ) {
258	$sort = (string) get_post_meta( $source_gallery_id, FOOGALLERY_META_SORT, true );
259	}
260
261	if ( ! $explicit_custom_css ) {
262	$custom_css = (string) get_post_meta( $source_gallery_id, FOOGALLERY_META_CUSTOM_CSS, true );
263	}
264	}
265
266	if ( '' === $template ) {
267	$template = sanitize_key( (string) foogallery_default_gallery_template() );
268	}
269
270	if ( false === foogallery_get_gallery_template( $template ) ) {
271	return new WP_Error(
272	'foogallery_invalid_template',
273	__( 'The requested gallery template is not registered.', 'foogallery' )
274	);
275	}
276
277	$gallery_id = wp_insert_post(
278	array(
279	'post_type' => FOOGALLERY_CPT_GALLERY,
280	'post_title' => $title,
281	'post_status' => $status,
282	'post_author' => $author_id,
283	),
284	true
285	);
286
287	if ( is_wp_error( $gallery_id ) ) {
288	return $gallery_id;
289	}
290
291	$metadata = array(
292	FOOGALLERY_META_TEMPLATE => $template,
293	FOOGALLERY_META_SETTINGS => $settings,
294	FOOGALLERY_META_ATTACHMENTS => $attachment_ids,
295	FOOGALLERY_META_DATASOURCE => foogallery_default_datasource(),
296	FOOGALLERY_META_SORT => $sort,
297	FOOGALLERY_META_CUSTOM_CSS => $custom_css,
298	);
299
300	foreach ( $metadata as $meta_key => $meta_value ) {
301	$updated = update_post_meta( $gallery_id, $meta_key, $meta_value );
302
303	if ( false === $updated && get_post_meta( $gallery_id, $meta_key, true ) !== $meta_value ) {
304	wp_delete_post( $gallery_id, true );
305
306	return new WP_Error(
307	'foogallery_invalid_gallery',
308	__( 'The gallery could not be created.', 'foogallery' )
309	);
310	}
311	}
312
313	delete_post_meta( $gallery_id, FOOGALLERY_META_DATASOURCE_VALUE );
314	foogallery_clear_gallery_cache( $gallery_id );
315
316	if ( function_exists( 'foogallery_set_gallery_video_count' ) ) {
317	foogallery_set_gallery_video_count( $gallery_id );
318	}
319
320	do_action(
321	'foogallery_after_save_gallery',
322	$gallery_id,
323	array_merge(
324	$context,
325	array(
326	'operation' => 'insert',
327	'gallery_id' => $gallery_id,
328	'attachment_ids' => $attachment_ids,
329	)
330	)
331	);
332
333	return $gallery_id;
334	}
335
336	/**
337	* Get normalized attachment IDs belonging to a gallery.
338	*
339	* Authorization is the caller's responsibility.
340	*
341	* @param int $gallery_id Gallery ID.
342	*
343	* @return int[]\|WP_Error
344	*/
345	function foogallery_get_gallery_attachment_ids( $gallery_id ) {
346	$gallery_id = absint( $gallery_id );
347
348	if ( ! $gallery_id ) {
349	return new WP_Error(
350	'foogallery_invalid_gallery',
351	__( 'A valid gallery ID is required.', 'foogallery' )
352	);
353	}
354
355	$gallery_post = get_post( $gallery_id );
356
357	if ( ! $gallery_post \|\| FOOGALLERY_CPT_GALLERY !== $gallery_post->post_type ) {
358	return new WP_Error(
359	'foogallery_gallery_not_found',
360	__( 'The requested gallery could not be found.', 'foogallery' )
361	);
362	}
363
364	$datasource = get_post_meta( $gallery_id, FOOGALLERY_META_DATASOURCE, true );
365
366	if ( '' === $datasource ) {
367	$datasource = foogallery_default_datasource();
368	}
369
370	if ( foogallery_default_datasource() !== $datasource ) {
371	return new WP_Error(
372	'foogallery_unsupported_datasource',
373	__( 'Only media-library-backed galleries are supported.', 'foogallery' )
374	);
375	}
376
377	return foogallery_normalize_attachment_ids( get_post_meta( $gallery_id, FOOGALLERY_META_ATTACHMENTS, true ) );
378	}
379
380	/**
381	* Update gallery attachments.
382	*
383	* Authorization is the caller's responsibility.
384	*
385	* @param int $gallery_id Gallery ID.
386	* @param array $changes {
387	* Attachment changes.
388	*
389	* @type array $replace Replace the complete attachment list.
390	* @type array $add Append attachments that are not already present.
391	* @type array $remove Remove attachments from the gallery.
392	* }
393	* @param array $context Optional caller-provided hook context.
394	*
395	* @return int[]\|WP_Error Final attachment IDs.
396	*/
397	function foogallery_update_gallery_attachments( $gallery_id, $changes, $context = array() ) {
398	if ( ! is_array( $changes ) \|\| ! is_array( $context ) ) {
399	return new WP_Error(
400	'foogallery_no_attachment_changes',
401	__( 'Attachment changes and context must be arrays.', 'foogallery' )
402	);
403	}
404
405	$old_attachment_ids = foogallery_get_gallery_attachment_ids( $gallery_id );
406
407	if ( is_wp_error( $old_attachment_ids ) ) {
408	return $old_attachment_ids;
409	}
410
411	$allowed_keys = array( 'replace', 'add', 'remove' );
412	$unknown_keys = array_diff( array_keys( $changes ), $allowed_keys );
413
414	if ( ! empty( $unknown_keys ) ) {
415	return new WP_Error(
416	'foogallery_invalid_attachment_changes',
417	__( 'One or more attachment change operations are not supported.', 'foogallery' ),
418	array(
419	'invalid_change_keys' => array_values( $unknown_keys ),
420	)
421	);
422	}
423
424	$has_replace = array_key_exists( 'replace', $changes );
425	$has_add = array_key_exists( 'add', $changes );
426	$has_remove = array_key_exists( 'remove', $changes );
427
428	if ( ! $has_replace && ! $has_add && ! $has_remove ) {
429	return new WP_Error(
430	'foogallery_no_attachment_changes',
431	__( 'Provide replace, add, remove, or a combination of add and remove.', 'foogallery' )
432	);
433	}
434
435	if ( $has_replace && ( $has_add \|\| $has_remove ) ) {
436	return new WP_Error(
437	'foogallery_conflicting_attachment_changes',
438	__( 'replace cannot be combined with add or remove.', 'foogallery' )
439	);
440	}
441
442	if ( $has_replace ) {
443	$new_attachment_ids = foogallery_validate_attachment_ids( $changes['replace'] );
444
445	if ( is_wp_error( $new_attachment_ids ) ) {
446	return $new_attachment_ids;
447	}
448
449	$operation = 'replace';
450	} else {
451	$new_attachment_ids = $old_attachment_ids;
452
453	if ( $has_add ) {
454	$add_attachment_ids = foogallery_validate_attachment_ids( $changes['add'] );
455
456	if ( is_wp_error( $add_attachment_ids ) ) {
457	return $add_attachment_ids;
458	}
459
460	foreach ( $add_attachment_ids as $attachment_id ) {
461	if ( ! in_array( $attachment_id, $new_attachment_ids, true ) ) {
462	$new_attachment_ids[] = $attachment_id;
463	}
464	}
465	}
466
467	if ( $has_remove ) {
468	$remove_attachment_ids = foogallery_normalize_attachment_ids( $changes['remove'] );
469	$new_attachment_ids = array_values( array_diff( $new_attachment_ids, $remove_attachment_ids ) );
470	}
471
472	if ( $has_add && $has_remove ) {
473	$operation = 'add_remove';
474	} elseif ( $has_add ) {
475	$operation = 'add';
476	} else {
477	$operation = 'remove';
478	}
479	}
480
481	if ( $new_attachment_ids === $old_attachment_ids ) {
482	return $new_attachment_ids;
483	}
484
485	$gallery_id = absint( $gallery_id );
486	$updated = update_post_meta( $gallery_id, FOOGALLERY_META_ATTACHMENTS, $new_attachment_ids );
487
488	if ( false === $updated && get_post_meta( $gallery_id, FOOGALLERY_META_ATTACHMENTS, true ) !== $new_attachment_ids ) {
489	return new WP_Error(
490	'foogallery_invalid_gallery',
491	__( 'The gallery attachments could not be updated.', 'foogallery' )
492	);
493	}
494
495	update_post_meta( $gallery_id, FOOGALLERY_META_DATASOURCE, foogallery_default_datasource() );
496	delete_post_meta( $gallery_id, FOOGALLERY_META_DATASOURCE_VALUE );
497	foogallery_clear_gallery_cache( $gallery_id );
498
499	if ( function_exists( 'foogallery_set_gallery_video_count' ) ) {
500	foogallery_set_gallery_video_count( $gallery_id );
501	}
502
503	do_action(
504	'foogallery_gallery_attachments_updated',
505	$gallery_id,
506	$old_attachment_ids,
507	$new_attachment_ids,
508	$operation,
509	$context
510	);
511
512	do_action(
513	'foogallery_after_save_gallery',
514	$gallery_id,
515	array_merge(
516	$context,
517	array(
518	'operation' => 'update_attachments',
519	'attachment_action' => $operation,
520	'gallery_id' => $gallery_id,
521	'attachment_ids' => $new_attachment_ids,
522	'old_attachment_ids' => $old_attachment_ids,
523	)
524	)
525	);
526
527	return $new_attachment_ids;
528	}
529
530	/**
531	* Replace all gallery attachments.
532	*
533	* Authorization is the caller's responsibility.
534	*
535	* @param int $gallery_id Gallery ID.
536	* @param array $attachment_ids Attachment IDs.
537	* @param array $context Optional caller-provided hook context.
538	*
539	* @return int[]\|WP_Error Final attachment IDs.
540	*/
541	function foogallery_set_gallery_attachments( $gallery_id, $attachment_ids, $context = array() ) {
542	return foogallery_update_gallery_attachments(
543	$gallery_id,
544	array(
545	'replace' => $attachment_ids,
546	),
547	$context
548	);
549	}
550
551	/**
552	* Add attachments without adding duplicates.
553	*
554	* Authorization is the caller's responsibility.
555	*
556	* @param int $gallery_id Gallery ID.
557	* @param array $attachment_ids Attachment IDs.
558	* @param array $context Optional caller-provided hook context.
559	*
560	* @return int[]\|WP_Error Final attachment IDs.
561	*/
562	function foogallery_add_gallery_attachments( $gallery_id, $attachment_ids, $context = array() ) {
563	return foogallery_update_gallery_attachments(
564	$gallery_id,
565	array(
566	'add' => $attachment_ids,
567	),
568	$context
569	);
570	}
571
572	/**
573	* Remove attachments from a gallery.
574	*
575	* Authorization is the caller's responsibility.
576	*
577	* @param int $gallery_id Gallery ID.
578	* @param array $attachment_ids Attachment IDs.
579	* @param array $context Optional caller-provided hook context.
580	*
581	* @return int[]\|WP_Error Final attachment IDs.
582	*/
583	function foogallery_remove_gallery_attachments( $gallery_id, $attachment_ids, $context = array() ) {
584	return foogallery_update_gallery_attachments(
585	$gallery_id,
586	array(
587	'remove' => $attachment_ids,
588	),
589	$context
590	);
591	}
592