ACF Composer v3 Released

I don’t normally make posts about releases but this one ended up being a lot larger than expected so I’d like to open up an easy way for people to ask questions or get support specific to the release.

Check out the full release notes here: Release v3.0.0 · Log1x/acf-composer · GitHub

:boom: Breaking Change

If you generated Blocks using the --construct option, you will need to manually update the block __construct()'s with a find & replace:

- use Roots\Acorn\Application;
+ use Log1x\AcfComposer\AcfComposer;

- public function __construct(Application $app)
+ public function __construct(AcfComposer $composer)

- parent::__construct($app);
+ parent::__construct($composer);

Once done, continue to the upgrade guide below.

Upgrade Guide

  1. Make sure ACF Composer is installed in the same composer.json as Acorn.
  2. Run composer require log1x/acf-composer to upgrade to ^3.0.
  3. Update your class references using wp acorn acf:upgrade.

Going forward, it is recommended to use the new Builder class:

- use StoutLogic\AcfBuilder\FieldsBuilder;
+ use Log1x\AcfComposer\Builder;

- $listItems = new FieldsBuilder('listItems');
+ $listItems = Builder::make('listItems');

When using the new Builder class, you can now use ->addPartial() to add field partials:

- $listItems->addFields($this->get(Partial::class));
+ $listItems->addPartial(Partial::class);

Inside of Blocks, enqueue() has been changed to assets($block):

- public function enqueue()
+ public function assets($block)

Running wp acorn acf:upgrade should do all of the above for you automatically.

Config Changes

There are 2 new entries to the acf.php config if you have it published:

| Custom Field Types
| Here you can define custom field types that are not included with ACF
| out of the box. This allows you to use the fluent builder pattern with
| custom field types such as `addEditorPalette()`.

