Today was an exciting day for the Bolt community:

And most important of all: we've released Bolt 3.2.0. This release further solidifies the stability of the Bolt 3 branch. Bolt 3.2.0 contains a few new features, but most energy was spent on 'under the hood' improvements.That said, there are a few new goodies, that we'd like to show off:

Exception Handling and Exception screen

In an application of Bolt's size, it can sometimes be hard to troubleshoot potential problems. Especially when an error doesn't really show the cause of the problem or worse: Instead of a nice detailed error message, you'll get a white screen of doom with no information whatsoever. This can cause mayor headaches, while trying to figure out what went wrong and where.

Nobody likes mistakes in the websites, code or templates that they're building, but it's worse if you happen to have a mistake, but you're not aware of it. Bolt 3.2 comes with a completely revamped Exception handler and Exception screen. We've sorted out how the application is bootstrapped and how Exceptions are thrown in our own code, but also in the other components we use. Errors or mistakes that previously remained unseen, are now brought to light, allowing you to fix them. These Exceptions are then shown in a clearly laid out screen, that tells you where the Exception occurred, what most of the important values in the request and routing were, as well as a full stack trace.


Screenshot of Exceptions screen

Another screenshot of Exceptions screen

Symfony HTTP Cache for request caching

We're now using Symfony's HTTP Cache, which replaces Doctrine's file cache. This means that Twig, Doctrine, Bolt and Request caching is done per-environment, and per service. While this already gives a significant performance boost, it opens the door for more improvements down the road, because it allows us more fine-grained control over what is cached and how.

Thumbnail aliases

In previous Bolt versions, we've always created thumbnails by adding the dimensions to the URL. For example: In some cases this might not be desirable. For one, it would allow a potential attacker to iterate over all combinations, quickly filling up a significant amount of disk space in the cache. Secondly, it lacks semantics: 1000x800 is just a dimension, it doesn't tell us anything about what the thumbnail is for, or how it is used.

To solve this, Bolt 3.2 comes with thumbnail aliasing. You can use so called 'aliases' for thumbnails, to give different thumbnail sizes names. Doing so will allow you to keep them organised, and prevent potential flooding by malicious actors. For example:

            size: [400,300]
            cropping: resize

Now, the theme can use {{ record.image|thumbnail('medium') }}, to produce a clean URL for this image.

Better flow during installation

With Bolt we always try to strike a good balance between "Using secure, best practices" and "Low barrier of entry" for novice users. We've noticed that the way we've been handling the packaging scripts could be made more user friendly, while at the same time a seasoned developer might want to have more strict settings. This will be a process going forward, but this release shows the first steps in improving this balance for all users with different levels of expertise.

We've made a small separation in the default settings in the configuration that you'll get when using either a 'distribution' version of Bolt or a different one. In the "distro", the settings are tuned to get you up and running as quickly as possible. They will get a tailored version of the .gitignore file, settings that help troubleshoot common issues, without being intrusive. Finally, when using the 'quick setup' instructions, the configuration files are generated before the user goes to the 'Setup the first user' screen, allowing for a more sensible workflow.

As you may know, starting with Bolt 3, we default to keeping all code files outside of the web root. It turns out that this is still causing problems with people, if they have a webhost that disallows writing outside of the web root. Even though we think this a problem with the host, we realise we can't change the world singlehandedly. As of Bolt 3.2.0, we'll package two versions of the releases: A recommended one, with the bulk of the files outside of the web root, and one for people having to deal with inflexible hosting parties.

In coming versions we'll improve this process by automatically setting the correct file permissions on install or perhaps prompting for a first user account.

Other fixes and changes:

Detailed changes for this release can be found in the Changelog. Besides this, we've been working on the documentation and the code for extensions. We've also updated our Roadmap with the features we're working on at the moment.

Installation & Upgrade

To install this version from scratch, follow the instructions on the updated installation page in the documentation, as can be found here: Installing Bolt.

To upgrade an existing site, see Updating. Be sure to get the correct versions, though: bolt-latest.tar.gz or

If you need the version with all files inside the web root, grab bolt-latest-flat-structure.tar.gz or

Note that we've recently added a more strict whitelist filtering for HTML in fields. If you're upgrading an existing Bolt install, you might need to review your current settings, and adjust them where needed. See config.yml.dist for a baseline set of values to use.

To do a 15-second install, use the following:

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

After this, you might need to set the correct permissions for the cache and image folders. Check our documentation on File system permissions. If you have any questions or remarks, post a comment below, or join us on Slack or IRC.

comments powered by Disqus