acf-value-storage-frontend
Implements and diagnoses Advanced Custom Fields value storage, programmatic writes, database inspection, and frontend rendering. Covers the value row plus hidden field-key reference, post/user/term/co
SKILL.mdacf/acf-value-storage-frontend/SKILL.md
GitHubACF value storage and frontend rendering
ACF normally stores a field as a pair:
acme_event_start = 2026-10-20 18:00:00
_acme_event_start = field_acme_event_start
The visible row contains the raw value. The underscore-prefixed row maps the
field name to its stable field key, which lets ACF find the field type and apply
the correct load/format behavior. A raw meta value without a valid reference can
look present in SQL while get_field() returns an unformatted value, no value,
or a value governed by a different field definition.
Storage locations
ACF $post_id |
WordPress storage | Example value/reference keys |
|---|---|---|
123 |
wp_postmeta |
field_name, _field_name |
user_12 |
wp_usermeta |
field_name, _field_name |
term_34 or category_34 |
wp_termmeta |
field_name, _field_name |
comment_56 |
wp_commentmeta |
field_name, _field_name |
option or options |
wp_options |
options_field_name, _options_field_name |
custom option target such as option_brand_a |
wp_options |
option_brand_a_field_name, _option_brand_a_field_name |
Numeric IDs mean posts. Pass the explicit prefixed target for every other object; do not rely on the current global object in imports, cron, REST, or CLI code.
Read with the shape you intend to render
$post_id = get_the_ID();
// Plain text: format through ACF, then escape for this HTML context.
$eyebrow = get_field( 'acme_eyebrow', $post_id );
if ( is_string( $eyebrow ) && '' !== $eyebrow ) {
echo '<p class="eyebrow">' . esc_html( $eyebrow ) . '</p>';
}
// WYSIWYG: ask ACF 6.2.6+ for its field-aware safe HTML value.
$body = get_field( 'acme_body', $post_id, true, true );
if ( is_string( $body ) && '' !== $body ) {
echo $body; // ACF returned the escaped/formatted value.
}
// Image configured to return an attachment ID.
$image_id = (int) get_field( 'acme_image', $post_id );
if ( $image_id ) {
echo wp_get_attachment_image( $image_id, 'large' );
}
get_field( $selector, $post_id, $format_value, $escape_html ) has two distinct
switches:
- formatted
trueapplies the field type's return format and format filters; - escaped
trueasks ACF for an HTML-safe formatted value and requires formatted to also betrue; - formatted
falsereturns the raw database shape after WordPress unserializes metadata. It does not mean "safe to output."
Prefer get_field() when ACF owns the schema. Use get_post_meta() or the
matching core metadata API when code intentionally needs the raw storage value
or the value is ordinary WordPress meta that ACF does not own.
Write through ACF
Use the field key for a first write so ACF can create both the value and reference rows. Later writes by name work once the reference exists, but key-based imports remain clearer and survive ambiguous field names.
$saved = update_field(
'field_acme_event_start',
'2026-10-20 18:00:00',
$post_id
);
if ( false === $saved ) {
// False can also mean that the stored value was unchanged; verify the value
// before treating this as an operational failure.
}
Do not create only _field_name, copy a field key from another field, or bulk
write complex ACF values with $wpdb. update_field() runs the field type's
acf/update_value pipeline, writes the reference, removes obsolete nested rows
where supported, and clears ACF's request cache.
Raw and formatted shapes
The field settings decide the public shape. Code must not infer it from the label or field name.
| Field configuration | Typical raw storage | Typical formatted value |
|---|---|---|
| Text, number, URL, date/time | scalar string | string or field-specific scalar |
| True/False | 0 or 1 |
boolean-like value |
| Image/File | attachment ID | ID, URL, or array according to Return Format |
| Link | serialized array | array containing URL, title, and target |
| Select/Checkbox | scalar or serialized array | value(s), or value/label arrays when configured |
| Relationship/Post Object | ID or serialized ID array | ID(s) or object(s) according to Return Format |
| Group | flattened child meta rows | associative array of formatted child values |
| Repeater | parent row count plus flattened child rows | array of formatted rows; PRO |
| Flexible Content | layout-name array plus flattened child rows | layout rows; PRO |
WordPress serializes arrays placed in a single metadata row. ACF complex fields may instead use several flattened rows; inspect the field type before writing a migration or query.
Query the raw value, render the formatted value
WP_Query and metadata SQL see stored values, not get_field() return formats.
An image field configured to return an array still stores an attachment ID. A
Relationship field returning WP_Post objects still stores IDs. Build queries
against the verified raw shape, then render through ACF.
Serialized multi-value fields are a weak database index. A quoted-ID LIKE
query can avoid matching 12 inside 312, but it remains unindexed and should
not become the primary model for large or frequently queried relationships.
Use taxonomies, dedicated relationship tables, or a purpose-built post model
when querying is central to the feature.
Diagnose a missing or wrong value
- Resolve the exact
$post_idtarget and field selector. - Confirm the field definition is registered before the read.
- Inspect both the value row and
_field_namereference. - Resolve that reference to the expected field key and type.
- Compare
get_field( ..., false )raw output with formatted output. - Check
acf/load_value,acf/format_value, and type/name/key variations. - If code mixed raw metadata writes and ACF reads in one request, repeat through
update_field()or explicitly account for ACF's value cache.
Runtime characterization
The bundled WP-CLI smoke plugin
registers a disposable schema and verifies post, user, term, custom-options,
Relationship, Group, escaped reads, and a custom field type under Free and PRO;
when PRO is active it also verifies Repeater storage. It is pinned to ACF 6.8.10
and deletes its fixtures in a finally block.
Run it only on an authorized disposable installation. Define
ACF_SKILLS_SMOKE_ALLOW_WRITES as true before WordPress loads, activate the
example plugin, and run:
wp acf-skills-smoke run --confirm-disposable
Deactivate and remove the example afterward. Keep environment names, server paths, database prefixes, and run output outside the public skill collection.
Cross-references
acf-field-group-developmentfor stable field definitions and deployment.acf-relational-fieldsfor ID/object return formats and reverse relations.acf-pro-complex-fieldsfor flattened Repeater and Flexible Content storage.
References
- Official
get_field()documentation. - Official
update_field()documentation. - Official HTML escaping guide.
- Official field-function behavior since ACF 5.11.
- Verified ACF 6.8.10 source paths:
includes/api/api-template.phpincludes/acf-value-functions.phpincludes/acf-meta-functions.phpincludes/acf-wp-functions.phpsrc/Meta/MetaLocation.phpsrc/Meta/Post.phpsrc/Meta/User.phpsrc/Meta/Term.phpsrc/Meta/Option.php