'types' => [
    // 'editorPalette' => 'editor_palette',
    // 'phoneNumber' => 'phone_number',

| Cache Manifest Path
| Here you can define the cache manifest path. Fields are typically cached
| when running the `acf:cache` command. This will cache the built field
| groups and potentially improve performance in complex applications.

'manifest' => storage_path('framework/cache'),

Field Group Caching

ACF Composer now includes field group caching. It may be a good idea to add this to your deployment script, especially if you have a lot of field groups:

$ wp acorn acf:cache

You can view the status of the cache by running wp acorn acf:cache --status or wp acorn about.

Custom Field Types

Seen in the config changes above is support for adding custom field types to the Builder. This should help tidy up code a bit when using custom types like ACF Phone Number and ACF Editor Palette.

Once defined in config/acf.php, you can generate IDE helpers for them using wp acorn acf:ide-helpers.

- $fields->addField('mobile_number', 'phone_number');
+ $fields->addPhoneNumber('mobile_number');

Nice update :+1:!

Does this also fix the issue, that the block name won’t translate in the admin? Didn’t see it in the release notes, but maybe I missed it.

Or is it a won’t fix issue?

It’s not something I’ve looked into. As far as I know, it should technically work on ACF Composer. The reason it doesn’t on Poet is due to Laravel caching the config - but that shouldn’t be an issue in this case.

I do plan on adding a better way to set properties instead of doing it in __construct(), though.


An attributes() method has been added to improve setting dynamic block properties instead of using __construct():

 * The block attributes.
public function attributes(): array
    return [
        'name' => __('Example', 'sage'),
        'description' => __('A simple Example block.', 'sage'),
        'category' => 'formatting',
        'icon' => 'editor-ul',
        'keywords' => [],
        'post_types' => [],
        'parent' => [],
        'ancestor' => [],
        'mode' => 'preview',
        'align' => '',
        'align_text' => '',
        'align_content' => '',
        'supports' => [
            'align' => true,
            'align_text' => false,
            'align_content' => false,
            'full_height' => false,
            'anchor' => false,
            'mode' => false,
            'multiple' => true,
            'jsx' => true,
            'color' => [
                'background' => true,
                'text' => true,
                'gradient' => true,
        'styles' => ['light', 'dark'],
        'template' => [
            'core/heading' => ['placeholder' => 'Hello World'],
            'core/paragraph' => ['placeholder' => 'Welcome to the Example block.'],

So I ran the upgrade and I’m hitting some unexpected errors. Going to number things for clarity.

  1. After updating the package and running acf:upgrade, an error is thrown: “Function acf_register_block_type was called incorrectly. Block type “acf/{block-name}” is already registered.”

  2. I move everything out of the folder app/Blocks and run acf:upgrade again. This time everything works as expected and all of the classes inside of

  3. I empty out resources/views/blocks for a fresh test and then run wp acorn acf:block Tester to create a new block, “Tester”. This creates app/Blocks/Tester.php and resources/views/blocks/tester.blade.php as expected.

  4. Run wp acorn cache:clear and then a new error is thrown, “Function acf_register_block_type was called incorrectly. Block type “acf/tester” is already registered.”

I’m also running Poet for CPT / taxonomy setup, but the issue persists when that’s removed, so don’t think it’s related to that.

I am currently running ACF PRO v 6.2.7 and ACF Extended Pro (the issue persists when ACF Extended is disabled).

Any thoughts as to why this could be happening? Something I’ve missed?

Here is the content of my theme’s current composer.json file as well.

  "name": "roots/sage",
  "type": "wordpress-theme",
  "license": "MIT",
  "description": "WordPress starter theme with a modern development workflow",
  "homepage": "",
  "authors": [
      "name": "Ben Word",
      "email": "",
      "homepage": ""
      "name": "Scott Walkinshaw",
      "email": "",
      "homepage": ""
      "name": "QWp6t",
      "email": "",
      "homepage": ""
      "name": "Brandon Nifong",
      "email": "",
      "homepage": ""
  "keywords": [
  "support": {
    "issues": "",
    "forum": ""
  "autoload": {
    "psr-4": {
      "App\\": "app/"
  "require": {
    "php": "^8.0",
    "fakerphp/faker": "^1.23",
    "guzzlehttp/guzzle": "^7.0",
    "log1x/acf-composer": "^3.0",
    "log1x/poet": "^2.0",
    "log1x/sage-directives": "^1.1",
    "maltyxx/images-generator": "^1.0",
    "mwdelaney/sage-advanced-custom-fields": "^1.6",
    "phenx/php-font-lib": "^0.5.4",
    "roots/acorn": "^3.1",
    "ryangjchandler/blade-capture-directive": "^0.3.0",
    "spatie/laravel-google-fonts": "^1.2",
    "stoutlogic/acf-builder": "^1.12",
    "supermundano/sage-the-events-calendar": "^1.0",
    "voku/simple_html_dom": "^4.8",
    "weble/laravel-adobe-typekit": "^1.1"
  "require-dev": {
    "squizlabs/php_codesniffer": "3.7.1"
  "suggest": {
    "log1x/sage-directives": "A collection of useful Blade directives for WordPress and Sage (^1.0).",
    "log1x/sage-svg": "A useful SVG directive for inlining SVG's within Blade views (^1.0)."
  "config": {
    "optimize-autoloader": true,
    "preferred-install": "dist",
    "sort-packages": true,
    "allow-plugins": {
      "composer/installers": true
  "minimum-stability": "dev",
  "prefer-stable": true,
  "scripts": {
    "lint": [
      "phpcs --extensions=php --standard=PSR12 app"
    "post-autoload-dump": [
  "extra": {
    "acorn": {
      "providers": [

Sorry you’re having issues. I’m not able to reproduce this. Could you invite me to a repo?

Just now on an existing project, after requiring in v3 from v2, I’m able to run acf:upgrade without any other steps needed.


Thanks for the quick response. I just got access to the site so let me get one setup. It’s a slightly older site that I’m taking over for some upgrades, so there could be some other stuff lurking in there I just haven’t found yet.

Just to clarify though, I was able to run acf:upgrade with no problems. The problems are relating to the blocks, i.e. wp acorn acf:block Tester.

It wasn’t a completely fresh install on my end, but I did empty out the entire app/Blocks and resources/views/blocks directories at which everything functions as expected.

As soon as I add in the first block is when the “acf_register_block_type was called incorrectly” starts to pop up.

Can you try creating a new acf block and seeing if you have the same thing on your fresh install while i get that repo added?

Yeah I’m able to create blocks with no problem. I’m not understanding the scenario where ACF Composer would be trying to boot twice which it seems to be doing for you – but I can put something into place to prevent that from happening.

Can you try composer require log1x/acf-composer:dev-chore/prevent-multi-boot ?

It’s definitely a good idea to do this on my part, but I feel like there is something else weird going on in your project for this to happen.

1 Like

Could very well be something weird going on in the project. I’m basically merging an older site’s codebase into a base framework that I have too try and debug some page speed issues etc. before getting things rebuilt.

I just invited you to a repo that has most of the theme code in it. There’s a ton of crap in there right now so if you don’t feel like digging through everything, I totally get it, I’m sure I’ll run into whatever is going on eventually. If you do see anything that sticks out to you though let me know.

I’m going to give your fix here a try now.

This did the trick, thanks. I’m going to keep going on the refactor here, let me know if you do end up seeing anything in there though that looks like the cause.

Great, I’ll push a release. I don’t see anything that stands out looking at the repo but do note that you’ll want to capitalize the names of blocks/fields when you make them so test.php and class test should be Test.php and class Test.

Edit: Release is pushed. Just run composer require log1x/acf-composer

1 Like

v3.0.19 now converts Blocks to block.json when running acf:cache.

This should give a noticeable performance increase when loading blocks in the backend. :zap:


You’re the man, @Log1x can’t wait to try this out