Field groups#

A field group is the root of an ACF Chef definition.

Create one with FieldGroup::make() and give it a name:

use AcfChef\FieldGroup;

$group = FieldGroup::make('hero');

make() returns an instance of the class it was called on. For a FieldGroup subclass, HeroGroup::make() returns a HeroGroup, not the base class.

Names and titles#

The constructor takes one argument: the group name.

ACF Chef derives the initial title from that name by replacing underscores and hyphens with spaces, then applying title case:

$group = FieldGroup::make('hero_banner');

$group->toArray()['title'];
// Hero Banner

To change the derived title, configure the group:

$group->config([
    'title' => 'Homepage Hero',
]);

ACF Chef uses a string value as the output title. If title is present but is not a string, ACF Chef ignores it and derives the title from the group name again.

Configure the group#

Group-level config() accepts an array of ACF field-group settings:

$group = FieldGroup::make('hero_banner');

$group->config([
    'title' => 'Hero Banner',
    'style' => 'seamless',
    'position' => 'acf_after_title',
    'menu_order' => 3,
    'hide_on_screen' => ['the_content'],
]);

There is no closure form of group-level config().

Deferred field configuration receives an extended-acf field object at compile time. A field group has no corresponding extended-acf object, so there is nothing for a group configuration closure to receive.

Before you add fields or locations, the example compiles to this array:

[
    'title' => 'Hero Banner',
    'key' => 'group_hero_banner',
    'fields' => [],
    'location' => [],
    'style' => 'seamless',
    'position' => 'acf_after_title',
    'menu_order' => 3,
    'hide_on_screen' => ['the_content'],
]

The first four keys always appear in this order:

1. title
2. key
3. fields
4. location

The remaining group settings follow in the order you configured them.

location is always present. For a group with no location rules, its value is an empty array.

Special group settings#

ACF Chef handles four configuration keys separately when it converts the group to an array.

title#

A string overrides the title derived from the group name.

$group->config([
    'title' => 'Primary Hero',
]);

ACF Chef ignores a non-string value and uses the derived title instead.

key#

An explicit group key overrides the key produced by the active key strategy:

$group->config([
    'key' => 'group_legacy_hero',
]);

The output contains the value exactly as supplied.

Use an explicit key when the group must keep an identifier already used by an existing site or another registration tool.

location#

You can pass a complete ACF location array to config():

$group->config([
    'location' => [
        [
            [
                'param' => 'post_type',
                'operator' => '==',
                'value' => 'page',
            ],
        ],
    ],
]);

That array is used only when you have not called location() or andLocation() on the group.

Once you add a fluent location rule, ACF Chef uses the fluent rules for the output location value. A location array in config() cannot replace them.

See Locations and registration for the fluent location API.

fields#

A fields value in group configuration is discarded:

$group->config([
    'fields' => [
        // Ignored.
    ],
]);

Fields come from the ACF Chef node tree. If group configuration also supplied fields, that array could disagree with the declared tree.

The title, key, location and fields entries are removed from the remaining settings before they are appended to the output, so none of them can appear twice.

Group configuration has no shorthands#

Configuration shorthands work on field cursors. A shorthand registered with Chef::shorthand() expands when used on a field:

Chef::shorthand('half', fn (): array => ['wrapper' => ['width' => 50]]);

$group->text('title')->config([
    'half' => true,
]);

The same key at group level is not expanded:

$group->config([
    'half' => true,
]);

That produces a literal top-level half key in the field-group array, which ACF does not define as a field-group setting.

Use ACF’s group settings: style, position, menu_order, hide_on_screen and the rest.

Override the key strategy for one group#

Set a key strategy directly on a field group when only that definition should use it:

use AcfChef\FieldGroup;
use AcfChef\KeyStrategy\HashedKeys;

$group = FieldGroup::make('hero');
$group->keyStrategy(new HashedKeys());

The override applies to the group key and every field and layout key compiled within the group.

Other groups continue to use the global strategy configured through Chef::keyStrategy().

See Field keys for the built-in strategies, custom strategies and compatibility rules.

Subclass a field group#

You can define a field group in a subclass:

use AcfChef\FieldGroup;

final class HeroGroup extends FieldGroup
{
    public function __construct(string $name)
    {
        parent::__construct($name);

        $this
            ->text('title')
            ->textarea('summary')
            ->location('post_type', 'page');
    }
}

Create an instance of the subclass:

$hero = HeroGroup::make('hero');

$array = $hero->toArray();

The constructor must keep the base signature:

public function __construct(string $name)

FieldGroup uses a consistent constructor, and make() passes only the name. Changing the required parameters makes the inherited factory unusable.

Call parent::__construct($name) before declaring fields. The parent constructor sets up the group name, derived title and field tree that the public builder methods use.

All FieldGroup state is private. A subclass builds and configures itself through the same public methods as any other definition; it cannot access the node tree or settings directly.

Chef::group() always creates a plain FieldGroup. It does not infer or instantiate your subclass. Use HeroGroup::make() or construct the subclass yourself when the definition belongs to a custom class.

Typehint the contract#

Code that accepts a field group without requiring the concrete implementation should typehint:

AcfChef\Contracts\FieldGroup

The contract defines the supported field-group methods and lets the caller accept the base class or one of your subclasses.