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.
Couldn't find what you were looking for? We are happy to help you in the forum, on Slack or on Github.