class-acf-field-image.php — Advanced Custom Fields (ACF®) 6.8.8

advanced-custom-fields / includes / fields / class-acf-field-image.php

advanced-custom-fields / includes / fields Last commit date

class-acf-field-image.php

583 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 ( ! class_exists( 'acf_field_image' ) ) :
13
14	class acf_field_image extends acf_field {
15
16
17	/**
18	* This function will setup the field type data
19	*
20	* @type function
21	* @date 5/03/2014
22	* @since 5.0.0
23	*
24	* @param n/a
25	* @return n/a
26	*/
27	function initialize() {
28
29	// vars
30	$this->name = 'image';
31	$this->label = __( 'Image', 'acf' );
32	$this->category = 'content';
33	$this->description = __( 'Uses the native WordPress media picker to upload, or choose images.', 'acf' );
34	$this->preview_image = acf_get_url() . '/assets/images/field-type-previews/field-preview-image.png';
35	$this->doc_url = acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/image/', 'docs', 'field-type-selection' );
36	$this->defaults = array(
37	'return_format' => 'array',
38	'preview_size' => 'medium',
39	'library' => 'all',
40	'min_width' => 0,
41	'min_height' => 0,
42	'min_size' => 0,
43	'max_width' => 0,
44	'max_height' => 0,
45	'max_size' => 0,
46	'mime_types' => '',
47	);
48
49	// filters
50	add_filter( 'get_media_item_args', array( $this, 'get_media_item_args' ) );
51	add_filter( 'acf/validate_attachment/type=image', 'acf_validate_is_image_attachment', 10, 5 );
52	}
53
54
55	/**
56	* description
57	*
58	* @type function
59	* @date 16/12/2015
60	* @since 5.3.2
61	*
62	* @param $post_id (int)
63	* @return $post_id (int)
64	*/
65	function input_admin_enqueue_scripts() {
66
67	// localize
68	acf_localize_text(
69	array(
70	'Select Image' => __( 'Select Image', 'acf' ),
71	'Edit Image' => __( 'Edit Image', 'acf' ),
72	'Update Image' => __( 'Update Image', 'acf' ),
73	'All images' => __( 'All images', 'acf' ),
74	)
75	);
76	}
77
78	/**
79	* Renders the field HTML.
80	*
81	* @date 23/01/13
82	* @since 3.6.0
83	*
84	* @param array $field The field settings.
85	* @return void
86	*/
87	function render_field( $field ) {
88	$uploader = acf_get_setting( 'uploader' );
89
90	// Enqueue uploader scripts
91	if ( $uploader === 'wp' ) {
92	acf_enqueue_uploader();
93	}
94
95	// Elements and attributes.
96	$value = '';
97	$div_attrs = array(
98	'class' => 'acf-image-uploader',
99	'data-preview_size' => $field['preview_size'],
100	'data-library' => $field['library'],
101	'data-mime_types' => $field['mime_types'],
102	'data-uploader' => $uploader,
103	);
104	$img_attrs = array(
105	'src' => '',
106	'alt' => '',
107	'data-name' => 'image',
108	);
109
110	// Detect value.
111	if ( $field['value'] && is_numeric( $field['value'] ) ) {
112	$image = wp_get_attachment_image_src( $field['value'], $field['preview_size'] );
113	if ( $image ) {
114	$value = $field['value'];
115	$img_attrs['src'] = $image[0];
116	$img_attrs['alt'] = get_post_meta( $field['value'], '_wp_attachment_image_alt', true );
117	$div_attrs['class'] .= ' has-value';
118	}
119	}
120
121	// Add "preview size" max width and height style.
122	// Apply max-width to wrap, and max-height to img for max compatibility with field widths.
123	$size = acf_get_image_size( $field['preview_size'] );
124	$size_w = $size['width'] ? $size['width'] . 'px' : '100%';
125	$size_h = $size['height'] ? $size['height'] . 'px' : '100%';
126	$img_attrs['style'] = sprintf( 'max-height: %s;', $size_h );
127
128	// Render HTML.
129	?>
130	<div <?php echo acf_esc_attrs( $div_attrs ); ?>>
131	<?php
132	acf_hidden_input(
133	array(
134	'name' => $field['name'],
135	'value' => $value,
136	)
137	);
138	?>
139	<div class="show-if-value image-wrap" style="max-width: <?php echo esc_attr( $size_w ); ?>" tabindex="0" role="button" aria-label="<?php esc_attr_e( 'Selected image. Press tab to access image options.', 'acf' ); ?>">
140	<img <?php echo acf_esc_attrs( $img_attrs ); ?> />
141	<div class="acf-actions -hover">
142	<?php if ( $uploader !== 'basic' ) : ?>
143	<a class="acf-icon -pencil dark" data-name="edit" href="#" title="<?php esc_attr_e( 'Edit', 'acf' ); ?>" aria-label="<?php esc_attr_e( 'Edit image', 'acf' ); ?>"></a>
144	<?php endif; ?>
145	<a class="acf-icon -cancel dark" data-name="remove" href="#" title="<?php esc_attr_e( 'Remove', 'acf' ); ?>" aria-label="<?php esc_attr_e( 'Remove image', 'acf' ); ?>"></a>
146	</div>
147	</div>
148	<div class="hide-if-value">
149	<?php if ( $uploader === 'basic' ) : ?>
150	<?php if ( $field['value'] && ! is_numeric( $field['value'] ) ) : ?>
151	<div class="acf-error-message"><p><?php echo acf_esc_html( $field['value'] ); ?></p></div>
152	<?php endif; ?>
153	<label class="acf-basic-uploader">
154	<?php
155	$args = array(
156	'name' => $field['name'],
157	'id' => $field['id'],
158	'key' => $field['key'],
159	);
160
161	if ( ! empty( $field['mime_types'] ) ) {
162	$extensions = str_replace( array( ' ', '.' ), '', $field['mime_types'] );
163	$extensions = array_filter( explode( ',', $extensions ) );
164	$accept_extensions = array();
165
166	foreach ( $extensions as $extension ) {
167	$accept_extensions[] = '.' . $extension;
168	}
169
170	$args['accept'] = implode( ',', $accept_extensions );
171	} else {
172	$args['accept'] = 'image/*';
173	}
174
175	acf_file_input( $args );
176	?>
177	</label>
178	<?php else : ?>
179	<p><?php esc_html_e( 'No image selected', 'acf' ); ?> <a data-name="add" class="acf-button button" href="#"><?php esc_html_e( 'Add Image', 'acf' ); ?></a></p>
180	<?php endif; ?>
181	</div>
182	</div>
183	<?php
184	}
185
186
187	/**
188	* Create extra options for your field. This is rendered when editing a field.
189	* The value of $field['name'] can be used (like bellow) to save extra data to the $field
190	*
191	* @type action
192	* @since 3.6
193	* @date 23/01/13
194	*
195	* @param $field - an array holding all the field's data
196	*/
197	function render_field_settings( $field ) {
198	acf_render_field_setting(
199	$field,
200	array(
201	'label' => __( 'Return Format', 'acf' ),
202	'instructions' => '',
203	'type' => 'radio',
204	'name' => 'return_format',
205	'layout' => 'horizontal',
206	'choices' => array(
207	'array' => __( 'Image Array', 'acf' ),
208	'url' => __( 'Image URL', 'acf' ),
209	'id' => __( 'Image ID', 'acf' ),
210	),
211	)
212	);
213
214	acf_render_field_setting(
215	$field,
216	array(
217	'label' => __( 'Library', 'acf' ),
218	'instructions' => __( 'Limit the media library choice', 'acf' ),
219	'type' => 'radio',
220	'name' => 'library',
221	'layout' => 'horizontal',
222	'choices' => array(
223	'all' => __( 'All', 'acf' ),
224	'uploadedTo' => __( 'Uploaded to post', 'acf' ),
225	),
226	)
227	);
228	}
229
230	/**
231	* Renders the field settings used in the "Validation" tab.
232	*
233	* @since 6.0
234	*
235	* @param array $field The field settings array.
236	* @return void
237	*/
238	function render_field_validation_settings( $field ) {
239	// Clear numeric settings.
240	$clear = array(
241	'min_width',
242	'min_height',
243	'min_size',
244	'max_width',
245	'max_height',
246	'max_size',
247	);
248
249	foreach ( $clear as $k ) {
250	if ( empty( $field[ $k ] ) ) {
251	$field[ $k ] = '';
252	}
253	}
254
255	acf_render_field_setting(
256	$field,
257	array(
258	'label' => __( 'Minimum', 'acf' ),
259	'hint' => __( 'Restrict which images can be uploaded', 'acf' ),
260	'type' => 'text',
261	'name' => 'min_width',
262	'prepend' => __( 'Width', 'acf' ),
263	'append' => 'px',
264	)
265	);
266
267	acf_render_field_setting(
268	$field,
269	array(
270	'label' => '',
271	'type' => 'text',
272	'name' => 'min_height',
273	'prepend' => __( 'Height', 'acf' ),
274	'append' => 'px',
275	'_append' => 'min_width',
276	)
277	);
278
279	acf_render_field_setting(
280	$field,
281	array(
282	'label' => '',
283	'type' => 'text',
284	'name' => 'min_size',
285	'prepend' => __( 'File size', 'acf' ),
286	'append' => 'MB',
287	'_append' => 'min_width',
288	)
289	);
290
291	acf_render_field_setting(
292	$field,
293	array(
294	'label' => __( 'Maximum', 'acf' ),
295	'hint' => __( 'Restrict which images can be uploaded', 'acf' ),
296	'type' => 'text',
297	'name' => 'max_width',
298	'prepend' => __( 'Width', 'acf' ),
299	'append' => 'px',
300	)
301	);
302
303	acf_render_field_setting(
304	$field,
305	array(
306	'label' => '',
307	'type' => 'text',
308	'name' => 'max_height',
309	'prepend' => __( 'Height', 'acf' ),
310	'append' => 'px',
311	'_append' => 'max_width',
312	)
313	);
314
315	acf_render_field_setting(
316	$field,
317	array(
318	'label' => '',
319	'type' => 'text',
320	'name' => 'max_size',
321	'prepend' => __( 'File size', 'acf' ),
322	'append' => 'MB',
323	'_append' => 'max_width',
324	)
325	);
326
327	acf_render_field_setting(
328	$field,
329	array(
330	'label' => __( 'Allowed File Types', 'acf' ),
331	'instructions' => __( 'Comma separated list. Leave blank for all types', 'acf' ),
332	'type' => 'text',
333	'name' => 'mime_types',
334	)
335	);
336	}
337
338	/**
339	* Renders the field settings used in the "Presentation" tab.
340	*
341	* @since 6.0
342	*
343	* @param array $field The field settings array.
344	* @return void
345	*/
346	function render_field_presentation_settings( $field ) {
347	acf_render_field_setting(
348	$field,
349	array(
350	'label' => __( 'Preview Size', 'acf' ),
351	'instructions' => '',
352	'type' => 'select',
353	'name' => 'preview_size',
354	'choices' => acf_get_image_sizes(),
355	)
356	);
357	}
358
359	/**
360	* This filter is appied to the $value after it is loaded from the db and before it is returned to the template
361	*
362	* @type filter
363	* @since 3.6
364	* @date 23/01/13
365	*
366	* @param $value (mixed) the value which was loaded from the database
367	* @param $post_id (mixed) the post_id from which the value was loaded
368	* @param $field (array) the field array holding all the field options
369	*
370	* @return $value (mixed) the modified value
371	*/
372	function format_value( $value, $post_id, $field ) {
373
374	// bail early if no value
375	if ( empty( $value ) ) {
376	return false;
377	}
378
379	// bail early if not numeric (error message)
380	if ( ! is_numeric( $value ) ) {
381	return false;
382	}
383
384	// convert to int
385	$value = intval( $value );
386
387	// format
388	if ( $field['return_format'] == 'url' ) {
389	return wp_get_attachment_url( $value );
390	} elseif ( $field['return_format'] == 'array' ) {
391	return acf_get_attachment( $value );
392	}
393
394	// return
395	return $value;
396	}
397
398
399	/**
400	* description
401	*
402	* @type function
403	* @date 27/01/13
404	* @since 3.6.0
405	*
406	* @param $vars (array)
407	* @return $vars
408	*/
409	function get_media_item_args( $vars ) {
410
411	$vars['send'] = true;
412	return( $vars );
413	}
414
415
416	/**
417	* This filter is appied to the $value before it is updated in the db
418	*
419	* @type filter
420	* @since 3.6
421	* @date 23/01/13
422	*
423	* @param $value - the value which will be saved in the database
424	* @param $post_id - the post_id of which the value will be saved
425	* @param $field - the field array holding all the field options
426	*
427	* @return $value - the modified value
428	*/
429	function update_value( $value, $post_id, $field ) {
430
431	return acf_get_field_type( 'file' )->update_value( $value, $post_id, $field );
432	}
433
434
435	/**
436	* This function will validate a basic file input
437	*
438	* @type function
439	* @since 5.0.0
440	*
441	* @param boolean $valid The current validity status.
442	* @param mixed $value The field value.
443	* @param array $field The field array.
444	* @param string $input The name of the input in the POST object.
445	* @return boolean The validity status.
446	*/
447	public function validate_value( $valid, $value, $field, $input ) {
448	if ( $valid !== true ) {
449	return $valid;
450	}
451
452	if ( empty( $value ) ) {
453	return $valid;
454	}
455
456	if ( is_numeric( $value ) && ! wp_attachment_is_image( $value ) ) {
457	return __( 'File must be a valid image.', 'acf' );
458	}
459
460	return acf_get_field_type( 'file' )->validate_value( $valid, $value, $field, $input );
461	}
462
463	/**
464	* Additional validation for the image field when submitted via REST.
465	*
466	* @param boolean $valid The current validity booleean
467	* @param integer $value The value of the field
468	* @param array $field The field array
469	* @return boolean\|WP_Error
470	*/
471	public function validate_rest_value( $valid, $value, $field ) {
472	return acf_get_field_type( 'file' )->validate_rest_value( $valid, $value, $field );
473	}
474
475	/**
476	* Return the schema array for the REST API.
477	*
478	* @param array $field The field array
479	* @return array
480	*/
481	public function get_rest_schema( array $field ) {
482	return acf_get_field_type( 'file' )->get_rest_schema( $field );
483	}
484
485	/**
486	* Apply basic formatting to prepare the value for default REST output.
487	*
488	* @param mixed $value The field value
489	* @param string\|integer $post_id The post ID
490	* @param array $field The field array
491	* @return mixed
492	*/
493	public function format_value_for_rest( $value, $post_id, array $field ) {
494	return acf_format_numerics( $value );
495	}
496
497	/**
498	* Formats the field value for JSON-LD output.
499	*
500	* @since 6.8.0
501	*
502	* @param mixed $value The value of the field.
503	* @param integer\|string $post_id The ID of the post.
504	* @param array $field The field array.
505	* @return mixed
506	*/
507	public function format_value_for_jsonld( $value, $post_id, $field ) {
508	if ( empty( $value ) ) {
509	return null;
510	}
511
512	// Get output format with fallback.
513	$output_format = $field['schema_output_format'] ?? '';
514	if ( empty( $output_format ) ) {
515	$property = $field['schema_property'] ?? '';
516	$output_format = \ACF\AI\GEO\Schema::get_default_output_format( $this->name, $property );
517	}
518
519	// Get the attachment ID.
520	$attachment_id = is_array( $value ) ? ( $value['ID'] ?? 0 ) : (int) $value;
521	if ( ! $attachment_id ) {
522	return null;
523	}
524
525	$url = wp_get_attachment_url( $attachment_id );
526	if ( ! $url ) {
527	return null;
528	}
529
530	// URL format - just return the URL string.
531	if ( 'URL' === $output_format ) {
532	return $url;
533	}
534
535	// ImageObject format - return structured object.
536	$image_object = array(
537	'@type' => 'ImageObject',
538	'url' => $url,
539	);
540
541	// Add dimensions if available.
542	$metadata = wp_get_attachment_metadata( $attachment_id );
543	if ( ! empty( $metadata['width'] ) ) {
544	$image_object['width'] = (int) $metadata['width'];
545	}
546	if ( ! empty( $metadata['height'] ) ) {
547	$image_object['height'] = (int) $metadata['height'];
548	}
549
550	// Add caption/alt text if available.
551	$alt = get_post_meta( $attachment_id, '_wp_attachment_image_alt', true );
552	if ( $alt ) {
553	$image_object['caption'] = $alt;
554	}
555
556	// Add name from attachment title.
557	$attachment = get_post( $attachment_id );
558	if ( $attachment && $attachment->post_title ) {
559	$image_object['name'] = $attachment->post_title;
560	}
561
562	return $image_object;
563	}
564
565	/**
566	* Returns an array of JSON-LD Property output types that are supported by this field type.
567	*
568	* @since 6.8
569	*
570	* @return string[]
571	*/
572	public function get_jsonld_output_types(): array {
573	return array( 'ImageObject', 'URL' );
574	}
575	}
576
577
578	// initialize
579	acf_register_field_type( 'acf_field_image' );
580	endif; // class_exists check
581
582	?>
583