acf-pro-options-pages

Builds and reviews ACF PRO options pages and their global value storage. Covers acf_add_options_page registration, capabilities, menu and location rules, default and custom post_id prefixes in wp_opti

SKILL.md

GitHub

ACF PRO options pages

Options Pages are an ACF PRO feature. They provide an admin screen and field location; their values live in wp_options, not in a special ACF table. Default options pages share the same options storage target, so page separation in the menu does not isolate duplicate field names.

Register a page with explicit policy

add_action( 'acf/init', static function (): void {
    if ( ! function_exists( 'acf_add_options_page' ) ) {
        return;
    }

    acf_add_options_page( array(
        'page_title'    => __( 'Brand settings', 'acme-brand' ),
        'menu_title'    => __( 'Brand settings', 'acme-brand' ),
        'menu_slug'     => 'acme-brand-settings',
        'capability'    => 'manage_options',
        'redirect'      => false,
        'post_id'       => 'option_acme_brand',
        'autoload'      => false,
        'update_button' => __( 'Save brand settings', 'acme-brand' ),
    ) );
} );

Then attach a field group with an Options Page location rule whose value matches the menu slug. Keep registration and field definitions in the same owning plugin so the page cannot exist without its schema.

edit_posts is the ACF default capability. That is often too broad for global configuration. Choose a capability from the feature's authorization model and recheck it on any custom save, REST, AJAX, or CLI path.

Understand option names

With the default post_id of options, a field named support_phone produces:

options_support_phone   = <raw value>
_options_support_phone  = field_acme_support_phone

With post_id => 'option_acme_brand', the same field produces:

option_acme_brand_support_phone   = <raw value>
_option_acme_brand_support_phone  = field_acme_support_phone

The underscore option is ACF's field-key reference. Keep it aligned with the value option. Do not call get_option( 'support_phone' ) and assume it is the ACF value; use get_field() with the same storage target or intentionally address the fully prefixed raw option.

Read and render from the same target

$storage = 'option_acme_brand';

$phone = get_field( 'acme_support_phone', $storage );
if ( is_string( $phone ) && '' !== $phone ) {
    printf(
        '<a href="%s">%s</a>',
        esc_url( 'tel:' . preg_replace( '/[^0-9+]/', '', $phone ) ),
        esc_html( $phone )
    );
}

The common 'option' and 'options' aliases target default options storage. They do not target a custom post_id. Centralize a custom storage identifier in one constant or method and reuse it for field definitions, reads, writes, tests, and migrations.

Prevent page collisions

Two pages using default storage and the same field name read and overwrite the same option. Choose one of these models:

  • globally unique field names across all default options pages;
  • a distinct custom post_id per independent page/tenant/brand;
  • intentionally shared fields, documented as shared state.

Changing post_id later is a data migration. Copy both the raw value and its reference by reading through the old ACF target and writing through update_field( $field_key, $value, $new_target ); then verify and remove the old options according to the rollback plan.

Control autoload and size

ACF PRO 6.8.10 defaults an options page's autoload setting to false. Enabling it can improve access to a small set of values used on nearly every request, but it also adds those option rows to WordPress's autoloaded option set.

  • Keep large Repeaters, Flexible Content, galleries, and rarely used settings non-autoloaded.
  • Measure total autoloaded option size before and after enabling it.
  • Avoid storing caches, logs, queues, or frequently changing operational state in an ACF options page.
  • Do not assume ACF's formatted-value cache replaces WordPress option/object cache design.

Free/PRO degradation

acf_add_options_page() and the Options Pages UI require ACF PRO. A plugin whose core behavior depends on the page should show one clear administrator notice and disable only that feature when the function is absent. Do not create a lookalike page that writes incompatible option names under ACF Free.

Verification

  1. Log in with an allowed administrator and a role that must be denied.
  2. Save a scalar, an empty value, and each complex value used by the page.
  3. Inspect the expected prefixed option and underscore reference.
  4. Render on a frontend request without an admin global screen.
  5. Confirm a second options page cannot collide unintentionally.
  6. Measure autoload growth and object-cache behavior where relevant.
  7. Exercise import/CLI writes with the exact custom storage target.

Cross-references

  • acf-field-group-development for options-page location rules and schema ownership.
  • acf-value-storage-frontend for raw/formatted values and safe output.
  • acf-pro-complex-fields when global settings contain Repeaters or Flexible Content.

References