fields.php — Advanced Custom Fields (ACF®) 6.8.7

advanced-custom-fields / includes / fields.php

advanced-custom-fields / includes Last commit date

fields.php

466 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	if ( ! defined( 'ABSPATH' ) ) {
13	exit; // Exit if accessed directly
14	}
15
16	if ( ! class_exists( 'acf_fields' ) ) :
17	class acf_fields {
18
19	/**
20	* Contains an array of field type instances.
21	* @var array
22	*/
23	public $types = array();
24
25	/**
26	* This function will setup the class functionality
27	*
28	* @type function
29	* @date 5/03/2014
30	* @since 5.4.0
31	*
32	* @param n/a
33	* @return n/a
34	*/
35	function __construct() {
36	/* do nothing */
37	}
38
39	/**
40	* This function will register a field type instance based on a class name or instance.
41	* It will return the instance for further use.
42	*
43	* @since 5.4.0
44	*
45	* @param mixed $field_class Either a class name (string) or instance of acf_field.
46	* @return acf_field The instance of acf_field.
47	*/
48	public function register_field_type( $field_class ) {
49	// Allow registering an instance.
50	if ( $field_class instanceof acf_field ) {
51	$this->types[ $field_class->name ] = $field_class;
52	return $field_class;
53	}
54
55	// Allow registering a loaded class name.
56	$instance = new $field_class();
57	$this->types[ $instance->name ] = $instance;
58	return $instance;
59	}
60
61	/**
62	* This function will return a field type instance
63	*
64	* @type function
65	* @date 6/07/2016
66	* @since 5.4.0
67	*
68	* @param $name (string)
69	* @return (mixed)
70	*/
71	function get_field_type( $name ) {
72	return isset( $this->types[ $name ] ) ? $this->types[ $name ] : null;
73	}
74
75
76	/**
77	* This function will return true if a field type exists
78	*
79	* @type function
80	* @date 6/07/2016
81	* @since 5.4.0
82	*
83	* @param $name (string)
84	* @return (mixed)
85	*/
86	function is_field_type( $name ) {
87	return isset( $this->types[ $name ] );
88	}
89
90
91	/**
92	* This function will store a basic array of info about the field type
93	* to later be overriden by the above register_field_type function
94	*
95	* @type function
96	* @date 29/5/17
97	* @since 5.6.0
98	*
99	* @param $info (array)
100	* @return n/a
101	*/
102	function register_field_type_info( $info ) {
103
104	// convert to object
105	$instance = (object) $info;
106	$this->types[ $instance->name ] = $instance;
107	}
108
109
110	/**
111	* This function will return an array of all field types
112	*
113	* @type function
114	* @date 6/07/2016
115	* @since 5.4.0
116	*
117	* @param $name (string)
118	* @return (mixed)
119	*/
120	function get_field_types() {
121	return $this->types;
122	}
123	}
124
125
126	// initialize
127	acf()->fields = new acf_fields();
128	endif; // class_exists check
129
130
131	/**
132	* alias of acf()->fields->register_field_type()
133	*
134	* @type function
135	* @date 31/5/17
136	* @since 5.6.0
137	*
138	* @param n/a
139	* @return n/a
140	*/
141	function acf_register_field_type( $class ) {
142	return acf()->fields->register_field_type( $class );
143	}
144
145
146	/**
147	* alias of acf()->fields->register_field_type_info()
148	*
149	* @type function
150	* @date 31/5/17
151	* @since 5.6.0
152	*
153	* @param n/a
154	* @return n/a
155	*/
156	function acf_register_field_type_info( $info ) {
157	return acf()->fields->register_field_type_info( $info );
158	}
159
160
161	/**
162	* alias of acf()->fields->get_field_type()
163	*
164	* @type function
165	* @date 31/5/17
166	* @since 5.6.0
167	*
168	* @param n/a
169	* @return n/a
170	*/
171	function acf_get_field_type( $name ) {
172	return acf()->fields->get_field_type( $name );
173	}
174
175
176	/**
177	* alias of acf()->fields->get_field_types()
178	*
179	* @type function
180	* @date 31/5/17
181	* @since 5.6.0
182	*
183	* @param n/a
184	* @return n/a
185	*/
186	function acf_get_field_types( $args = array() ) {
187
188	// default
189	$args = wp_parse_args(
190	$args,
191	array(
192	'public' => true, // true, false
193	)
194	);
195
196	// get field types
197	$field_types = acf()->fields->get_field_types();
198
199	// filter
200	return wp_filter_object_list( $field_types, $args );
201	}
202
203
204	/**
205	* acf_get_field_types_info
206	*
207	* Returns an array containing information about each field type
208	*
209	* @date 18/6/18
210	* @since 5.6.9
211	*
212	* @param type $var Description. Default.
213	* @return type Description.
214	*/
215	function acf_get_field_types_info( $args = array() ) {
216
217	// vars
218	$data = array();
219	$field_types = acf_get_field_types();
220
221	// loop
222	foreach ( $field_types as $type ) {
223	$data[ $type->name ] = array_filter(
224	array(
225	'label' => $type->label,
226	'name' => $type->name,
227	'description' => $type->description,
228	'category' => $type->category,
229	'public' => $type->public,
230	'doc_url' => $type->doc_url,
231	'tutorial_url' => $type->tutorial_url,
232	'preview_image' => $type->preview_image,
233	'pro' => $type->pro,
234	)
235	);
236	}
237
238	// return
239	return $data;
240	}
241
242
243	/**
244	* alias of acf()->fields->is_field_type()
245	*
246	* @type function
247	* @date 31/5/17
248	* @since 5.6.0
249	*
250	* @param n/a
251	* @return n/a
252	*/
253	function acf_is_field_type( $name = '' ) {
254	return acf()->fields->is_field_type( $name );
255	}
256
257
258	/**
259	* This function will return a field type's property
260	*
261	* @type function
262	* @date 1/10/13
263	* @since 5.0.0
264	*
265	* @param n/a
266	* @return (array)
267	*/
268	function acf_get_field_type_prop( $name = '', $prop = '' ) {
269	$type = acf_get_field_type( $name );
270	return ( $type && isset( $type->$prop ) ) ? $type->$prop : null;
271	}
272
273
274	/**
275	* This function will return the label of a field type
276	*
277	* @type function
278	* @date 1/10/13
279	* @since 5.0.0
280	*
281	* @param n/a
282	* @return (array)
283	*/
284	function acf_get_field_type_label( $name = '' ) {
285	$label = acf_get_field_type_prop( $name, 'label' );
286	return $label ? $label : '<span class="acf-js-tooltip" title="' . __( 'Field type does not exist', 'acf' ) . '">' . __( 'Unknown', 'acf' ) . '</span>';
287	}
288
289	/**
290	* Returns the value of a field type "supports" property.
291	*
292	* @since 6.2.5
293	*
294	* @param string $name The name of the field type.
295	* @param string $prop The name of the supports property.
296	* @param mixed $default The default value if the property is not set.
297	*
298	* @return mixed The value of the supports property which may be false, or $default on failure.
299	*/
300	function acf_field_type_supports( $name = '', $prop = '', $default = false ) {
301	$supports = acf_get_field_type_prop( $name, 'supports' );
302	if ( ! is_array( $supports ) ) {
303	return $default;
304	}
305	return isset( $supports[ $prop ] ) ? $supports[ $prop ] : $default;
306	}
307
308
309	/**
310	*
311	* @deprecated
312	* @see acf_is_field_type()
313	*
314	* @type function
315	* @date 1/10/13
316	* @since 5.0.0
317	*
318	* @param $type (string)
319	* @return (boolean)
320	*/
321	function acf_field_type_exists( $type = '' ) {
322	return acf_is_field_type( $type );
323	}
324
325	/**
326	* Returns an array of localised field categories.
327	*
328	* @since 6.1
329	*
330	* @return array
331	*/
332	function acf_get_field_categories_i18n() {
333
334	$categories_i18n = array(
335	'basic' => __( 'Basic', 'acf' ),
336	'content' => __( 'Content', 'acf' ),
337	'choice' => __( 'Choice', 'acf' ),
338	'relational' => __( 'Relational', 'acf' ),
339	'advanced' => __( 'Advanced', 'acf' ),
340	'layout' => __( 'Layout', 'acf' ),
341	'pro' => __( 'PRO', 'acf' ),
342	);
343
344	return apply_filters( 'acf/localized_field_categories', $categories_i18n );
345	}
346
347
348	/**
349	* Returns an multi-dimentional array of field types "name => label" grouped by category
350	*
351	* @since 5.0.0
352	*
353	* @return array
354	*/
355	function acf_get_grouped_field_types() {
356
357	// vars
358	$types = acf_get_field_types();
359	$groups = array();
360	$l10n = acf_get_field_categories_i18n();
361
362	// loop
363	foreach ( $types as $type ) {
364
365	// translate
366	$cat = $type->category;
367	$cat = isset( $l10n[ $cat ] ) ? $l10n[ $cat ] : $cat;
368
369	// append
370	$groups[ $cat ][ $type->name ] = $type->label;
371	}
372
373	// filter
374	$groups = apply_filters( 'acf/get_field_types', $groups );
375
376	// return
377	return $groups;
378	}
379
380	/**
381	* Returns an array of tabs for a field type.
382	* We combine a list of default tabs with filtered tabs.
383	* I.E. Default tabs should be static and should not be changed by the
384	* filtered tabs.
385	*
386	* @since 6.1
387	*
388	* @return array Key/value array of the default settings tabs for field type settings.
389	*/
390	function acf_get_combined_field_type_settings_tabs() {
391	$default_field_type_settings_tabs = array(
392	'general' => __( 'General', 'acf' ),
393	'validation' => __( 'Validation', 'acf' ),
394	'presentation' => __( 'Presentation', 'acf' ),
395	'conditional_logic' => __( 'Conditional Logic', 'acf' ),
396	'advanced' => __( 'Advanced', 'acf' ),
397	);
398
399	$field_type_settings_tabs = (array) apply_filters( 'acf/field_group/additional_field_settings_tabs', array() );
400
401	// remove any default tab values from filter tabs.
402	foreach ( $field_type_settings_tabs as $key => $tab ) {
403	if ( isset( $default_field_type_settings_tabs[ $key ] ) ) {
404	unset( $field_type_settings_tabs[ $key ] );
405	}
406	}
407
408	$combined_field_type_settings_tabs = array_merge( $default_field_type_settings_tabs, $field_type_settings_tabs );
409
410	return $combined_field_type_settings_tabs;
411	}
412
413
414
415	/**
416	* Get the PRO only fields and their core metadata.
417	*
418	* @since 6.1
419	*
420	* @return array An array of all the pro field types and their field type selection required meta data.
421	*/
422	function acf_get_pro_field_types() {
423	return array(
424	'clone' => array(
425	'name' => 'clone',
426	'label' => _x( 'Clone', 'noun', 'acf' ),
427	'doc_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/clone/', 'docs', 'field-type-selection' ),
428	'preview_image' => acf_get_url() . '/assets/images/field-type-previews/field-preview-clone.png',
429	'description' => __( 'This allows you to select and display existing fields. It does not duplicate any fields in the database, but loads and displays the selected fields at run-time. The Clone field can either replace itself with the selected fields or display the selected fields as a group of subfields.', 'acf' ),
430	'tutorial_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/how-to-use-the-clone-field/', 'docs', 'field-type-selection' ),
431	'category' => 'layout',
432	'pro' => true,
433	),
434	'flexible_content' => array(
435	'name' => 'flexible_content',
436	'label' => __( 'Flexible Content', 'acf' ),
437	'doc_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/flexible-content/', 'docs', 'field-type-selection' ),
438	'preview_image' => acf_get_url() . '/assets/images/field-type-previews/field-preview-flexible-content.png',
439	'description' => __( 'This provides a simple, structured, layout-based editor. The Flexible Content field allows you to define, create and manage content with total control by using layouts and subfields to design the available blocks.', 'acf' ),
440	'tutorial_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/building-layouts-with-the-flexible-content-field-in-a-theme/', 'docs', 'field-type-selection' ),
441	'category' => 'layout',
442	'pro' => true,
443	),
444	'gallery' => array(
445	'name' => 'gallery',
446	'label' => __( 'Gallery', 'acf' ),
447	'doc_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/gallery/', 'docs', 'field-type-selection' ),
448	'preview_image' => acf_get_url() . '/assets/images/field-type-previews/field-preview-gallery.png',
449	'description' => __( 'This provides an interactive interface for managing a collection of attachments. Most settings are similar to the Image field type. Additional settings allow you to specify where new attachments are added in the gallery and the minimum/maximum number of attachments allowed.', 'acf' ),
450	'tutorial_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/how-to-use-the-gallery-field/', 'docs', 'field-type-selection' ),
451	'category' => 'content',
452	'pro' => true,
453	),
454	'repeater' => array(
455	'name' => 'repeater',
456	'label' => __( 'Repeater', 'acf' ),
457	'doc_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/repeater/', 'docs', 'field-type-selection' ),
458	'preview_image' => acf_get_url() . '/assets/images/field-type-previews/field-preview-repeater.png',
459	'description' => __( 'This provides a solution for repeating content such as slides, team members, and call-to-action tiles, by acting as a parent to a set of subfields which can be repeated again and again.', 'acf' ),
460	'tutorial_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/repeater/how-to-use-the-repeater-field/', 'docs', 'field-type-selection' ),
461	'category' => 'layout',
462	'pro' => true,
463	),
464	);
465	}
466