Description

This function will return a field object as seen in the field group edit screen. The returned array will look something like this:

Array
(
    [key] => field_4fea85f5320da
    [label] => Text Field
    [name] => text_field
    [type] => text
    [instructions] => 
    [required] => 0
    [default_value] => 
    [formatting] => html
    [order_no] => 0
    [value] => Use the option parameter to toggle loading the value
)

Parameters

get_field_object($field_key, $post_id, $options)

$field_key

The key or name of the field to be retrieved. eg “field_4fc5ab37e1819lol” or ”heading” (required)

$post_id

Specific post ID where your value was entered. Defaults to current post ID (not required). This can also be options / taxonomies / users / etc

$options

An array holding options. These are:

  • load_value – true|false. Whether or not to load the value for the field. Defaults to true

field_key vs field_name

Each value stored in the database consists of 2 rows of data. These are:

  1. value – the value, saved with a meta_key of “$fieldName”
  2. reference – the field_key, used to find the field object, saved with a meta_key of “_$fieldName”

This is shown in the following screenshot from a WP database using ACF

This reference value is important!

When editing a post in the wp admin, the reference is automatically added. It is then used by many of the API functions to correctly format the value.

For example, the save value of an image field is the attachment ID, however you can set the return value to “URL” or “Image Object”. The reference is used to load the field object and format the value.

So when can I use $field_name?

If the reference for a value already exists, you can use the $field_name as the first parameter in the update_field function. ACF will lookup the field reference / field object from that field name.

So when can I use $field_key?

You can and should use the $field_key 100% of the time.

The problem with using $field_name is that if the reference does not already exist, ACF will not be able to find the field object and will not be able to save the value. This situation would occur if you had used code to insert a post.

Also, it is more efficient to use the field_key as the first parameter in the update_field function as it bypasses the reference look up.

Finding the field key

When editing a field group, click on the screen options tab at the top of the page. You should see an option to toggle the display of the field key (it is hidden by default to save space). The following image demonstrates this.

 Usage

<?php 
 
/*
*  Get a field object and display it with it's value
*/
 
$field_name = "text_field";
$field = get_field_object($field_name);
 
echo $field['label'] . ': ' . $field['value'];
 
/*
*  Get a field object and display it with it's value (using the field key and the value fron another post)
*/
 
$field_key = "field_5039a99716d1d";
$post_id = 123;
$field = get_field_object($field_key, $post_id);
 
echo $field['label'] . ': ' . $field['value'];
 
/*
*  Get a field object and create a select form element
*/
 
$field_key = "field_5039a99716d1d";
$field = get_field_object($field_key);
 
if( $field )
{
	echo '<select name="' . $field['key'] . '">';
		foreach( $field['choices'] as $k => $v )
		{
			echo '<option value="' . $k . '">' . $v . '</option>';
		}
	echo '</select>';
}
 
?>