get_field() │ ACF 3.6

Gets the value of the specified field or option.

This function can be used to get the value of any field from any location.

Remember that every field type returns different data types: string, integer, array, and so on.

No Hooks.

Returns

mixed. The field value.

Usage

get_field( $selector, $post_id, $format_value );

$selector(string) (required)

The field key or name (name or key).

$post_id(integer/object)

The post for which the specified field is saved.
Default: the current post

$format_value(true/false)

Allows formatting to be enabled or disabled. When formatting is disabled, the value is returned as it is in the database.
Default: true

Examples

#1 Get the field value of the current post

This example shows how to get the value of the text_field field of the current post.

$value = get_field( 'text_field' );

#2 Get the field value of a specific post

This example shows how to get the value of the text_field field from post ID 123.

$value = get_field( 'text_field', 123 );

#3 Whether a field has a value

This example shows how to check whether the specified field has a value.

$value = get_field( 'text_field' );

if( $value ) {
	echo $value;
}
else {
	echo 'empty';
}

#4 Get one field value from different objects

This example shows the values that can be passed in $post_id to get a field from a post, user, term, or option.

$post_id = false;        // current post
$post_id = 1;            // post ID = 1
$post_id = "user_2";     // user ID = 2
$post_id = "category_3"; // category term ID = 3
$post_id = "event_4";    // event (custom taxonomy) term ID = 4
$post_id = "option";     // options page
$post_id = "options";    // same as above

$value = get_field( 'my_field', $post_id );

#5 Get a field value without formatting

In this example, image is an image field that normally returns an image object. However, by passing false as the third parameter, the value is not formatted and is returned from the database as is.

Note that the second parameter is false to specify the current post.

$image = get_field( 'image', false, false );

function get_field( $selector, $post_id = false, $format_value = true, $escape_html = false ) {

	// filter post_id
	$post_id = acf_get_valid_post_id( $post_id );

	// get field
	$field = acf_maybe_get_field( $selector, $post_id );

	// create dummy field
	$dummy_field = false;
	if ( ! $field ) {
		$field = acf_get_valid_field(
			array(
				'name' => $selector,
				'key'  => '',
				'type' => '',
			)
		);

		// prevent formatting, flag as dummy in case $escape_html is true.
		$format_value = false;
		$dummy_field  = true;
	}

	// get value for field
	$value = acf_get_value( $post_id, $field );

	// escape html is only compatible when formatting the value too
	if ( ! $dummy_field && ! $format_value && $escape_html ) {
		_doing_it_wrong( __FUNCTION__, __( 'Returning an escaped HTML value is only possible when format_value is also true. The field value has not been returned for security.', 'acf' ), '6.2.6' ); //phpcs:ignore -- escape not required.
		return false;
	}

	// format value
	if ( $format_value ) {
		if ( $escape_html ) {
			// return the escaped HTML version if requested.
			if ( acf_field_type_supports( $field['type'], 'escaping_html' ) ) {
				$value = acf_format_value( $value, $post_id, $field, true );
			} else {
				$new_value = acf_format_value( $value, $post_id, $field );
				if ( is_array( $new_value ) ) {
					$value = map_deep( $new_value, 'acf_esc_html' );
				} else {
					$value = acf_esc_html( $new_value );
				}
			}
		} else {
			// get value for field
			$value = acf_format_value( $value, $post_id, $field );
		}
	}

	// If we've built a dummy text field, we won't format the value, but they may still request it escaped. Use `acf_esc_html`
	if ( $dummy_field && $escape_html ) {
		if ( is_array( $value ) ) {
			$value = map_deep( $value, 'acf_esc_html' );
		} else {
			$value = acf_esc_html( $value );
		}
	}

	// return
	return $value;
}