Bolt 3.3 is the next step in the continued evolution of everyone's favourite CMS. We've received and merged nearly 300 pull requests from dozens of contributors around the world. All helping to shape, grow, and develop Bolt, allowing users & developers to do more with less. I'd like to thank our core development team specifically, for putting in a tremendous amount of work for this release. Thank you, Carson, Ross, Svante and Gawain!

For a comprehensive list of changes, refer to the changelog on GitHub.

Major Changes in 3.3

Installation Documentation Overhaul

In preparation for 3.3.0 we've overhauled our installation documentation, with a focus on use by a broader audience of people installing Bolt.

Jump on over to the install section of our documentation site, and let us know what you think.

Since Bolt 3.3.0 is still in RC, and the documentation assumes you'll want to install the latest stable version, use these slightly modified commands to install Bolt. Quick install:

curl -O
tar -xzf bolt-v3.3.0-RC1.tar.gz --strip-components=1
php app/nut init

Composer create project:

composer create-project bolt/composer-install:^3.3@RC --prefer-dist

If you're upgrading from Bolt 3.2 to Bolt 3.3, there are a few caveats you'll need to take into account. See below for instructions on how to update your sites smoothly.

Themes! Yes, Themes!

A few rather exciting developments are included with Bolt's example themes in 3.3, notably a new "skeleton" theme that you can copy and use to get started quickly. We've also revamped base-2016 to get it ready for Twig 2.

Behind the scenes we've decoupled these example themes into a new project, bolt/themes with the aim of lowering the barrier for people wanting to work on improving the out-of-the-box Bolt install.

We've also made improvements to make linking to other resources (assets, records, external pages) more consistent and better in line with standard Symfony practices. This is described extensively in the documentation in Linking in templates.

Canonical URL Handling

The code that handles canonical URLs was completely rewritten during the development of Bolt 3.3, and a significant number of quirks and bugs were fixed in the process, such as correctly handling HTTP vs HTTPS, subsites, and many more!

Bolt Collection Library

An exciting new addition to the Bolt project, included as a dependency, is bolt/collection.

Notably, this brings two new classes; Bolt\Collection\Bag and Bolt\Collection\ImmutableBag. Very simply, these are object-oriented implementations of arrays that provide:

  • Functionality on par with built-in array methods
  • Useful functionality lacking from built-in array methods
  • A fluent-like experience for working with PHP array-type data

Editors and template developers will not notice any changes to the way they work with Bolt, but for people extending Bolt this is an incredibly simple, exciting, and powerful feature! We really hope you enjoy using this new library as much as we do.

Configuration helper

We've added a new "Configuration Notices" helper in the form of a Dashboard widget. It automatically checks for a large number of common and less common issues, that might not be apparent at first sight. If possible, it also gives a quick pointer on how to fix the found issues.

Configuration Notices screenshot

Local Extension replaced with Bundles (breaking change)

Bolt 3.3 brings with it the removal of "local extensions", and its replacement with Bundles. Unavoidably this will mean some breaking changes.

Local extensions were originally designed to aide in the development of extensions prior to publishing them to Bolt's Marketplace. However, as with many useful features, they came with a lot of quirks, this situation was compounded with the unintended use of local extensions in production. A better, more flexible, solution was desperately needed!

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.

For the full documentation on the use of Bundles, see the new Bundled Extensions section of our documentation.

For those upgrading a pre-3.3 site, we've prepared a page on Migrating Local Extensions to Bundles for Bolt 3.3.

Extension Page & Route

An ever so slight change that site administrators and developers will notice is that the "Extend" page has been renamed to "Extensions" , and the URL has also changed from /bolt/extend to /bolt/extensions.

Only extensions that add a page to the back-end of Bolt need updating, and the most popular Bolt extensions have been updated to handle this gracefully.

Deprecation of fields().

The {{ fields() }} Twig tag has long been a source of discussion in the Bolt core team.

On the one hand it's extremely useful as both a "quick prototyping" tool, as well as in the default theme to always give meaninful output when the template has no knowledge about the Record structure in the ContentTypes definition. On the other hand, it was found to be a "black box", and if you've modified the standard output, it might break on updates.

We've moved away from using macros, and are now using self-contained block tags for the same functionality. This means that they no longer rely on anything in Bolt core, but are purely an implementation for a specific template, making them a lot more maintainable.

