See the video here:

RockMigrations - Wiki

RockMigrations - Wiki


Module Description

RockMigrations has an easy API to do all the things you can do in the PW backend via code. This means you can fully version control your site or app simply by adding all the necessary fields and templates not via clicking but via writing simple scripts that do that tasks for you.

The module also contains several helpers that make it extremely easy to implement fully automated CI/CD pipelines.

Wiki

Check out the WIKI for a Quickstart and Docs!

Limitations

RockMigrations might not support all external fields, especially not ProFields. Adding support has no priority for me because I'm not using them. If you need support for any field that is currently not supported please provide a PR or if you are interested in sponsoring that feature please contact me via PM in the forum. Update: RepeaterMatrix support was added in v3.31.0.

But not to forget: You can still use the regular PW API to create fields and manipulate all kinds of things the way you would do it if RockMigrations did not exist. It might just not be as convenient as when using the RockMigrations API.

Where do I find out all those field and template properties?

  1. You can edit your field or template and copy the code from there (I recommend to only copy the settings you need to make your migration files more readable):

    img
    img

  2. Hover the caret on the very right of the field of the setting you want to set:

    img
    img

Magic

RockMigrations does not only help you with your migrations and deployments but it also adds a lot of helpers that make developing with ProcessWire even more fun.

See WIKI for MagicPages!

Snippets

Another option that helps you get started with migration syntax is using the shipped VSCode snippets. I highly recommend enabling the syncSnippets option in your config:

// site/config.php
$config->rockmigrations = [
  "syncSnippets" => true,
];

Watching files, paths or modules

RockMigrations can watch files, paths and modules for changes. It will detect changes on any of the files on the watchlist and trigger migrations to run if anything changed.

As from version 1.0.0 (29.8.2022) RockMigrations will not run all migrations if one file changes but will only migrate this single changed file. This makes the migrations run a lot faster!

When run from the CLI it will still run every single migration file to make sure that everything works as expected and no change is missed.

Sometimes it is necessary that even unchanged files are migrated. RockMatrix is an example for that, where the module file triggers the migrations for all Matrix-Blocks. In that case you can add the file to the watchlist using the force option:

// inside RockMatrix::init
$rm->watch($this, true, ['force'=>true]);

Watching modules

You can easily watch any ProcessWire module for changes and trigger the migrate() method whenever the file is changed:

// module needs to be autoload!
public function init() {
  $rm = $this->wire->modules->get('RockMigrations');
  if($rm) $rm->watch($this);
}
public function migrate() {
  bd('Migrating MyModule...');
}

Watching files

You can watch single files or entire paths:

$rm->watch(__FILE__, false);
$rm->watch(__DIR__."/foo");

Note that you need to define FALSE as second parameter if the file should not be migrated but only watched for changes. If you set it to TRUE the file will be included and executed as if it was a migration script (see examples below).

Running migrations

RockMigrations will run migrations automatically when a watched file was changed. In case you want to trigger the migrations manually (eg after deployment) you can use the migrate.php file:

php site/modules/RockMigrations/migrate.php

Sometimes you want to work on a file and you want it to be watched for changes, but you don't want to trigger the migrations all the time. For example when working on markup or LESS. In that case you can disable automatic running of migrations:

$config->noMigrate = true;

This prevents running migrations but files will still be watched for changes and you will still be able to trigger migrations from the CLI.

Hooking after migrationsDone

If you want to apply migrations after all other migrations have run, you can hook after migrationsDone:

$wire->addHookAfter("RockMigrations::migrationsDone", function(HookEvent $event) {
  /** @var RockMigrations $rm */
  $rm = $event->object;
  $rm->removeFieldFromTemplate('title', 'field-profilephoto');
  $rm->removeFieldFromTemplate('title', 'field-pressphoto');
});

Files On Demand

You can instruct RockMigrations to download files on demand from a remote server. This makes it possible to create content on the remote system (eg on the live server), pull data from the database to your local machine and as soon as you open a page RockMigrations will fetch the missing files from your remote server.

// without authentication
$config->filesOnDemand = 'https://example.com';

// with http basic authentication
$config->filesOnDemand = 'https://user:password@example.com';

YAML

$rm->watch("/your/file.yaml");
fields:
  foo:
    type: text
    label: My foo field

PHP

$rm->watch("/your/file.php");
<?php namespace ProcessWire;
$rm->createField('foo', 'text');

Auto-Watch

RockMigrations automatically watches /site/migrate.php and files like YourModule.migrate.php.

Working with YAML files

RockMigrations ships with the Spyc library to read/write YAML files:

// get YAML instance
$rm->yaml();

// get array from YAML file
$rm->yaml('/path/to/file.yaml');

// save data to file
$rm->yaml('/path/to/file.yaml', ['foo'=>'bar']);

Working with fieldsets

Working with fieldsets is a pain because they need to have an opening and a closing field. That makes it complicated to work with it from a migrations perspective, but RockMigrations has you covered with a nice little helper method that can wrap other fields at runtime:

// syntax
$rm->wrapFields($form, $fields, $fieldset);

