ACF get_field() Function: Detailed Explanation

Advanced Custom Fields (ACF) is one of the leading meta field plugins. The get_field() function is one of the most important parts of the ACF API. Using this function, you can retrieve the value of any field created with ACF, regardless of the field type. It serves as a universal entry point, facilitating access to field values.

In fact, it's the function you're going to use most often. The ACF plugin doesn't have a separate PHP namespace, so the function is available globally.

It's important to note that the function is available only after the plugins_loaded action, and in order to work properly, you should call it only after the acf/init hook.

The get_field function and the the_field function are both provided by ACF. While they function identically in terms of retrieving field values, they differ in how they handle the response. get_field returns the value, whereas the_field prints it directly.

Thus, echo get_field() is equivalent to using the_field(). Both functions accept the same arguments, making navigation between them seamless.

Note: Our preference is to use the get_field function in all cases. The the_field function lacks utility for non-plain field types such as user or post. For instance, if used with the user data, it will print the string 'array' rather than the HTML markup of an avatar or related content as might be expected.

Below, we'll cover all the essential aspects of using the function.

But before we delve into the review of the get_field function, it's worth mentioning alternative approaches. While using the ACF API, particularly the get_field function, is the most straightforward and obvious way to get ACF field values, there are other options as well.

The Advanced Views plugin introduces Smart templates with built-in post queries and automated template generation. The plugin supports all the most renowned meta field plugins, such as ACF, MetaBox, and Pods, out of the box.

ACF is a renowned plugin, and many page builders offer their own integrations with ACF. If you use one, check the documentation of your page builder to see if there is an add-on available.

For retrieving values of plain fields, like text, you can employ ACF shortcodes. So if you need to insert your field value into some piece of text, such as the date, it will work well. But keep in mind that it doesn't work in more complex cases.

Let's start with the get_field function by reviewing its arguments:

get_field($selector, [$post_id = false], [$format_value = true], [$escape_html = false]);

1. $selector (string) (Required): The field name or field key.
2. $post_id (mixed) (Optional): The post ID where the value is saved. Defaults to false, which will use the current post.
3. $format_value (bool) (Optional): Determines whether to apply formatting logic. Defaults to true.
4. $escape_html (bool) (Optional, since 6.2.6): Returns an escaped HTML safe version of the field value. Requires $format_value to be true. Defaults to false

As you can see, the single required argument is the field selector, which can be either the field name or the field key. Each field has a unique ID in the format "field_uniqueid", with the second part being the unique ID response.

However, the field key isn't displayed in the plugin's UI and isn't self-explanatory. We always recommend using the field name and ensuring that each field has a proper and unique name to avoid conflicts, especially if placed on the same page.

The second argument defines the source from which the field should be loaded. By default, it's the current object (post, page, user, taxonomy, etc.).

See the Supported sources chapter for details.

The $format_value argument controls whether the meta field value should be processed by ACF before returning. By default, it's set to true, meaning ACF checks the 'Return Format' setting of the specific field and returns the corresponding value.

For example, an ACF User field stores the user ID (int) in the meta field inside the database but returns a WP_User object by default. If you change this flag, get_field will return the raw ID (int) without any extra processing.

By default, the get_field function's response isn't escaped, as it may contain HTML. However, in cases where HTML is not expected, we should either mark it as true or manually escape the value. Refer to the Values Escaping chapter for more details.

ACF offers a wide variety of field types, ranging from simple ones like Text and Number to object-related types such as Post and User, as well as group types like Gallery or Repeater. Despite the diverse value formats associated with each field type, the universal usage of the get_field() function simplifies our workflow.

However, a couple of challenges may complicate our tasks:

Ideally, get_field() would return a distinct object for each field type with predefined fields. This would allow developers to inspect object properties directly within their IDE instead of referring to documentation.

While this setting enhances flexibility, it introduces a variety of response formats, akin to a small zoo. In addition to knowing the field type, developers must also be mindful of the Return Format setting specific to each field.

Although fields typically have default settings, caution is necessary to ensure they are not altered. This challenge can be addressed with a handy lifehack: passing true to the unformatted argument returns the 'pure' value, ensuring consistent formatting regardless of the specific field settings.

Refer to the 'Non-formatted' section of this article for further details.

Tip: You can overcome these challenges by using the Advanced Views plugin. It introduces Smart templates with automatic markup generation, allowing you to handle diverse field types effortlessly while maintaining control over the markup.

Below, we provide a detailed breakdown of return formats for every field type. You can bookmark this page and use it as a cheat sheet.

Note: In the table, the 'optional' multiple items support indicates the presence of an option field setting. Enabling this setting allows users to choose several items within the same field. This adjustment changes the get_field response to an array of items, regardless of the actual count, even if it's just one.

