Synthetic Industry

Troubleshooting guide · updated 2026-10-11

Advanced Custom Fields: keep field groups in files, not just the dashboard, and print values safely

Where ACF field definitions can live, how Local JSON syncs, what get_field returns and why location rules do not control the front end.

Three places a field definition can live

Advanced Custom Fields lets you define fields in the dashboard, where they are stored in the database; in a JSON file that ACF writes and reads, called Local JSON; or in PHP code. The dashboard is quick but ties the definition to one copy of the site, so a staging copy and a live site can quietly differ. The other two put the definition in files you can keep in version control and deploy with the rest of your code. For a site that has a staging copy, files are the safer home, because "the fields are different on live" is one of the hardest faults to describe.

  • Dashboard only: fastest to start, easiest to lose.
  • Local JSON: dashboard editing with files as the record.
  • PHP: not editable in the dashboard, fully controlled by code.

How Local JSON works

The ACF documentation explains that when the folder named acf-json exists in the theme, ACF writes a file each time a field group, post type, taxonomy or options page is saved. Field groups are saved this way in any recent version; saving post types and taxonomies to files needs ACF 6.1 or later, the version whose release post says the JSON sync tools were extended to include them; and options pages need ACF PRO 6.2 or later, whose release post says options page definitions are supported as ACF JSON files. An item becomes available for sync when it is missing from the database or its file records a newer modified time than the database, and a tab appears in the list so you choose what to import. The page lists the benefits as version control over field settings and fewer database queries per page. It also notes requirements: the folder must exist and be writable. If you do not want the JSON files listed publicly, the page says to add an empty index.php file to the folder, which prevents directory listing. Filters such as acf/settings/save_json and acf/settings/load_json let a plugin keep the files, which matters when the content type lives in a plugin and not in the theme.

  • Create the folder before saving anything, or nothing is written.
  • If the files live in a plugin, add its folder to the load path.

Registering in PHP

The registration page shows acf_add_local_field_group() called inside the acf/init action, which it recommends because ACF is then guaranteed to be loaded. Every group and field needs a unique key, and if two share a key the later one overrides the earlier. Groups registered this way will not be visible or editable on the Edit Field Groups screen, which is the point: the code is the single source. The page notes that one setting, save_other_choice, works only for database-stored fields. ACF can generate the PHP for an existing group from its import and export page, which is a practical way to move from dashboard to code.

  • Choose keys that will never be reused.
  • Do not mix a group in the dashboard and the same group in code.

Reading and printing values

get_field takes the field name or key, an optional post ID that defaults to the current post, a flag that controls formatting and, since version 6.2.6, an option to return an escaped value. Other locations are addressed with prefixes: a user ID with a user prefix, a term with its taxonomy name, and the word option for an options page. The documentation advises escaping a value before printing it, for example with wp_kses_post, and it does not say what a missing field returns, so a template must handle an empty value without printing empty wrappers or errors. Location rules, by contrast, only decide which admin screens show a field group; they do not decide what the front end can read.

  • Test every template with a filled, a partly filled and an empty entry.
  • Never print a stored value without escaping it for its context.

Fit, limits and how the paid job relates

The content-type job stores field definitions as files in the plugin and proves on a fresh staging copy that they load without a manual import. It does not buy an ACF licence, import your existing entries or add visitor submission forms. Which field types are available can depend on your ACF edition and licence, so the field list is checked against the edition before a price is given. Because saving post types and taxonomies as files needs ACF 6.1 or later, and options pages need ACF PRO 6.2 or later, say which version you run. The job has a published test price of GBP 650, is an untested proposal and payment follows the agreed checks.

  • Send your field list with types and an example value for each.
  • Say which ACF edition and version you hold, and take a full backup before the site holder installs anything.

Sources and limits

  • ACF documentation: local JSON Checked 2026-10-11.
    • By default ACF writes a JSON file to an acf-json folder you create in the theme each time a field group, post type, taxonomy or options page is saved; an item is offered for sync when it is missing from the database or its JSON modified value is newer.
    • The feature gives version control over field settings and reduces database queries; the folder must exist and be writable, and the acf/settings/save_json and load_json filters change the paths. Adding an empty index.php file to the acf-json folder prevents directory listing of the JSON files.
    • The page (last updated 28 September 2023) names ACF 6.2 only for the modifiers of the save_json filter.
  • ACF: ACF 6.1 release post Checked 2026-10-11.
    • In ACF 6.1 the JSON sync, export and import tools were updated to include post types and taxonomies registered with ACF, and their PHP code can be exported for sites without ACF active.
  • ACF: ACF 6.2 release post Checked 2026-10-11.
    • ACF 6.2 introduced creating options pages from the plugin admin UI in ACF PRO, and options page definitions are supported as ACF JSON files, with import, export and JSON sync.
  • ACF documentation: register fields via PHP Checked 2026-10-11.
    • Groups can be registered with acf_add_local_field_group(), recommended inside the acf/init action; each group and field key must be unique and a later duplicate overrides the first; code-registered groups are not visible or editable on the Edit Field Groups screen.
  • ACF documentation: get_field() Checked 2026-10-11.
    • get_field($selector, $post_id, $format_value, $escape_html) defaults the post ID to the current post, uses prefixes such as user_2 or category_3 and "option" for other locations, and the page advises escaping values before output; the escape_html argument was added in 6.2.6.
  • ACF documentation: custom location rules Checked 2026-10-11.
    • Location rules determine which field groups appear on which admin screen.