local-fields.php — Advanced Custom Fields (ACF®) 6.8.8

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

advanced-custom-fields / includes Last commit date

local-fields.php

744 lines

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