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

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

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