Skip to content
Statamic v2 to v3 migration helper
PHP HTML CSS Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin Fix php-cs-fixer to be Windows-friendly. Nov 22, 2019
src Fix theme migrator idempotency. Feb 6, 2020
tests Fix test. Feb 6, 2020
.gitignore Don't store DS store. Sep 17, 2019
README.md Revert "Form migrator is still WIP." Dec 13, 2019
composer.json Add stat tracking. Dec 23, 2019
phpunit.bat phpunit.bat Nov 22, 2019
phpunit.xml Port migrate fieldset test. Sep 6, 2019

README.md

Statamic Migrator

Statamic 3.0+

🤘 Make migrating from v2 to v3 all the moar easier!

📺 See the migrator in action in this screencast.

Installation

Run the following command in your v3 project root:

composer require statamic/migrator --dev

Getting started

File prep

All of the migrators assume the presence of your v2 project's site folder, as well as any local asset container folders. Be sure to copy these into your v3 project root first. Also, if you were running above webroot, be sure to copy your public/themes folder into site/themes.

Git state

We recommend running these commands from a clean git state, so that you can see a diff of the changes made, and easily rollback if necessary.

Idempotency

It's worth noting that these commands are generally idempotent, in that they can be run multiple times without negative side effects. If you encounter any warnings or errors, fix what you need and re-run your migration command. If necessary, you can force overwriting a particular migration using the --force option.

Upgrade guide

While we hope to automate most of the common tedious stuff for you, anything more custom may need to be manually migrated. For this reason, we still recommend getting familiar with the upgrade guide. Though we can't migrate everything, hopefully you have found this package useful in your transition to v3.

Using the site migrator

The site migrator is the recommended way to migrate your site. To get started...

  1. We recommend creating a new branch, so that you can easily roll back a migration if necessary.

  2. The site migrator requires the presence of your v2 project's site folder, as well as any local asset container folders. Be sure to copy these into your v3 project root. Also, if you were running above webroot, be sure to copy your public/themes folder into site/themes.

  3. We recommend clearing your existing site, to ensure a blank slate for your migration:

    php please site:clear
    
  4. We recommend committing all your changes up to this point, so that you can view a diff of all the changes performed by the migrator.

  5. Run the following command to initiate the migration:

    php please migrate:site
    

Using individual migrators

If you prefer a more granular hands-on approach, you may also run the individual migrator commands.

Fieldset to blueprint migrator

In v3, blueprints are the replacement to fieldsets. It's worth noting that fieldsets technically still exist, although they are are a now a smaller, companion feature to blueprints. To migrate a fieldset to a blueprint:

php please migrate:fieldset post

In this example, post is the fieldset handle.

Collection migrator

In v3, collections have a slightly different folder and config structure. To migrate a collection:

php please migrate:collection blog

In this example, blog is the collection handle.

Pages migrator

In v3, pages are now stored as a collection, with a separate structure to manage your page tree hierarchy. To migrate your pages:

php please migrate:pages

Taxonomy migrator

In v3, taxonomies are mostly plug-and-play, apart from a few minor changes to config structure. To migrate a taxonomy:

php please migrate:taxonomy tags

In this example, tags is the taxonomy handle.

Asset container migrator

In v3, assets and related meta data are now stored within a Laravel filesystem. To migrate a local asset container, you will need to copy your assets folder into your v3 project root, along side your site folder. You can skip this step if migrating an S3 based container. Once ready, run the following command:

php please migrate:asset-container main

In this example, main is the asset-container handle.

Globals migrator

In v3, globals are mostly plug-and-play. To migrate a global set:

php please migrate:global-set global

In this example, global is the global set handle.

Form migrator

In v3, forms fields are now defined in a blueprint. To migrate a form and it's submissions:

php please migrate:form contact

In this example, contact is the form handle.

User migrator

In v3, users are mostly plug-and-play. The most notable change being that email now replaces username as the new file name and handle. To migrate a user:

php please migrate:user hasselhoff

In this example, hasselhoff is the username handle.

Roles migrator

In v3, roles are mostly plug-and-play. The most notable change being that roles are keyed by a slug handle, instead of by uuid. It's worth noting that the user migrator takes care of this relationship on the user end as well. To migrate your user roles:

php please migrate:roles

Groups migrator

In v3, groups are mostly plug-and-play. The most notable change being that groups are keyed by a slug handle, instead of by uuid. Also, we've removed the users array from each group, in favor of storing a groups relationship on the user itself. It's worth noting that the user migrator takes care of this new relationship on the user end. To migrate your user groups:

php please migrate:groups

Settings migrator

In v3, site settings are now stored in a conventional Laravel config directory. We cannot guarantee a complete migration, but this migration attempts to transfer core settings where possible. To migrate your site settings:

php please migrate:settings

Theme migrator

In v3, the concept of 'themes' is gone. Your site just has the one, and it's in the resources directory. When running a full site migration, we only attempt the migration of your active theme. However, you can specify any theme handle when running this migrator individually:

php please migrate:theme redwood

In this example, redwood is the handle of a theme located in the site/themes folder.

It's worth noting that antlers templating has undergone a fair number of changes. The most obvious change is that antlers now uses the .antlers.html file extension. You'll also notice changes in the available tags, modifiers, and how variables cascade, etc.

Due to the evolution of antlers templating, we cannot guarantee a complete migration of your theme, but we attempt to update the most obvious stuff for you.

After migration

Be sure to manually test your site, addressing all errors and warnings as you see fit. When you are finished and happy with your migration, feel free to delete your site and asset container folders from your v3 project root, and then run the following command:

composer remove statamic/migrator

Reporting issues

While we hope to automate most of the common tedious stuff for you, anything more custom may need to be manually migrated. For this reason, we still recommend getting familiar with the upgrade guide. Though we can't migrate everything, hopefully you have found this package useful in your transition to v3. If you come across a bug or issue that you think needs to be addressed, please open an issue.

You can’t perform that action at this time.