For details on how to use them, see the example in our new Skeleton theme: record.twig and partials/_sub_fields.twig.


We've started to overhaul our translation layer in Bolt 3.3, and with this comes a nifty new feature: Site specific translations!

To use, in your site project create app/translation/xx_XX/messages.xx_XX.yml or app/translation/messages.xx_XX.yml (all translations in the one directory) files, and add your keywords and translated messages there. These files will have a higher priority than the default ones installed by Bolt, allowing more flexible configuration.

Session Storage with Memcached or Redis

Session handling has long been one of the "black sheep" in PHP, and has come a long way in recent years. Symfony 2 has abstracted session handling, and Bolt has continued to build, strenghten and secure that. We beleive that we're now delivering a world-class solution to our implementors and end users.

To further build on this, we've continued to refine out session storage options and have promoted both Memcached & Redis to first class session storage supported options for advance use-cases.

For details on this, see the Sessions section of the documentation.

Remote Filesystems — Now including Amazon S3

Over the last 5 years, Bolt has grown both as a project, and in terms of how it is used. Increasingly it is being used on increasingly larger and larger implementations, including many sites with millions of hits per month. To enable this scaling we've been working for sometime to abstract and fully virtualise the underlying filesystem.

With the release of Bolt 3.3 we are very ~proud~ excited to add Amazon S3 as a remote filesystem option.

Please note however, that this is quite an advanced option. Nonetheless we've added some detailed documentation to assit implementors in scaling their Bolt sites to the proverial "next level", and this has already helped numerous beta testers roll out some very large sites.

Did we mention how excited we are about this?

Preparations for Bolt 4, Silex 2, Symfony 3 & Twig 2

Behind the scenes we are hard at work getting Bolt 4 ready for release early next year, with it will come Silex 2, Symfony 3 (or perhaps even Symfony 4) & Twig 2.

To make this transition smoother, we've updated a lot of internal code to support these changes, and deprecated a lot of functionality in our internal API.

We've also updated how deprecation reporting is done, so site developers will be able to see what is deprecated but still being used.

Apart from that, we'll go into Beta for Bolt 3.4 very soon, which will contain more ongoing updates and additions, moving forward to the next major release.

Debugging Improvements

There is a famous quote in computer science that states "[…] debugging is twice as hard as writing a program in the first place" . Bolt has always focused on reducing complexity where it makes sense, and debugging is no exception.

So we've updated our documentation and added some additional Nut commands to Bolt to help site builders get a better understanding of what is happening.

Exception handling

Bolt 3.2 saw the introduction of modernised exception handling, and we've continued to refine and improve that in 3.3, cleaning up a few quirks along the way.

Updating from previous Bolt 3.x sites to 3.3

As you've read above, we've made some major changes to session handling. This means that if you're updating, you'll need to take care you and your users don't have lingering "old" sessions and/or cookies.

The update itself is pretty straightforward. If you're using composer to update, set the following in your composer.json:

"require": {
    "php": "^5.5.9 || ^7.0",
    "bolt/bolt": "^3.3@RC",
    "passwordlib/passwordlib": "^1.0@beta"
"minimum-stability": "beta",
"prefer-stable": true,

Then run composer update --optimize-autoloader and php app/nut init to update.

If you're on the CLI, but prefer to update using the distribution files, use:

curl -O
tar -xzf bolt-v3.3.0-rc1.tar.gz --strip-components=1
php app/nut init

The two most common "problems" to encounter during the update are:

You get an error like Compile Error: Declaration of JsonSchema\Constraints during composer update

This is due to a conflict between composer and a stale component in the cache. Fix it by running the following:

composer selfupdate
composer clearcache
rm -rf vendor
composer install

After doing so, Bolt will be installed / updated correctly.

You can't login / are stuck in a redirect loop

To resolve this, you need to make sure all old sessions are flushed. Take the following steps:

  • Clear out the app/cache/ folder, and especially app/cache/.sessions (it's often hidden).
  • Truncate (but not delete) the bolt_authtoken table in your database, using the database administration tool of your choice.
  • Finally, clear the cookies in your browser.

Now you'll be able to log in, as usual. If you've bumped into this, be sure to also tell your users / editors that they might need to clear out their cookies.

comments powered by Disqus