Documentation

update_field()

Description

This function is used to update a field value.

Parameters

update_field($field_key, $value, $post_id)
  • $field_key: the key or name of the field to be retrieved. eg “field_4fc5ab37e1819lol” or “heading” (required)
  • $value: the new value to save (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

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 

/*
*  update a text field on the current post (using the field_name)
*/

$field_name = "text_field";
$value = "some new string";
update_field( $field_name, $value );

/*
*  update a text field on the current post (using the field_key)
*/

$field_key = "field_5039a99716d1d";
$value = "some new string";
update_field( $field_key, $value );

/*
*  update a checkbox field on another post
*/

$field_key = "field_5039a9973jsd1d";
$value = array("red", "blue", "yellow");
$post_id = 123;
update_field( $field_key, $value, $post_id );

/*
*  add a repeater row on a taxonomy!!!
*/

$field_key = "repeater_field";
$post_id = "event_123";
$value = get_field($field_key, $post_id);
$value[] = array("sub_field_1" => "Foo", "sub_field_2" => "Bar");
update_field( $field_key, $value, $post_id );

/*
*  add a flexible content row
*  - each row needs an extra key "acf_fc_layout" holding the name of the layout (string)
*/

$field_key = "flexible_field";
$value = get_field($field_key);
$value[] = array("sub_field_1" => "Foo1", "sub_field_2" => "Bar1", "acf_fc_layout" => "layout_1_name");
$value[] = array("sub_field_x" => "Foo2", "sub_field_y" => "Bar2", "acf_fc_layout" => "layout_2_name");
update_field( $field_key, $value, $post_id );
/*
*  Create a new post and add field data
*  - if the post does not already contain a "reference" to the field object, you must use the field_key instead of the field_name.
*/

// Create post object
$my_post = array(
 'post_title' => 'My post',
 'post_content' => 'This is my post.',
 'post_status' => 'publish',
 'post_author' => 1
);

// Insert the post into the database
$post_id = wp_insert_post( $my_post );

// Add field value
update_field( "field_5039a99716d1d", "I am a value!", $post_id );

/*
*  $post_id examples
*/

$post_id = null; // current post
$post_id = 1;
$post_id = "option";
$post_id = "options"; // same as above
$post_id = "category_2"; // save to a specific category
$post_id = "event_3"; // save to a specific taxonomy (this tax is called "event")
$post_id = "user_1"; // save to user (user id = 1)

?>