acf-builder turns WordPress field groups into fluent PHP

ACF field groups as code, not as admin clicks

Advanced Custom Fields Pro is normally configured by clicking in the WordPress admin, and the result is a set of field groups stored in the database. acf-builder exists for projects that want those groups to live in source control instead.

The library is described as a tool to create configuration arrays for Advanced Custom Fields Pro using the builder pattern and a fluent API. The point is that the output of the builder is the array shape ACF itself expects, and you register it with ACF's own PHP entry point, acf_add_local_field_group, on the acf/init action. The README points to the ACF documentation on registering fields via PHP for the details of that mechanism.

The stated benefits are brevity, correctness, reuse and consistency. Writing the raw array by hand is verbose and easy to get wrong, and a group of fields that appears in three places has to be written three times unless you factor it out. The library's answer is a fluent chain that returns the builder, so a field group is a sequence of calls rather than a nested literal.

The package is stoutlogic/acf-builder on Packagist, published under the GPL-2.0 licence.

The chain that produces a field group

The README's simple example is a banner field group with three fields and a location rule. The builder is created with a name, fields are added with typed methods, and the location is set with a comparison:

$banner = new StoutLogic\AcfBuilder\FieldsBuilder('banner');
$banner
    ->addText('title')
    ->addWysiwyg('content')
    ->addImage('background_image')
    ->setLocation('post_type', '==', 'page')
        ->or('post_type', '==', 'post');

add_action('acf/init', function() use ($banner) {
   acf_add_local_field_group($banner->build());
});

The method names map to field types, so addText, addWysiwyg and addImage are self describing, and the setLocation call takes a parameter, an operator and a value. The or method adds another condition group, and the indentation in the example is what shows that calling or continues the same chain.

What build returns is a plain array with the same keys ACF uses: a group key derived from the name, a title, a fields array where each field has a key, a name, a label and a type, and a location array holding the rule groups. Nothing about the array is magic, which means you can still inspect or adjust it before handing it over.

Reuse is the argument that justifies the library

The reuse example is the one that shows why you would add a dependency. A background group with a tab, an image field, a true false field with instructions and a colour picker is defined once, and then inserted into two other groups:

$background = new FieldsBuilder('background');
$background
    ->addTab('Background')
    ->addImage('background_image')
    ->addTrueFalse('fixed')
        ->instructions("Check to add a parallax effect where the background image doesn't move when scrolling")
    ->addColorPicker('background_color');

and then composed into a banner and into a section that contains a repeater with its own nested copy of the same group:

$section = new FieldsBuilder('section');
$section
    ->addTab('Content')
    ->addText('section_title')
    ->addRepeater('columns', ['min' => 1, 'layout' => 'block'])
        ->addTab('Content')
        ->addText('title')
        ->addWysiwyg('content')
        ->addFields($background)
        ->endRepeater()
    ->addFields($background)
    ->setLocation('post_type', '==', 'page');

The addFields method inserts an existing builder into the current one, and endRepeater closes the repeater scope so the following calls attach to the outer group again. The stated payoff is that if you want to add a light or dark field for the text colour based on the background, you add it in one place and it appears everywhere.

The secondary effect is a consistent admin interface, since the same field definitions render identically in every place they are used. For a project with a dozen field groups that share a handful of components, that consistency is worth more than the individual keystrokes saved.

Installing with Composer, and the PHP version caveat

Installation is a single Composer command:

composer require stoutlogic/acf-builder

If the project does not use Composer, the README notes that you can require the autoload.php file directly, and that file is present at the repository root.

The requirements section is the part worth reading twice, because it says something specific about support. PHP 5.4 through 7.2 is supported, but the automated tests cannot be run anymore, so it might stop working at some point. Version 7.4 and 8 are marked as tested.

That is an honest statement about a project whose last release was in 2021 and whose CI configuration dates from the Travis era. The library itself is small and has few dependencies on WordPress, so the risk is not the code but the absence of a maintained test matrix on current PHP versions.

The test suite is run with PHPUnit:

vendor/bin/phpunit

and there is also a gulp based workflow that reruns the tests on file change, which needs npm and gulp from the package.json dev dependencies.

The documentation lives in its own repository

The README defers to a wiki for thorough documentation, and adds an unusual detail: the wiki has its own repository, stoutlogic/acf-builder-wiki, and accepts pull requests. Any merges to master in the main project get synced with the wiki.

That arrangement is worth noting because it inverts the usual relationship. Normally a wiki is a static site maintained alongside the code, and it drifts. Here the wiki content is version controlled and reviewable, and the sync means the published documentation follows the released code rather than the other way round.

The same project also keeps a gitter chat badge in the README for questions, and the badges show a Scrutinizer code quality score and a build status from the GitHub Actions workflow for tests.

The repository itself is small and conventional: src for the implementation, tests for the PHPUnit suite, composer.json and composer.lock, a phpunit.xml configuration, a rector.php for automated refactoring, a gulpfile.js and package.json for the JavaScript side of the test workflow, an autoload.php fallback, and a .travis.yml from the earlier CI era.

What the releases added and where the project stopped

The release history shows a project that grew its feature set steadily and then stopped. v1.12.0, tagged 2021-09-17, was about modifying and removing nested fields. 1.11.1, from July 2021, fixed PHP Stan errors and added a php clone functionality. 1.11.0, from February 2021, added conditionals referencing parent fields.

Those are the kinds of releases a mature small library produces, and the gap between them is short. The last push to the repository was on 2026-09-11, and the repository is not archived.

So the code is still there and still readable, but there has been no new release since 2021. If you adopt it, you are adopting a snapshot rather than tracking a release line, and you will be running it against a WordPress and ACF Pro stack that has moved on considerably since.

The GPL-2.0 licence is the other thing to weigh. It is a copyleft licence, so if you modify the library and distribute it, the obligations attach. For most teams the practical question is whether they only use it internally, and any specific compliance question belongs with your own counsel.

Editorial conclusion

acf-builder suits a WordPress project that registers many ACF Pro field groups from code and wants to reuse a group of fields in several places, since the build output is a plain configuration array that ACF registers itself. It is the wrong tool if you only need a couple of groups, since the admin screen is fine for that, and it targets a Pro plugin, not the free version. Before adopting it, install it with composer require stoutlogic/acf-builder, confirm your PHP version is one of the tested ones, and check the wiki, since the thorough documentation lives in a separate repository that is synced from master.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. Releases
5. StoutLogic/acf-builder on GitHub