advanced-custom-fields / includes / local-fields.php

local-fields.php in Advanced Custom Fields (ACF®) 6.1.6, at includes/local-fields.php

732 lines 15.7 KB

Raw Download Zip

1	<?php
2
3	// Register local stores.
4	acf_register_store( 'local-fields' );
5	acf_register_store( 'local-groups' );
6	acf_register_store( 'local-empty' );
7	acf_register_store( 'local-post-types' );
8	acf_register_store( 'local-taxonomies' );
9
10	// Register filter.
11	acf_enable_filter( 'local' );
12
13	/**
14	* acf_enable_local
15	*
16	* Enables the local filter.
17	*
18	* @date 22/1/19
19	* @since 5.7.10
20	*
21	* @param void
22	* @return void
23	*/
24	function acf_enable_local() {
25	acf_enable_filter( 'local' );
26	}
27
28	/**
29	* acf_disable_local
30	*
31	* Disables the local filter.
32	*
33	* @date 22/1/19
34	* @since 5.7.10
35	*
36	* @param void
37	* @return void
38	*/
39	function acf_disable_local() {
40	acf_disable_filter( 'local' );
41	}
42
43	/**
44	* acf_is_local_enabled
45	*
46	* Returns true if local fields are enabled.
47	*
48	* @date 23/1/19
49	* @since 5.7.10
50	*
51	* @param void
52	* @return bool
53	*/
54	function acf_is_local_enabled() {
55	return ( acf_is_filter_enabled( 'local' ) && acf_get_setting( 'local' ) );
56	}
57
58	/**
59	* Returns either local store or a dummy store for the given name or post type.
60	*
61	* @date 23/1/19
62	* @since 5.7.10
63	*
64	* @param string $name The store name.
65	* @param string $post_type The post type for the desired store.
66	* @return ACF_Data
67	*/
68	function acf_get_local_store( $name = '', $post_type = '' ) {
69	if ( '' !== $post_type ) {
70	switch ( $post_type ) {
71	case 'acf-post-type':
72	$name = 'post-types';
73	break;
74	case 'acf-taxonomy':
75	$name = 'taxonomies';
76	break;
77	case 'acf-field-group':
78	$name = 'groups';
79	break;
80	case 'acf-field':
81	$name = 'fields';
82	break;
83	}
84	}
85
86	if ( acf_is_local_enabled() && '' !== $name ) {
87	return acf_get_store( "local-$name" );
88	} else {
89	// Return dummy store if not enabled or no name provided.
90	return acf_get_store( 'local-empty' );
91	}
92	}
93
94	/**
95	* acf_reset_local
96	*
97	* Resets the local data.
98	*
99	* @date 22/1/19
100	* @since 5.7.10
101	*
102	* @param void
103	* @return void
104	*/
105	function acf_reset_local() {
106	acf_get_local_store( 'fields' )->reset();
107	acf_get_local_store( 'groups' )->reset();
108	acf_get_local_store( 'post-types' )->reset();
109	acf_get_local_store( 'taxonomies' )->reset();
110	}
111
112	/**
113	* acf_get_local_field_groups
114	*
115	* Returns all local field groups.
116	*
117	* @date 22/1/19
118	* @since 5.7.10
119	*
120	* @param void
121	* @return array
122	*/
123	function acf_get_local_field_groups() {
124	return acf_get_local_store( 'groups' )->get();
125	}
126
127	/**
128	* Returns local ACF posts with the provided post type.
129	*
130	* @since 6.1
131	*
132	* @param string $post_type The post type to check for.
133	* @return array\|mixed
134	*/
135	function acf_get_local_internal_posts( $post_type = 'acf-field-group' ) {
136	return acf_get_local_store( '', $post_type )->get();
137	}
138
139	/**
140	* acf_have_local_field_groups
141	*
142	* description
143	*
144	* @date 22/1/19
145	* @since 5.7.10
146	*
147	* @param type $var Description. Default.
148	* @return type Description.
149	*/
150	function acf_have_local_field_groups() {
151	return acf_get_local_store( 'groups' )->count() ? true : false;
152	}
153
154	/**
155	* acf_count_local_field_groups
156	*
157	* description
158	*
159	* @date 22/1/19
160	* @since 5.7.10
161	*
162	* @param type $var Description. Default.
163	* @return type Description.
164	*/
165	function acf_count_local_field_groups() {
166	return acf_get_local_store( 'groups' )->count();
167	}
168
169	/**
170	* acf_add_local_field_group
171	*
172	* Adds a local field group.
173	*
174	* @date 22/1/19
175	* @since 5.7.10
176	*
177	* @param array $field_group The field group array.
178	* @return bool
179	*/
180	function acf_add_local_field_group( $field_group ) {
181	// Apply default properties needed for import.
182	$field_group = wp_parse_args(
183	$field_group,
184	array(
185	'key' => '',
186	'title' => '',
187	'fields' => array(),
188	'local' => 'php',
189	)
190	);
191
192	// Generate key if only name is provided.
193	if ( ! $field_group['key'] ) {
194	$field_group_key = 'group_' . acf_slugify( $field_group['title'], '_' );
195	if ( $field_group_key === 'group_' ) {
196	$field_group_key = 'group_' . md5( $field_group['title'] );
197	}
198	$field_group['key'] = $field_group_key;
199	}
200
201	// Bail early if field group already exists.
202	if ( acf_is_local_field_group( $field_group['key'] ) ) {
203	return false;
204	}
205
206	// Prepare field group for import (adds menu_order and parent properties to fields).
207	$field_group = acf_prepare_field_group_for_import( $field_group );
208
209	// Extract fields from group.
210	$fields = acf_extract_var( $field_group, 'fields' );
211
212	// Add to store
213	acf_get_local_store( 'groups' )->set( $field_group['key'], $field_group );
214
215	// Add fields
216	if ( $fields ) {
217	acf_add_local_fields( $fields );
218	}
219
220	// Return true on success.
221	return true;
222	}
223
224	/**
225	* Adds a local ACF internal post type.
226	*
227	* @since 6.1
228	*
229	* @param array $post The main ACF post array.
230	* @param string $post_type The post type being added.
231	* @return bool
232	*/
233	function acf_add_local_internal_post_type( $post, $post_type ) {
234	// Apply default properties needed for import.
235	$post = wp_parse_args(
236	$post,
237	array(
238	'key' => '',
239	'title' => '',
240	'local' => 'json',
241	)
242	);
243
244	// Bail early if field group already exists.
245	if ( acf_is_local_internal_post_type( $post['key'], $post_type ) ) {
246	return false;
247	}
248
249	// Prepare field group for import (adds menu_order and parent properties to fields).
250	$post = acf_prepare_internal_post_type_for_import( $post, $post_type );
251
252	// Add to store.
253	acf_get_local_store( '', $post_type )->set( $post['key'], $post );
254
255	return true;
256	}
257
258	/**
259	* register_field_group
260	*
261	* See acf_add_local_field_group().
262	*
263	* @date 22/1/19
264	* @since 5.7.10
265	*
266	* @param array $field_group The field group array.
267	* @return void
268	*/
269	function register_field_group( $field_group ) {
270	acf_add_local_field_group( $field_group );
271	}
272
273	/**
274	* acf_remove_local_field_group
275	*
276	* Removes a field group for the given key.
277	*
278	* @date 22/1/19
279	* @since 5.7.10
280	*
281	* @param string $key The field group key.
282	* @return bool
283	*/
284	function acf_remove_local_field_group( $key = '' ) {
285	return acf_remove_local_internal_post_type( $key, 'acf-field-group' );
286	}
287
288	/**
289	* Removes a local ACF post with the given key and post type.
290	*
291	* @since 6.1
292	*
293	* @param string $key The ACF key.
294	* @param string $post_type The ACF post type.
295	* @return bool
296	*/
297	function acf_remove_local_internal_post_type( $key = '', $post_type = 'acf-field-group' ) {
298	return acf_get_local_store( '', $post_type )->remove( $key );
299	}
300
301	/**
302	* acf_is_local_field_group
303	*
304	* Returns true if a field group exists for the given key.
305	*
306	* @date 22/1/19
307	* @since 5.7.10
308	*
309	* @param string $key The field group key.
310	* @return bool
311	*/
312	function acf_is_local_field_group( $key = '' ) {
313	return acf_get_local_store( 'groups' )->has( $key );
314	}
315
316
317	/**
318	* Returns true if an ACF post exists for the given key.
319	*
320	* @since 6.1
321	*
322	* @param string $key The ACF key.
323	* @param string $post_type The ACF post type.
324	* @return bool
325	*/
326	function acf_is_local_internal_post_type( $key = '', $post_type = 'acf-field-group' ) {
327	return acf_get_local_store( '', $post_type )->has( $key );
328	}
329
330	/**
331	* acf_is_local_field_group_key
332	*
333	* Returns true if a field group exists for the given key.
334	*
335	* @date 22/1/19
336	* @since 5.7.10
337	*
338	* @param string $key The field group key.
339	* @return bool
340	*/
341	function acf_is_local_field_group_key( $key = '' ) {
342	return acf_is_local_internal_post_type_key( $key, 'acf-field-group' );
343	}
344
345	/**
346	* Returns true if a local ACF post exists for the given key.
347	*
348	* @since 6.1
349	*
350	* @param string $key The ACF post key.
351	* @param string $post_type The post type to check.
352	* @return bool
353	*/
354	function acf_is_local_internal_post_type_key( $key = '', $post_type = '' ) {
355	return acf_get_local_store( '', $post_type )->is( $key );
356	}
357
358	/**
359	* acf_get_local_field_group
360	*
361	* Returns a field group for the given key.
362	*
363	* @date 22/1/19
364	* @since 5.7.10
365	*
366	* @param string $key The field group key.
367	* @return (array\|null)
368	*/
369	function acf_get_local_field_group( $key = '' ) {
370	return acf_get_local_store( 'groups' )->get( $key );
371	}
372
373	/**
374	* Returns an ACF post for the given key.
375	*
376	* @since 6.1
377	*
378	* @param string $key The field group key.
379	* @param string $post_type The ACF post type.
380	* @return array\|null
381	*/
382	function acf_get_local_internal_post_type( $key = '', $post_type = 'acf-field-group' ) {
383	return acf_get_local_store( '', $post_type )->get( $key );
384	}
385
386	/**
387	* acf_add_local_fields
388	*
389	* Adds an array of local fields.
390	*
391	* @date 22/1/19
392	* @since 5.7.10
393	*
394	* @param array $fields An array of un prepared fields.
395	* @return array
396	*/
397	function acf_add_local_fields( $fields = array() ) {
398
399	// Prepare for import (allows parent fields to offer up children).
400	$fields = acf_prepare_fields_for_import( $fields );
401
402	// Add each field.
403	foreach ( $fields as $field ) {
404	acf_add_local_field( $field, true );
405	}
406	}
407
408	/**
409	* acf_get_local_fields
410	*
411	* Returns all local fields for the given parent.
412	*
413	* @date 22/1/19
414	* @since 5.7.10
415	*
416	* @param string $parent The parent key.
417	* @return array
418	*/
419	function acf_get_local_fields( $parent = '' ) {
420
421	// Return children
422	if ( $parent ) {
423	return acf_get_local_store( 'fields' )->query(
424	array(
425	'parent' => $parent,
426	)
427	);
428
429	// Return all.
430	} else {
431	return acf_get_local_store( 'fields' )->get();
432	}
433	}
434
435	/**
436	* acf_have_local_fields
437	*
438	* Returns true if local fields exist.
439	*
440	* @date 22/1/19
441	* @since 5.7.10
442	*
443	* @param string $parent The parent key.
444	* @return bool
445	*/
446	function acf_have_local_fields( $parent = '' ) {
447	return acf_get_local_fields( $parent ) ? true : false;
448	}
449
450	/**
451	* acf_count_local_fields
452	*
453	* Returns the number of local fields for the given parent.
454	*
455	* @date 22/1/19
456	* @since 5.7.10
457	*
458	* @param string $parent The parent key.
459	* @return int
460	*/
461	function acf_count_local_fields( $parent = '' ) {
462	return count( acf_get_local_fields( $parent ) );
463	}
464
465	/**
466	* acf_add_local_field
467	*
468	* Adds a local field.
469	*
470	* @date 22/1/19
471	* @since 5.7.10
472	*
473	* @param array $field The field array.
474	* @param bool $prepared Whether or not the field has already been prepared for import.
475	* @return void
476	*/
477	function acf_add_local_field( $field, $prepared = false ) {
478
479	// Apply default properties needed for import.
480	$field = wp_parse_args(
481	$field,
482	array(
483	'key' => '',
484	'name' => '',
485	'type' => '',
486	'parent' => '',
487	)
488	);
489
490	// Generate key if only name is provided.
491	if ( ! $field['key'] ) {
492	$field['key'] = 'field_' . $field['name'];
493	}
494
495	// If called directly, allow sub fields to be correctly prepared.
496	if ( ! $prepared ) {
497	return acf_add_local_fields( array( $field ) );
498	}
499
500	// Extract attributes.
501	$key = $field['key'];
502	$name = $field['name'];
503
504	// Allow sub field to be added multipel times to different parents.
505	$store = acf_get_local_store( 'fields' );
506	if ( $store->is( $key ) ) {
507	$old_key = _acf_generate_local_key( $store->get( $key ) );
508	$new_key = _acf_generate_local_key( $field );
509	if ( $old_key !== $new_key ) {
510	$key = $new_key;
511	}
512	}
513
514	// Add field.
515	$store->set( $key, $field )->alias( $key, $name );
516	}
517
518	/**
519	* _acf_generate_local_key
520	*
521	* Generates a unique key based on the field's parent.
522	*
523	* @date 22/1/19
524	* @since 5.7.10
525	*
526	* @param string $key The field key.
527	* @return bool
528	*/
529	function _acf_generate_local_key( $field ) {
530	return "{$field['key']}:{$field['parent']}";
531	}
532
533	/**
534	* acf_remove_local_field
535	*
536	* Removes a field for the given key.
537	*
538	* @date 22/1/19
539	* @since 5.7.10
540	*
541	* @param string $key The field key.
542	* @return bool
543	*/
544	function acf_remove_local_field( $key = '' ) {
545	return acf_get_local_store( 'fields' )->remove( $key );
546	}
547
548	/**
549	* acf_is_local_field
550	*
551	* Returns true if a field exists for the given key or name.
552	*
553	* @date 22/1/19
554	* @since 5.7.10
555	*
556	* @param string $key The field group key.
557	* @return bool
558	*/
559	function acf_is_local_field( $key = '' ) {
560	return acf_get_local_store( 'fields' )->has( $key );
561	}
562
563	/**
564	* acf_is_local_field_key
565	*
566	* Returns true if a field exists for the given key.
567	*
568	* @date 22/1/19
569	* @since 5.7.10
570	*
571	* @param string $key The field group key.
572	* @return bool
573	*/
574	function acf_is_local_field_key( $key = '' ) {
575	return acf_get_local_store( 'fields' )->is( $key );
576	}
577
578	/**
579	* acf_get_local_field
580	*
581	* Returns a field for the given key.
582	*
583	* @date 22/1/19
584	* @since 5.7.10
585	*
586	* @param string $key The field group key.
587	* @return (array\|null)
588	*/
589	function acf_get_local_field( $key = '' ) {
590	return acf_get_local_store( 'fields' )->get( $key );
591	}
592
593	/**
594	* _acf_apply_get_local_field_groups
595	*
596	* Appends local field groups to the provided array.
597	*
598	* @date 23/1/19
599	* @since 5.7.10
600	*
601	* @param array $field_groups An array of field groups.
602	* @return array
603	*/
604	function _acf_apply_get_local_field_groups( $groups = array() ) {
605	return _acf_apply_get_local_internal_posts( $groups, 'acf-field-group' );
606	}
607
608	/**
609	* Appends local ACF internal post types to the provided array.
610	*
611	* @since 6.1
612	*
613	* @param array $posts An array of ACF posts.
614	* @param string $post_type The ACF internal post type being loaded.
615	* @return array
616	*/
617	function _acf_apply_get_local_internal_posts( $posts = array(), $post_type = 'acf-field-group' ) {
618	// Get local posts.
619	$local_posts = acf_get_local_internal_posts( $post_type );
620
621	if ( ! $local_posts ) {
622	return $posts;
623	}
624
625	// Generate map of "index" => "key" data.
626	$map = wp_list_pluck( $posts, 'key' );
627
628	// Loop over local posts and update/append local.
629	foreach ( $local_posts as $post ) {
630	$i = array_search( $post['key'], $map, true );
631	if ( $i !== false ) {
632	unset( $post['ID'] );
633	$posts[ $i ] = array_merge( $posts[ $i ], $post );
634	} else {
635	$posts[] = acf_get_internal_post_type( $post['key'], $post_type );
636	}
637	}
638
639	// Sort list via menu_order and title.
640	return wp_list_sort(
641	$posts,
642	array(
643	'menu_order' => 'ASC',
644	'title' => 'ASC',
645	)
646	);
647	}
648	add_filter( 'acf/load_field_groups', '_acf_apply_get_local_internal_posts', 20, 2 );
649	add_filter( 'acf/load_post_types', '_acf_apply_get_local_internal_posts', 20, 2 );
650	add_filter( 'acf/load_taxonomies', '_acf_apply_get_local_internal_posts', 20, 2 );
651
652	/**
653	* _acf_apply_is_local_field_key
654	*
655	* Returns true if is a local key.
656	*
657	* @date 23/1/19
658	* @since 5.7.10
659	*
660	* @param bool $bool The result.
661	* @param string $id The identifier.
662	* @return bool
663	*/
664	function _acf_apply_is_local_field_key( $bool, $id ) {
665	return acf_is_local_field_key( $id );
666	}
667
668	// Hook into filter.
669	add_filter( 'acf/is_field_key', '_acf_apply_is_local_field_key', 20, 2 );
670
671	/**
672	* _acf_apply_is_local_field_group_key
673	*
674	* Returns true if is a local key.
675	*
676	* @date 23/1/19
677	* @since 5.7.10
678	*
679	* @param bool $bool The result.
680	* @param string $id The identifier.
681	* @return bool
682	*/
683	function _acf_apply_is_local_field_group_key( $bool, $id ) {
684	return acf_is_local_field_group_key( $id );
685	}
686
687	/**
688	* Returns true if is a local key.
689	*
690	* @since 6.1
691	*
692	* @param bool $bool The result.
693	* @param string $id The identifier.
694	* @param string $post_type The post type.
695	* @return bool
696	*/
697	function _acf_apply_is_local_internal_post_type_key( $bool, $id, $post_type = 'acf-field-group' ) {
698	return acf_is_local_internal_post_type_key( $id, $post_type );
699	}
700
701	// Hook into filter.
702	add_filter( 'acf/is_field_group_key', '_acf_apply_is_local_internal_post_type_key', 20, 3 );
703	add_filter( 'acf/is_post_type_key', '_acf_apply_is_local_internal_post_type_key', 20, 3 );
704	add_filter( 'acf/is_taxonomy_key', '_acf_apply_is_local_internal_post_type_key', 20, 3 );
705
706	/**
707	* _acf_do_prepare_local_fields
708	*
709	* Local fields that are added too early will not be correctly prepared by the field type class.
710	*
711	* @date 23/1/19
712	* @since 5.7.10
713	*
714	* @param void
715	* @return void
716	*/
717	function _acf_do_prepare_local_fields() {
718
719	// Get fields.
720	$fields = acf_get_local_fields();
721
722	// If fields have been registered early, re-add to correctly prepare them.
723	if ( $fields ) {
724	acf_add_local_fields( $fields );
725	}
726	}
727
728	// Hook into action.
729	add_action( 'acf/include_fields', '_acf_do_prepare_local_fields', 0, 1 );
730
731
732