// usage
$wire->addHookAfter("ProcessPageEdit::buildForm", function($event) {
  $form = $event->return;

  /** @var RockMigrations $rm */
  $rm = $this->wire->modules->get('RockMigrations');
  $rm->wrapFields($form, [
    'title' => [
      // runtime settings for title field
      'columnWidth' => 50,
    ],
    // runtime field example
    [
      'type' => 'markup',
      'label' => 'foo',
      'value' => 'bar',
      'columnWidth' => 50,
    ],
    'other_field_of_this_template',
  ], [
    'label' => 'I am a new fieldset wrapper',
  ]);
})

Migration Examples

Field migrations

CKEditor field

$rm->migrate([
  'fields' => [
    'yourckefield' => [
      'type' => 'textarea',
      'tags' => 'MyTags',
      'inputfieldClass' => 'InputfieldCKEditor',
      'contentType' => FieldtypeTextarea::contentTypeHTML,
      'rows' => 5,
      'formatTags' => "h2;p;",
      'contentsCss' => "/site/templates/main.css?m=".time(),
      'stylesSet' => "mystyles:/site/templates/mystyles.js",
      'toggles' => [
        InputfieldCKEditor::toggleCleanDIV, // convert <div> to <p>
        InputfieldCKEditor::toggleCleanP, // remove empty paragraphs
        InputfieldCKEditor::toggleCleanNBSP, // remove &nbsp;
      ],
    ],
  ],
]);

Image field

$rm->migrate([
  'fields' => [
    'yourimagefield' => [
      'type' => 'image',
      'tags' => 'YourTags',
      'maxFiles' => 0,
      'descriptionRows' => 1,
      'extensions' => "jpg jpeg gif png svg",
      'okExtensions' => ['svg'],
      'icon' => 'picture-o',
      'outputFormat' => FieldtypeFile::outputFormatSingle,
      'maxSize' => 3, // max 3 megapixels
    ],
  ],
]);

Files field

$rm->migrate([
  'fields' => [
    'yourfilefield' => [
      'type' => 'file',
      'tags' => 'YourTags',
      'maxFiles' => 1,
      'descriptionRows' => 0,
      'extensions' => "pdf",
      'icon' => 'file-o',
      'outputFormat' => FieldtypeFile::outputFormatSingle,
    ],
  ],
]);

Options field

$rm->migrate([
  'fields' => [
    'yourfield' => [
      'type' => 'options',
      'tags' => 'YourTags',
      'label' => 'Options example',
      'options' => [
        1 => 'ONE|This is option one',
        2 => 'TWO',
        3 => 'THREE',
      ],
    ],
  ],
]);

Options field with multilang labels:

$rm->createField('demo_field', 'options', [
  'label' => 'Test Field',
  'label1020' => 'Test Feld',
  'type' => 'options',
  'optionsLang' => [
    'default' => [
      1 => 'VERYLOW|Very Low',
      2 => 'LOW|Low',
      3 => 'MIDDLE|Middle',
      4 => 'HIGH|High',
      5 => 'VERYHIGH|Very High',
    ],
    'de' => [
      1 => 'VERYLOW|Sehr niedrig',
      2 => 'LOW|Niedrig',
      3 => 'MIDDLE|Mittel',
      4 => 'HIGH|Hoch',
      5 => 'VERYHIGH|Sehr hoch',
    ],
  ],
]);

Note that RockMigrations uses a slightly different syntax than when populating the options via GUI. RockMigrations makes sure that all options use the values of the default language and only set the label (title) of the options.

Page Reference field

$rm->migrate([
  'fields' => [
    'yourfield' => [
      'type' => 'page',
      'label' => __('Select a page'),
      'tags' => 'YourModule',
      'derefAsPage' => FieldtypePage::derefAsPageArray,
      'inputfield' => 'InputfieldSelect',
      'findPagesSelector' => 'foo=bar',
      'labelFieldName' => 'title',
    ],
  ],
]);

Date field

$rm->migrate([
  'fields' => [
    'yourfield' => [
      'type' => 'datetime',
      'label' => __('Enter date'),
      'tags' => 'YourModule',
      'dateInputFormat' => 'j.n.y',
      'datepicker' => InputfieldDatetime::datepickerFocus,
      'defaultToday' => 1,
    ],
  ],
]);

Migration Strategies

For larger projects, enhancing the maintainability of your migrations involves breaking them into smaller segments and dispersing them across your codebase. These segments can be linked to modules or custom PageClasses. All available options for achieving this are mentioned above in the sections about watching files.

Here are some examples:

  1. Module-based Migrations: When you are developing a module, you can consolidate all relevant migrations within a file named YourModule.migrate.php. These migrations will be automatically picked up.

  2. Custom PageClass with Template-specific Migrations: It is highly recommended to use custom PageClasses. Within these custom PageClasses, you can include template-specific migrations using MagicPages. Here's an example:

    <?php

namespace ProcessWire;

use RockMigrations\MagicPage;

class BasicPagePage extends Page
{
  use MagicPage;

  public function migrate()
  {
    $rm = $this->rockmigrations();
    $rm->migrate([
      'fields' => [
       // create the required fields here, if they don't exist already
      ],
      'templates' => [
        'basic-page' => [
          'fields' => [
            'title',
            'text',
          ],
          'childTemplates' => [
            'basic-page',
          ],
          'sortfield' => 'title',
        ],
      ],
    ]);
  }
}

    Please note that you must create the template separately from the custom PageClass. PageClasses will only be triggered once their associated template exists. You could do that inside your /site/migrate.php.

On this page