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

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

593 lines 11.6 KB

Raw Download Zip

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