Migrating From Statamic v1

Overview

We spent over 3 years growing v1, learning what our users needed, and maintaining backwards compatibility at every turn. We never made a semantic 2.0 update (even though maybe we should have for marketing purposes) that would break anything.

Not changing how anything works on the end-user level meant living with naming mechanisms that we grew out of, organization structures that became brittle, and technical limitations and debt that became looming harbingers of doom. Feature Requests began to feel like TPS Report assignments. When you lose the ability to change quickly and with confidence you lose the ability to scale and grow alongside your users.

For that reason, we rewrote everything for v2 and took the opportunity to analyze every feature, every tag name, every fieldtype, every file and folder — to make sure they fit together consistently, naturally, and intuitively. Our codebase is modern, flexible, testable (and tested), and is ready for the long haul.

From here out we will explain what has changed, why, and what you’ll need to do to upgrade your v1 site. Most of these things can be done with a project-wide find & replace (everything is still files after all), or some dragging, dropping, and renaming of files.

Recommended Upgrade Approach

We recommend starting with a fresh Statamic 2 install and then moving your content, theme, fieldsets, and users over, section by section. It’ll help you to focus on which areas need changes and isolate any unexpected behaviors.

The best way to move your content is to use the Importer and Exporter. It can generate a JSON representation of all of your content (pages, entries, globals, and taxonomies) and then generate all the right files in the right places.

Breaking Changes

Each of these changes may require a little bit of manual work.

File and Folder Naming Conventions

• Filename order keys are always delimited with a period before the slug. For example: 2015-12-25.christmas.md and 2.about/index.md. You can use a tool like Name Mangler to batch all these at once and confirm that the output is right before you do it.
• Rename page.md files to index.md.
• Convert any pages that aren’t in the folder/index.md format (e.g. /about/team.md becomes /about/team/index.md).

Entries Move into Collections

• Move entries into their own Collection and configure their route.
• Mount them to their corresponding pages by adding mount: collection_name to the appropriate index.md.
• Move fields.yaml from the page’s to the collection’s folder, and name it folder.yaml

Renamed Variables

• {{ layout_content }} is now {{ template_content }} because it’s the actual contents of the template. Feels so much more natural.
• {{ current_date }} is now {{ now }}

Removed Variables

• {{ _is_draft }}
• {{ _is_hidden }}
• {{ taxonomy_name }}
• {{ taxonomy_slug }}

Setting and Variable Naming Conventions

You know all those things that start with an underscore? _site_root, _layout, _template. We grew to hate those darn underscores. They were ugly. Annoying. They’re all gone. All of them, everywhere. They’re replaced with non-underscored versions of themselves. Also, we now have some system protected words. Don’t name your variables any of these words:

• template
• layout
• fieldset
• slug
• attributes
• parse_content
• first
• last
• redirect

Removed and Replaced Fieldtypes

The former templates fieldtype is now named template, singular.

The Location fieldtype, tag, and {{ entries:meld }} tag have been removed. We feel it’s important to eliminate reliance on third-party APIs for all core features. The maps HTML from v1 came from Leaflet.js and was really just a wrapper for their default implementation. Check it out, it’s pretty straightforward.

The File fieldtype is replaced by Assets. As long as you don’t move your files, your links won’t break, but you will lose your Control Panel connection to them. Check out the Assets guide to learn about the new and improved ways.

Status is gone. We now have the notion of “published” and “unpublished”. Unpublished content is represented by files beginning with an underscore _.

Removed Modifiers

The following modifiers were removed because they were rarely, if ever used and only served to make scanning the docs tedious. They were part of some mapping features we removed from core. Feel free to copy and paste them out of v1 and release them as free addons. You have our 100% permission.

• abs
• acos
• asin
• atan
• censor
• cos
• decbin
• dechex
• decoct
• deg2rad
• distance_in_km_from
• distance_in_mi_from
• double
• hexdec
• log
• log10
• octdec
• ordinal
• rad2deg
• rot13
• sin
• spaced_list
• sqrt
• tan
• triple

Addons

Addons are structured pretty differently in v2. Chances are porting one won’t prove to be very difficult, and may even be an enjoyable experience, but you can’t just drop a v1 addon into v2. At best nothing will happen. At worst, a wampa will try to eat you.

The Control Panel

The Control Panel is now accessible at /cp instead of admin.php. If you want to rename it, you can do so in your index.php file.

New Defaults

Required Fields

• The title field is no longer required when working with files only.
• The content field is no longer required. If you choose to ignore the content field, the --- YAML Front Matter delimiters are removed automatically for your (and our) convenience. It will be a straight YAML file.

Settings

Settings are now broken out by area of responsibility, and can be found in site/settings. You can explore them all in the Control Panel with descriptions, help text, and a nice interface. Of course, you can do it all in files still too, just like v1.

Learn more about Settings.

Better Ways of Doing Things

There are ways of doing things in v2 that are streets ahead of v1. You aren’t by any means required to change your logic, but if you choose to do so, you’ll be glad you did. Don’t let yourself get streets behind. Here’s a summary of those things.

Content Types

• Taxonomies, globals, and assets are first class citizens now; they are full-on Content Types with their own customizable fields.
• Just about everything is multilingual now, and it’s pretty darn neat.

Relationships

• All content gets a unique id: id. If you manually create a file, one will get added for you automatically. These ids let you create unbreakable relationships between various bits of data. It’s neat. Also, don’t remove them from your files.
• The new Relate Fieldtype replaces Suggest and provides an all-in-one relationship management interface, pairing nicely with the Relate Tag and | get Modifier.

Users

• Users can log in with email address in addition to username.
• Users can be organized into Groups.
• User groups can have Roles.
• User roles can have Permissions.
• Permissions let you decide which users get to do which thing, like delete pages, manage settings, or run the Updater.

Templates

• Tags now have optional scopes you can use to eliminate any conflict with The Cascade.
• Entries Listing and Collection tags can use a child variable alias (e.g. {{ entries }}) to let you more easily manage your markup.
• There are a lot more modifiers and an easier to use syntax. There’s a good chance you can simplify your templates and make them more readable.
• You know what? Just read through the whole Template Language guide. You’ll be glad you did.

Search

Search is Bloodhound’s cooler cousin. Search automatically indexes for performance. Search is more easily configured. Search connects to Algolia in a matter of seconds. Search is included in core. What more can you ask for? (Besides keyword weighting. Search doesn’t do keyword weighting.)