Statamic is a flat-file, Laravel-based content management system built and supported by Wilderborn (Jack McDade, Jason Varga and Gareth Redfern). It’s great to work with. I had the opportunity to upgrade a v1 site this week, so here’s my tuppence-worth.

The Statamic v2 documentation is excellent, taking the form of Trail Guides as walk-through processes, and Reference for the specific ingredients. It’s written in a conversational style with a liberal sprinkling of unselfconscious humour…

Overall it’s a case of:

  • setting up a clean v2 installation, which includes example content
  • removing the example content and files (optional)
  • transferring v1 files across in a sensible order - no database to worry about

v2 Installation

Getting Started With Statamic walks through setting up Statamic v2, and there’s a useful video on Vimeo.

Mamp Pro was the tool of choice for my local installation.

To configure URL rewrites, the sample .htaccess file should really be used so /index.php/ is removed from resulting URLs.

The installer.php file can be run locally to check requirements and set up a few handy things. This seemed to cleverly delete itself after running locally, so I had to find it again to copy it up to the production server to check that. For the production site I’m transferring hosts to get the required PHP >= 5.5.9 version, though this wasn’t unexpected and not a big deal, with performance improvements also on offer at the new host. Zip archive support for updater backups failed on production, and always_populate_raw_post_data=-1 on both production and local. Not to worry, for now at least.

System files can be moved above webroot for additional security. There’s a bit of extra work there in adjusting default paths in settings files.

The one-click updater tool in v2 is a potentially great time-saving addition.

Clear Site to Remove v2 Example Files

There’s a handy wee command line instruction to do this, with options:

php please clear:site

Best described in this video. It can also create a new theme skeleton for you.

This is optional and can be done after importing your v1 site, as I did after Jack pointed out the video. However since it wipes all /themes/, /collections/ and /pages/ subdirectories, in retrospect I’d recommend instead:

  • set up and play locally with the example files on a complete v2 site
  • set up a fresh v2 site and run Clear Site before the next v1 site import step

If you don’t choose to Clear Site, example content /pages/ and /collections/ subdirectory names can be prefixed with an underscore to hide but retain them for future reference.

Moving v1 Files

You Can Get Here From There clears a path through the undergrowth for an upgrade from v1.

The v2 Control Panel is now located at http://yourdomain/cp/ - this nugget tucked away in the docs under New Defaults. So Tools : Import then Import content from Statamic v1 instructs you to download an exporter add-on for installation into your v1 site. Visit the generated URL for a JSON string which can be pasted back into your v2 control panel. The result was:

  • v1 Entries were taken in as new v2 Collections
  • Pages are transformed to their v2 equivalents

Nice.

A few variables had to be renamed for the site to start working again - for example:

{{ layout_content }}

…becomes:

{{ template_content }}

…and underscores needed removed from various variables.

The custom theme from the /themes/ directory had to be moved across manually. Assets can be similarly copied across from the v1 /assets/ directory to the corresponding v2 location.

Optionally (as entries:listing is backwards-compatible), the main change here is renaming entries in the template code:

{{ entries:listing folder=”example” }}…{{ /entries:listing }}

… as collections:

{{ collection:example }}…{{ /collection:example }}

That was it! Up and running locally with v2. The original v1 site wasn’t enormously complicated but I guess the principles would probably remain the same if it had been. The main process just took a couple of hours as a first attempt, and the next v1 upgrade will go a lot quicker I’m sure.

There’s a high degree of integrity about Statamic that makes it very reassuring to work with, and their Slack v2 support channel is very active.

Statamic