Getting started#

Install ACF Chef, define a field group in a PHP file that WordPress loads, and add a location rule to the group.

You can use any bootstrap file. You must register the finished group with ACF yourself: ACF Chef declares field groups but does not add hooks.

Requirements#

ACF Chef requires:

  • PHP 8.4 or newer
  • vinkla/extended-acf ^15.0
  • Advanced Custom Fields installed and active at run time

The free ACF plugin supports most of the field types available in ACF Chef, including the group field.

ACF Pro is required for:

  • Repeaters
  • Flexible content
  • Layouts inside flexible content
  • Galleries

The example on this page uses only fields available in the free plugin.

Install the package#

Install ACF Chef with Composer:

composer require leaseleads/acf-chef

Composer also installs the extended-acf dependency.

Declare a field group#

Put the definition in any PHP file that runs during a normal WordPress request.

That could be:

  • functions.php
  • A file required from functions.php
  • A plugin’s main file
  • A file required by a plugin
  • A Composer-autoloaded class that your theme or plugin invokes

The package does not require a specific bootstrap filename.

use AcfChef\Chef;

add_action('acf/init', function () {
    Chef::group('hero', function ($group) {
        $group
            ->text('title')
            ->textarea('summary')
            ->location('post_type', 'page');
    })->register();
});

ACF Chef derives the title Hero from the group name hero.

The fields are named title and summary. ACF Chef derives their labels as Title and Summary.

The location rule tells ACF to show the group when the current post type is page.

Open a page editing screen in WordPress to see the field group.

Registration is yours#

Chef::group() builds and returns the field-group object. It does not add hooks, compile the group, or register it with ACF.

register() compiles the group and registers it with ACF by calling acf_add_local_field_group(). It returns the array it registered.

$hero = Chef::group('hero', function ($group) {
    $group
        ->text('title')
        ->location('post_type', 'page');
});

// Nothing has reached ACF yet.

$registered = $hero->register();

Call register() on acf/init, when ACF is ready for local field groups:

add_action('acf/init', function () use ($hero) {
    $hero->register();
});

The example above declares and registers the group in the same callback, which is the shortest form.

Keeping registration separate allows two uses.

You can modify a group after declaring it and before registering it. For example, a child theme can adjust a definition provided by a parent theme. See Finding and editing fields.

You can also declare a definition without WordPress. Unit tests and command-line tools can build a group and read toArray() without ACF, WordPress or hooks.

Register extensions before compilation#

Custom field types, cursor macros and configuration shorthands are read during declaration. Calling a verb with no registered class raises UnknownFieldType, and config() expands shorthands when it is called.

Load the file that registers a verb before declaring a group that uses it. Registering a shorthand too late does not raise an error: if it is registered after the config() call that uses it, the key remains unchanged in the field array.

Register extensions at load time:

  • At the top level of a plugin or theme bootstrap file
  • In a plugins_loaded callback

Register them before acf/init.

If one acf/init callback registers an extension and another compiles a group, their order matters. The group may compile before the first callback registers the custom field type, macro or shorthand.

The rule is:

Declare groups where they are easiest to read. Register field types, macros and shorthands during application loading, before acf/init registers anything.

The extension pages cover the individual registration APIs:

Next steps#

Read How it works to understand what ACF Chef stores during declaration and what it creates during compilation.

The remaining pages build on that distinction.