PHP Static Site Generators (Twig Templates)

Website Feb 18, 2021

I've previously loosely covered static site generators and mentioned that they can bring performance benefits to a site. They do this by building the HTML that would otherwise be built by a CMS when a page is requested and storing that as a file with the full content. This means when a request comes in to the web server for a resource, it can directly serve the page, with no processing via a database or similar. Couple that with a CDN and cache like Cloudflare, then those files can be cached closer to your end user, and speed up the site even further.

In this post, I'm going to take a look at some of the static site generators written in PHP, and outline some pros and cons of them.

Sculpin

Sculpin is written for PHP 7 and is quickly installed using Composer. It uses Symfony Bundles to allow you to extend the functionality in a way which may be familiar to you already, and builds pages using Twig templates.

I found it fairly easy to get up and running, but with a few changes needed in places to get URLs how I would want them i.e. without needing /blog/ in every URL. Fortunately the process for that is documented pretty well.

Because the base blog skeleton comes bundled with Bootstrap, the generated CSS is pretty big (nearly 600kB). This is unfortunate as the idea behind a static site generator is to improve website performance. One thing which came out of lighthouse audit tests of a simple sample post (base styling and lipsum text) was to remove unused CSS. It also listed minify CSS as a task to undertake. That may happen as part of a production build, but could lead to a big overhead if not.

A few things which may be off putting for people is the lack of activity around the project. Prior to November 29th 2020, the most recent tweet was in April 2020. At the time of writing, the latest blog post was August 2019. If it wasn't for a recent release, then you'd assume the project was dead!

Speaking of releases, these are few and far between. There was 3.1.0 in December 2020, 3.0.3 was a full year earlier, and 3.02 six month prior to that. It could be that it is just very stable and doesn't need a lot of work. However, there are issues on the project dating back to 2012 which are for older versions and haven't been closed as part of a release, or closed as obsolete due to the new version.

If you like Twig templates, Symfony, and a little bit of configuration in your life, this might be the static site generator for you.

Cecil

Cecil is a generator which only requires one file to get started, the cecil.phar file. Running that and using the commands it comes with should get most people up and running quickly. It requires PHP 7.1+, and uses Twig templates for to generate the site.

With releases every few days, this is one which will be time-consuming to keep up-to-date. Most updates appear to be very small fixes, so getting the updates might not be as essential. Though if you rely on downloading the cecil.phar as part of your CI/CD pipeline, then you will need to consider setting the phar to be a specific URL, rather than the download location online.

The default theme and styling which comes with Cecil is very basic. That's not a bad thing, it means there's a lot of scope for your own creativity. Or to implement a template from elsewhere. Because there's not a lot of styling out of the box, Cecil has a tiny page footprint, and will see the 4x100 score in lighthouse audit with ease.

Documentation for the system is comprehensive, but takes some getting used to. It's not as easy as you might hope to start a fresh and get new blog posts displaying on a grid (like most blog home pages). Adding elements like a list of tags and similar common blog post functionality can be done by reading the documentation and working this into the posts and templates.

Cecil is good, and fast! It will take some getting used to, at least to start with, but is worth checking out.

Symfony Static Dumper

I started this section by looking at Statie, but found it was deprecated from March 2020. It directs users to Symfony Static Dumper. As I like Symfony, I thought I would give it a try. It also means I could use Twig templating to generate the pages.

This differs massively from the others as it builds static static sites from a symfony app. That means you're going to need to create a full blog app and have a database (or manually code every page) to then be able to dump the changes. This is great if you're working on something with multiple contributors who aren't comfortable with source control or markdown. You can build a traditional WYSIWYG platform for them to work on. Then use a CI pipeline or batch job to publish the new pages once they are ready.

Because it's not a static structure, such as markdown, to build the pages, there's greater flexibility in the output. You aren't restricted to needing to follow specific file formats to get the right output. Build the content with whatever tools and editors you normally use, and let the dumper create the static pages from the output normally generated.

I didn't actually test this one further than installing the components, as I don't have a blog platform in place to try it with. Building one for this test wasn't something I wanted to do, as that can take a lot of time and be a source of distraction. If you already have a Symfony application in place serving dynamic pages, this might be something to look in to.

Spress

Spress is another static site generator which runs as a .phar to perform its tasks. Spress requires PHP 7.4+, not 5.6+ as started in the "getting started" documentation, and templating is done using Twig.

Like Cecil, above, the documentation available is comprehensive and easy to understand. Arguably, the Spress documentation is better than Cecil, with slightly more in-depth examples used, and greater functional coverage. However, as has been seen from the PHP requirements, not all of the documentation is accurate, so some trial and error may be needed to get things right.

Also like Sculpin, the default theme (which you should install if you want to make any sort of progress quickly) uses Bootstrap. Spress also includes FontAwesome in the default theme source.
These two items, plus the associated font files and javascript, make up the majority of the page download footprint. This might not seem like it's a lot when the whole page content for an article (a long article), came to 400kB, but over 90% of that footprint is CSS, JavaScript, or fonts.

The last release for Spress was in May 2020, which was the 3.0.0 release. There's been no changes made since then on the master branch, and the issues on GitHub seem a little stale. This is a bit concerning, especially when their Gitter channel hasn't had any activity since May 2020, nor has the blog or the Twitter account.

Getting up and running with Spress is easy enough, so long as you install a theme. If you don't, then there's nothing to build your content into, and you might not have the right structure to generate the output correctly. You will spend a lot of time reading documentation to solve that. Instead, just install the spresso theme as described in the document, and modify a copy of that to build your own theme (don't forget to modify the default theme in config.yml).

Conclusion

Whilst this list is by no means exhaustive for the PHP static site generators which use Twig templating, it should give you some things to think about. Only one of those options has regular updates, but those updates might be too frequent to stay on-top of without breaking things. Two of those have seen their development apparently stagnate, and should leave you with concerns about their long term viability.

Out of all the options here, Sculpin and Cecil are the ones I would look to for getting started with static site generation.

I would avoid the Symfony Static Dumper, unless you already have a Symfony site you want to make static. Building a blog platform only to then make the content itself static will take you way from actually getting content live.

Spress seems overly complicated on the surface, and has the larger learning curve of all of the systems here. Unless there's a clear benefit to using it which I haven't found at a glance, this might be one to avoid if you want to get running quickly and in an easily understandable way.

I prefer Sculpin to get up and running without needing to use a CLI to start new posts. I don't like the time between updates, and the uncertainty around future ones.

I really like the simplicity of Cecil, what it produces, and its general no-nonsense approach. I just feel it updates too often to be considered stable without fully understanding each change. It is good to know that it is regularly maintained and is continually evolving to build a better experience.

There are other options with other templating engines which I will look into on other posts. If you are considering starting, or migrating to, a static site, then give serious consideration and investigation time to Sculpin and Cecil.

Tags