Upgrading / Migrating Local Extensions to Bundles for Bolt 3.3

Note: You are currently reading the documentation for Bolt 3.7. Looking for the documentation for Bolt 5.2 instead?

Bolt 3.3 brings with it the removal of "local extensions", and its replacement with Bundles.

Unavoidably this will mean some breaking changes!

The good news is that by changing the approach a little we will hopefully make it a lot easier to write and add Bundles to your applications.

About Bundles¶

Before moving on with this guide, it is a good idea to have a read of the documentation section on Bundles.

The Essential Migration Steps¶

Update Extension Environment¶

If you've had local extensions installed, the extension composer.json and autoloader need to be updated.

There are two ways to achieve this, first via Nut.

php ./app/nut extensions:setup

Alternatively you can visit the Extensions page on your site's backend, and in the right side panel under Maintenance, expand the "Run all Update" drop down, select "Rebuild Autoloader".

Autoloading¶

Bundles, unlike old-style local extensions, autoloading configuration is not handled auto-magically by the Extensions Manager.

As a result, you will need to add each Bundle's source directory to composer.json in site's root directory. You need to open your root composer.json file and add each Bundle's entry to the to the "psr-4" sub-section of the "autoload" section.

For example, if you currently have a local extension, myname/myextension, located at extensions/local/myname/myextension, with your loader class inside a src directory, and Bolt\Extension\Myname\MyExtensionNamespace as the namespace.

    "autoload" : {
        "psr-4" : {
            "Bolt\\Extension\\Myname\\MyExtensionNamespace\\": "extensions/local/myname/myextension/src/"
        }
    }

For further information see the section of the Bundles documentation on configuring autoloading.

Note: You must always remember to run composer dump-autoload in your site's root directory after making any changes to the "autoload" section of your site's composer.json.

Activation¶

Once your extensions can be autoloaded then one more step is needed to direct Bolt to load them.

Activating your Bundles so they will be loaded is now handled via either your .bolt.yml or .bolt.php file.

For further information see the section of the Bundles documentation on configuring activation.