The layout group consists of two types of fields: visual-only and grouping. Visual-only fields, such as Tab, do not hold any value themselves. On the other hand, grouping fields do not directly affect the value but instead wrap it.

For more detailed information, check the specific guide about Group, Repeater, Flexible Content, and Clone fields.

ACF allows attaching fields to multiple different objects: posts/pages, users, taxonomies, comments, and even menus. While posts, along with pages and any custom post types, are stored in the same table, others are stored separately.

ACF automates the process and handles fetching/saving/loading values to the appropriate location. To request field values from a location different from the posts table, developers simply need to define the source ($post_id) argument with a specific prefix.

The following prefixed are supported:

• options for fields on the options page.
• user_{id} for fields on user profiles.
• category_{id} for category fields.
• {taxonomy}_{id} for fields associated with custom taxonomies.

Keep in mind that the value must remain the default false if you're retrieving fields from ACF Blocks:

$current_object_value = get_field('field_name');
$option_value = get_field('field_name',  'options');
$user_profile_value = get_field('field_name',  'user_1');
$category_value = get_field('field_name', 'category_1');
$taxonomy_value = get_field('field_name', 'genres_1');
$block_value = get_field('field_name');

Tip: While you may leave it empty, we recommend always passing a variable with the ID. This makes your code more flexible, allowing you to repurpose it easily. For example, you could turn a single template into an AJAX template that returns information based on the passed ID.

Another important thing to note about the get_field function is its default value: NULL.

So, if a field isn't present in the object, the function will return NULL. While this might seem straightforward, it can be a bit trickier in practice. Let's consider a practical example:

1. You've just added a new text field.
2. You request this field for an already existing post.
3. You get NULL.

This scenario seems clear. However, what happens if we open that post and press the save button? If the field has no value, ACF takes the value of the 'default value' setting of this field. When you press save, it saves the default value to the database, or an empty string if the default value isn't set.

So, since the first saving, our field will return an empty string ('') instead of NULL. All the posts made after the field was attached to the screen will also have the empty string saved in the database and returned.

It's important to keep this in mind when making WP_Query. To check if the field is empty, you should not only use 'equal to empty string' comparison but also add 'OR not exists'. To simplify querying by Meta fields, and even Taxonomies, you can use the Pro version of the Advanced Views plugin, which supports ACF fields.

For security reasons, WordPress requires developers to escape all values coming from the database before inserting them into the markup to prevent XSS attacks. While WordPress handles this automatically for built-in functions, developers should manually escape other values using functions such as esc_html() or esc_attr().

For example, the following code is not safe:

<img src="<?php echo get_field('image_field_name'); ?>" >

This is because the value retrieved from get_field() could contain the <script> tag, which could be executed on the page. To mitigate this risk, you should either set the $escape_html argument of get_field() to true, or use the esc_attr() function like so:

<img src="<?php echo esc_attr(get_field('image_field_name')); ?>" >

To avoid constantly remembering to escape values, you can utilize a template engine like Twig, which automatically escapes all values by default. For instance, the Advanced Views plugin employs Twig and supports all ACF field types out of the box.

As we described earlier, the return format of a specific field depends not only on the field type but also on the Return Format setting of that field. Let's consider the Image field as an example. Depending on the settings, the response data can be image data as an array, URL as a string, or attachment ID as an integer.

For newly added fields, you might remember the setting of the specific field. But what if you took over a project from another developer, or returned to development after a long pause? Checking the return format of every field can be time-consuming.

However, there's a not-obvious trick. It's used in the Advanced Views plugin integration with ACF, and we'll share it with you. So the trick is to use the $format_value argument as false. This allows you to get the clear meta value regardless of the Return Format setting.

So when requesting an image field without formatting, you can be sure that you'll get an image ID and nothing else.

However, nothing is perfect, and for some fields, this method has a drawback. For example, for the Select field, you'll only get the chosen option without the label. In such cases, you'll need to call ACF's API to get the list of options and retrieve the label.

All of this complexity is already handled in the Smart templates of the Advanced Views plugin, so you can use the plugin and forget about these hassles.

The ACF get_field() function is the most direct method for retrieving field values. It distinguishes itself from the the_field function only by its response behavior: get_field returns the value, while the_field prints it.

Besides using the ACF API, there are alternative methods such as using Smart templates from the Advanced Views plugin, ACF integration of your page builder, or ACF shortcodes.

The get_field function serves as a universal entrance door, allowing you to request field values from any object within any available location, such as post, user, or taxonomy. This universal approach inherently determines its flexible return format: the function's return format depends on both the field type and its return format setting.

When working with the get_field function, keep in mind that the returned value isn't escaped by default. So, for cases when you don't expect HTML, don't forget to escape the value properly or pass true to the $escape_html argument of the function.

Happy ACF development!