### Create Field and Template with RockMigrations

Source: https://github.com/baumrock/rockmigrations/wiki/Home

This example demonstrates how to create a new text field named 'demo' and a template also named 'demo' using the RockMigrations module. It includes setting a label and tags for the field, and assigning fields and tags to the template. Ensure TracyDebugger is installed for `bd()` calls.

```php
/** @var RockMigrations $rm */
$rm = $modules->get("RockMigrations");
bd('Create field + template via RM');
$rm->createField('demo', 'text', [
  'label' => 'My demo field',
  'tags' => 'RMDemo',
]);
$rm->createTemplate('demo');
$rm->setTemplateData('demo', [
  'fields' => [
    'title',
    'demo',
  ],
  'tags' => 'RMDemo',
]);
```

--------------------------------

### Permission Migration Example

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/config-migrations/readme.md

Example of a permission migration file. It returns a string describing the permission.

```php
// site/RockMigrations/permissions/my-permission.php
// return permission description as string
return 'My Permission Description';
```

--------------------------------

### Module-based Migrations Example

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

An example of how to structure migrations within a module file named 'YourModule.migrate.php'.

```php
<?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',
        ],
      ],
    ]);
  }
}
```

--------------------------------

### Install Language Packs and Support Modules

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/RockMigrations/rm-defaults.txt

Automate the installation of language packs and related support modules for ProcessWire. This includes setting up translations and installing modules like LanguageSupportFields, LanguageSupportPageNames, and LanguageTabs.

```php
// install german language pack for the default language
// this will install language support, download the ZIP and install it
$rm->setLanguageTranslations('DE');
$rm->installModule('LanguageSupportFields');
$rm->installModule('LanguageSupportPageNames');
$rm->installModule('LanguageTabs');

```

--------------------------------

### Role Migration Example

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/config-migrations/readme.md

Example of a role migration file. It defines the permissions associated with a specific role.

```php
// site/RockMigrations/roles/my-role.php
// return permissions of this role
return [
  'page-edit',
  'page-delete',
];
```

--------------------------------

### Install German Language Pack with RockMigrations

Source: https://github.com/baumrock/rockmigrations/wiki/Deployment

Installs the German language pack by downloading and installing its ZIP file. This example uses 'DE' as the language code.

```php
$rm->setLanguageTranslations('DE');
```

--------------------------------

### Full Repeater Migration Example

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/repeaters/readme.md

This example demonstrates a complete migration process: first defining prerequisite fields, then creating the repeater field, and finally adding the repeater to a template. All fields must be pre-existing before being added to the repeater.

```php
$rm->migrate([
  'fields' => [
    // first, make sure that all fields exist
    'foo' => [
      'type' => 'text',
      'label' => 'Foo field',
      'icon' => 'align-left',
      'textformatters' => [
        'TextformatterEntities',
      ],
    ],
    'bar' => [
      'type' => 'text',
      'label' => 'Bar field',
      'icon' => 'align-left',
      'textformatters' => [
        'TextformatterEntities',
      ],
    ],

    // then create the repeater field
    'your_repeater_field' => [
      'label' => 'My repeater field',
      'type' => 'FieldtypeRepeater',
      'fields' => [
        'title',
        'foo',
        'bar',
      ],
      'repeaterTitle' => '#n: {title}',
      'familyFriendly' => 1,
      'repeaterDepth' => 0,
      'tags' => '',
      'repeaterAddLabel' => 'Add New Item',
      'columnWidth' => 100,
    ],
  ],
  'templates' => [
    // finally add the repeater to your template
    'your_template' => [
      'fields' => [
        'title',
        'your_repeater',
      ],
    ],
  ],
]);
```

--------------------------------

### Example Price Class in classLoader

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/classloader/readme.md

This example shows a `Price` class extending `WireData` within the `classLoader` directory. Classes in this directory are automatically loaded by RockMigrations.

```php
<?php

namespace RockCommerce;

use ProcessWire\WireData;

class Price extends WireData
{
  public $net;
  public $vat;
  public $gross;
  public $taxrate;

  // more code here
}
```

--------------------------------

### Template Migration Example

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/config-migrations/readme.md

Example of a template migration file. It defines the fields and child templates associated with a template.

```php
// site/RockMigrations/templates/my-template.php
// return template data
return [
  'fields' => [
    'title',
    'foo',
    'bar',
  ],
  'childTemplates' => [
    'my-child-template',
  ],
  'noSettings' => true,
];
```

--------------------------------

### Conditional Migration with Confirmation Callback

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/once/readme.md

Use a confirmation callback to ensure a migration is marked as completed only if a specific condition is met. This example installs a module and confirms its installation.

```php
// install process module if it is not installed
$rm->once(
  "11.02.2024: Install RockMigrations Process Module",
  function (RockMigrations $rm) {
    $rm->installModule("ProcessRockMigrations");
  },
  confirm: function () {
    return $this->wire->modules->isInstalled("ProcessRockMigrations");
  },
);
```

--------------------------------

### Field Migration Example

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/config-migrations/readme.md

Example of a field migration file. It defines the label and type for a field, supporting magic properties like '*Language' for conditional type selection.

```php
// site/RockMigrations/fields/myfield.php
return [
  'label' => 'My Field Label',
  'type' => 'textarea*Language',
];
```

--------------------------------

### Get YAML Instance and Data

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Obtain the YAML instance or load data from a YAML file.

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

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

--------------------------------

### Example RockShell Command

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/rockshell/readme.md

This is a sample RockShell command class that demonstrates how to define a command and its logic. It includes a method to perform an action and logs a message using TracyDebugger if not running in a CLI environment.

```php
<?php

namespace Site;

use RockShell\Command;

class SiteDoSomething extends Command
{
  public function handle()
  {
    $this->doSomething();
    return self::SUCCESS;
  }

  public function doSomething(): void
  {
    // do something

    // log when not in CLI
    if(!$this->isCLI()) bd("I'm doing something!");
  }
}
```

--------------------------------

### Real-World Example: Remove Template Context

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/once/readme.md

This example demonstrates reverting a template context for a specific field using `once()`. It ensures the action is performed only once, preserving subsequent migration changes.

```php
$rm->once(
  "2024-02-11: Remove template context from coverpic",
  function ($rm) {
    $rm->removeTemplateContext("my_template", "coverpic");
  }
);
```

--------------------------------

### Github Actions Deploy Workflow Setup

Source: https://github.com/baumrock/rockmigrations/wiki/Deployment

Defines a Github Actions workflow to test SSH connectivity before proceeding with deployments. It uses a reusable workflow from RockMigrations.

```yaml
name: Deploy via RockMigrations

# Specify when this workflow will run.
# Change the branch according to your setup!
# The example will run on all pushes to main and dev branch.
on:
  push:
    branches:
      - main
      - dev

jobs:
  test-ssh:
    uses: baumrock/RockMigrations/.github/workflows/test-ssh.yaml@main
    with:
      SSH_HOST: your.server.com
      SSH_USER: youruser
    secrets:
      SSH_KEY: ${{ secrets.SSH_KEY }}
      KNOWN_HOSTS: ${{ secrets.KNOWN_HOSTS }}
```

--------------------------------

### Magic Assets Example

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/magicpages/readme.md

MagicPages automatically loads YourPage.css and YourPage.js in the PW backend when editing a page of type YourPage. This example shows how to include a CSS rule and a JavaScript alert.

```php
// /site/classes/HomePage.php

// /site/classes/HomePage.css
div { outline: 2px solid red; }

// /site/classes/HomePage.js
alert('You are editing the HomePage');
```

--------------------------------

### Get YAML Instance

Source: https://github.com/baumrock/rockmigrations/blob/main/readme.md

Get an instance of the YAML handler provided by RockMigrations.

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

--------------------------------

### Install Modules in beforeAssets Hook

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/config-migrations-hooks/readme.md

Use the `beforeAssets` hook to install necessary modules before creating fields or templates that depend on them. Temporarily disable config migrations to prevent infinite loops.

```php
<?php

namespace ProcessWire;

$rm = rockmigrations();

// install fieldtype + inputfield modules
$rm->configMigrations(false);
wire()->modules->install('FieldtypeRockInvoiceitems');
wire()->modules->install('InputfieldRockInvoiceitems');
$rm->configMigrations(true);
```

--------------------------------

### PHP Migrate Function Example

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/RockMigrations/rm-migrate-function.txt

This PHP function demonstrates how to use the migrate() method from the RockMigrations class to define changes for fields and templates. It's intended for use within a RockPageBuilder block.

```php
public function migrate()
{
  $rm = $this->rockmigrations();
  $rm->migrate([
    'fields' => [$0],
    'templates' => [
      self::tpl => [
        'fields' => [
          'title',
        ],
      ],
    ],
  ]);
}
```

--------------------------------

### YAML Field Definition

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Example of a field definition in YAML format.

```yaml
fields:
  foo:
    type: text
    label: My foo field
```

--------------------------------

### Get ProcessWire Version from package.json

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/ProcessWire/pw-version.txt

Loads the package.json file from the current directory and decodes it to extract the version number. Ensure package.json exists in the same directory as the script.

```php
json_decode(file_get_contents(__DIR__ . "/package.json"))->version
```

--------------------------------

### Custom Page Class with MagicPage

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/ProcessWire/pageclass.txt

Example of a custom page class extending ProcessWire's Page and using the MagicPage trait. Define template and prefix constants.

```php
<?php

namespace ProcessWire;

use RockMigrations\MagicPage;

class $1Page extends ${2:Page}
{
  use MagicPage;

  const tpl='$3';
  const prefix='$3_';
  $0
}
```

--------------------------------

### Hook After Migrations are Done

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Add a hook to run custom logic after all RockMigrations have completed. This example removes specific fields from templates.

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

--------------------------------

### Get Sorted Watchlist for Debugging

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/classloader/readme.md

This code snippet shows how to retrieve and debug the sorted watchlist of RockMigrations. The sorted watchlist represents the execution order of your migrations, which is essential for debugging.

```php
bd(rockmigrations()->sortedWatchlist());
```

--------------------------------

### Generate SSH Key Pair

Source: https://github.com/baumrock/rockmigrations/wiki/Deployment

Generates an RSA key pair for the deploy workflow. Use a custom name like 'id_rockmigrations' to avoid overwriting existing keys. This is a one-time setup step.

```bash
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rockmigrations -C "rockmigrations-[project]"
```

--------------------------------

### Define Custom Repeater Page Class

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/classloader/readme.md

This example shows how to define a custom repeater page class by extending ProcessWire's RepeaterPage. It highlights the necessity of defining the 'field' constant, which references the name of the field used for repeater items.

```php
<?php

namespace RockCommerce;

use ProcessWire\RepeaterPage;

class Accessory extends RepeaterPage
{
  // you must define the "field" constant for your repeater page class!
  // it has to reference the name of the field used for repeater items of this type
  const field = "rc_product_accessories";

  // a lot more code here :)
}
```

--------------------------------

### Loading and Executing RockShell Command in ready.php

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/rockshell/readme.md

This snippet shows how to load a registered RockShell command using the `rockmigrations()` helper and execute its method directly within `site/ready.php`. This is useful for live development and debugging with TracyDebugger.

```php
rockmigrations()
  ->rockshell()
  ->get("site:do:something")
  ->doSomething();
```

--------------------------------

### Configure Production Database and Auth Salt

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Set production database credentials and the generated userAuthSalt in the config-local.php file.

```php
$config->dbHost = 'localhost';
$config->dbName = 'your_db_name';
$config->dbUser = 'your_db_user';
$config->dbPass = 'c8kCbEBYM3t1VQ==';

$config->userAuthSalt = 'IHeIVPuu9LARrXG4L/6nfslYzCRoFIbFdkiwy5JWbTGVqkTV8ClBmw==';
```

--------------------------------

### Set Module Configurations with RockMigrations

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/RockMigrations/rm-defaults.txt

Configure modules like AdminThemeUikit and ProcessPageList to customize their behavior. Use this to set specific options such as toggle behavior or trash visibility.

```php

// Set some custom PW defaults
$rm->setPagenameReplacements('de');
$rm->setModuleConfig('AdminThemeUikit', [
  // use consistent inputfield clicks
  // see https://github.com/processwire/processwire/pull/169
  'toggleBehavior' => 1,
]);
$rm->setModuleConfig('ProcessPageList', [
  'useTrash' => true, // show trash in tree for non superusers
]);

```

--------------------------------

### Implement init() and ready() in Custom Page Class

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/magicpages/readme.md

Implement the `init()` and `ready()` methods within your custom page class to attach hooks and logic directly to the page class. This avoids spreading related code across multiple files.

```php
<?php

namespace ProcessWire;

use RockMigrations\MagicPage;

class DemoPage extends Page {
  use MagicPage;

  public function init() {
    // Your init code here
  }

  public function ready() {
    // Your ready code here
  }
}
```

--------------------------------

### Staging Instance-Specific Configuration

Source: https://github.com/baumrock/rockmigrations/wiki/Setting-up-different-config.php-files

This file holds configuration settings for a staging environment. It should be kept separate from your git repository. It defines database credentials, salts, http hosts, and TracyDebugger settings.

```php
<?php

namespace ProcessWire;

/** @var Config $config */
$config->debug = true;
$config->advanced = true;
$config->dbName = 'your_db';
$config->dbUser = 'your_db_user';
$config->dbPass = '1234';
$config->dbHost = 'localhost';
$config->userAuthSalt = '1234567';
$config->tableSalt = '1234567';
$config->httpHosts = ['yourproject.staging.yourdomain.com'];

// TracyDebugger
$config->tracy = [
  'localRootPath' => '/local/path/to/project/',
  'numLogEntries' => 100, // for RockMigrations
];

```

--------------------------------

### Get Server SSH Fingerprint

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Retrieve your server's SSH fingerprint to be used as the KNOWN_HOSTS secret in GitHub.

```bash
# Get your server's SSH fingerprint
ssh-keyscan your-server.com
```

--------------------------------

### Configure RockShell for Database Pull

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Set up the RockShell configuration in your project to enable pulling production databases. Uncomment 'remotePHP' if a specific PHP version is required on the server.

```php
$config->rockshell = [
  // 'remotePHP' => 'php81',  # uncomment if your server needs a specific PHP version
  'remotes' => [
    'production' => [
      'ssh' => 'DEMOUSER@DEMOSERVER',
      'dir' => '/path/to/your/documentroot/current',
    ],
  ],
];
```

--------------------------------

### Configure Tracy for Development

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/ProcessWire/config-tracy.txt

Set Tracy output mode to development and enable local development features. This configuration should only be used on local development environments.

```php
// tracy config
$config->tracy = [
  // use this only on local dev!!!!
  'outputMode' => 'development',
  'guestForceDevelopmentLocal' => true,
  'forceIsLocal' => true,

  'localRootPath' => getenv("DDEV_APPROOT"),
  'numLogEntries' => 100, // for RockMigrations
  // 'editor' => 'cursor://file/%file:%line',
];

```

--------------------------------

### Execute a Simple SQL Query

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/ProcessWire/pw-sql-query.txt

This snippet shows how to execute a basic SELECT query and fetch all results as objects. Remember to sanitize all user input before including it in queries.

```php
/*
 * SQL Database Query
 * do proper sanitization!!!
 */
$result = $this->database->query("${1:SELECT * FROM pages LIMIT 5}");
$${2:foo} = $result->fetchAll(PDO::FETCH_OBJ);
d($${2:foo});
```

--------------------------------

### Create Repeater Matrix Field

Source: https://github.com/baumrock/rockmigrations/blob/main/readme.md

Define a repeater matrix field with multiple types, each having its own set of fields. Also includes an example of how to remove a matrix type.

```php
$rm->createRepeaterMatrixField('repeater_matrix_field_name', [
   'label' => 'Field Label',
   'tags' => 'your tags',
   'repeaterAddLabel' => 'Add New Block',
   'matrixItems' => [
       'type1' => [
           'label' => 'Type1',
           'fields' => [
               'title' => [
                   'label' => 'Custom Title',
                   'description' => 'Custom description',
                   'required' => 1,
               ],
           ]
       ],
       'type2' => [
           'label' => 'Type2',
           'fields' => [
               'text' => [
                  'label' => 'Custom Label',
               ],
               'checkbox',
           ]
       ],
   ]
]);

// remove a matrix type from a matrix field
$rm->removeMatrixItem('repeater_matrix_field_name', 'name_of_type');
// do not forget to also remove the type from the 'matrixItems' array above
```

--------------------------------

### RockMigrations Deployment Script

Source: https://github.com/baumrock/rockmigrations/wiki/Deployment

Basic PHP script to initialize and run RockMigrations deployment. The second argument to the Deployment constructor specifies the local path for dry runs.

```php
<?php namespace RockMigrations;
require_once __DIR__."/modules/RockMigrations/classes/Deployment.php";
$deploy = new Deployment($argv, "/path/to/your/deployments");
// custom settings go here
$deploy->run();
```

--------------------------------

### Common Site Configuration

Source: https://github.com/baumrock/rockmigrations/wiki/Setting-up-different-config.php-files

This file holds settings common to all ProcessWire instances. It can be part of your git repository if no sensitive data is included. It also includes logic to load an instance-specific configuration file.

```php
<?php

namespace ProcessWire;

if (!defined("PROCESSWIRE")) die();

/** @var Config $config */

/*** SITE CONFIG *************************************************************************/
$config->useFunctionsAPI = false;
$config->usePageClasses = true;
$config->useMarkupRegions = false;
$config->prependTemplateFile = '_init.php';
$config->appendTemplateFile = '_main.php';
$config->templateCompile = false;

/*** INSTALLER CONFIG *******************************************************************/
$config->dbPort = '3306';
$config->dbCharset = 'utf8mb4';
$config->dbEngine = 'InnoDB';

$config->chmodDir = '0755'; // permission for directories created by ProcessWire
$config->chmodFile = '0644'; // permission for files created by ProcessWire

$config->timezone = 'Europe/Vienna';
$config->defaultAdminTheme = 'AdminThemeUikit';
$config->installed = 1675696905;

$config->debug = false;

$localConfig = __DIR__ . "/config-local.php";
if (is_file($localConfig)) include $localConfig;

```

--------------------------------

### Include Local Configuration

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Include environment-specific settings from a separate config-local.php file in your main config.php.

```php
// Split Config Pattern
// See https://processwire.com/talk/topic/18719--
require __DIR__ . "/config-local.php";
```

--------------------------------

### Test SSH Connections

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Verifies that SSH connections can be established using both the personal development key and the project deployment key. Successful testing is crucial before proceeding with automated deployments.

```bash
# Test personal key
ssh -i ~/.ssh/id_ed25519 user@server
```

```bash
# Test project key
ssh -i ~/.ssh/id_rockmigrations user@server
```

--------------------------------

### Include MagicPage Trait in Custom Page Class

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/magicpages/readme.md

Add the `use MagicPage;` statement to your custom page class to enable Magic Pages functionality. This is the initial setup required for your custom page class.

```php
<?php

namespace ProcessWire;

// if your IDE does not add this line
// automatically you need to add it manually!
use RockMigrations\MagicPage;

class DemoPage extends Page {
  use MagicPage;
}
```

--------------------------------

### Configure Files on Demand

Source: https://github.com/baumrock/rockmigrations/blob/main/readme.md

Instruct RockMigrations to download files on demand from a remote server. Supports basic HTTP authentication.

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

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

--------------------------------

### Configure Files on Demand with a URL

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/filesondemand/readme.md

Set the filesOnDemand configuration to a URL to enable the feature. ProcessWire will then automatically download referenced files that are missing locally from this URL.

```php
$config->filesOnDemand = 'https://my-live-site.com';
```

--------------------------------

### Transform Site Folder Structure

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Use RockShell to create an optimized folder structure for automated deployments, enabling versioning, rollbacks, and shared files.

```bash
php RockShell/rock rm:transform
```

--------------------------------

### Watch Module for Migrations with Force Option

Source: https://github.com/baumrock/rockmigrations/blob/main/readme.md

Watch a module for changes and force migrations to run, even for unchanged files. Useful for modules like RockMatrix.

```php
$rm = $this->wire->modules->get('RockMigrations');
if($rm) $rm->watch($this, true, ['force'=>true]);
```

--------------------------------

### Copy Files to Remote Server

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Synchronize project files from your local machine to the remote server using rsync over SSH.

```bash
# !!!!! MAKE SURE YOU ARE IN THE PROJECT ROOT !!!!!
cd /path/to/your/project

# copy content of current folder to remote server
# you can add additional excludes as needed
rsync -avz -e "ssh -i ~/.ssh/id_rockmigrations" \
  --exclude='.ddev' \
  --exclude='.git' \
  --exclude='.vscode' \
  --exclude='.github' \
  ./ DEMOUSER@DEMOSERVER:/path/to/your/documentroot/
```

--------------------------------

### Import Database Dump on Remote Server

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Import a SQL database dump file into the remote database.

```bash
mysql your_db_name < /path/to/your/dump.sql
```

--------------------------------

### Enable RockMigrations VSCode Snippets

Source: https://github.com/baumrock/rockmigrations/wiki/Home

Add this configuration to your development config file to automatically copy VSCode snippets to the .vscode folder, enabling code suggestions for RockMigrations.

```php
$config->rockmigrations = [
  'syncSnippets' => true,
];
```

--------------------------------

### Dump Local Database

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Create a database dump for backup and later restoration on the remote server.

```bash
rockshell db:dump
```

--------------------------------

### Verbose RockMigrations Deployment

Source: https://github.com/baumrock/rockmigrations/wiki/Deployment

Enables verbose output for the RockMigrations deployment script, useful for debugging CI/CD pipeline issues.

```php
$deploy->verbose();
$deploy->run();
```

--------------------------------

### Execute Migration Once

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/once/readme.md

Wrap a migration in the `once()` callback to ensure it runs only one time. The first parameter is a unique key, and the second is the callable migration function.

```php
$rm->once("once-demo", function() {
  bd('I will be executed only once!');
});
```

--------------------------------

### Watch an Entire Directory for Changes

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Watch an entire directory for changes. Files within this directory will be migrated if they change.

```php
$rm->watch(__DIR__."/foo");
```

--------------------------------

### Watch YAML File

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Instruct RockMigrations to watch a specific YAML file for changes.

```php
$rm->watch("/your/file.yaml");
```

--------------------------------

### Migrate Custom Page Class with Template and Page Creation

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/custom-pageclass/readme.md

This snippet demonstrates how to define and migrate a custom page class. It includes creating a template, defining fields, tags, and an icon, and then creating a page using this template.

```php
<?php

namespace RockSettings;

use ProcessWire\Page;
use RockMigrations\MagicPage;

use function ProcessWire\rockmigrations;

class SettingsPage extends Page
{
  use MagicPage;

  const tpl = "rocksettings";
  const prefix = "rocksettings_";

  public function migrate()
  {
    $rm = rockmigrations();
    $rm->migrate([
      'templates' => [
        self::tpl => [
          'fields' => [
            'title',
          ],
          'tags' => 'RockSettings',
          'icon' => 'cogs',
        ],
      ],
    ]);
    $rm->createPage(
      template: self::tpl,
      parent: 1,
      name: 'rocksettings',
      title: 'Settings',
      status: ['hidden'],
    );
  }
}
```

--------------------------------

### Run Migrations Manually via CLI

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Execute all RockMigrations scripts manually from the command line using the provided migrate.php script.

```bash
php site/modules/RockMigrations/migrate.php
```

--------------------------------

### Watch a Module for Changes

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Watch a ProcessWire module for changes and trigger its `migrate()` method when the module file is modified. The module must be autoloaded.

```php
// 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...');
}
```

--------------------------------

### Force Once Migration Execution

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/once/readme.md

To debug or test, you can force a `once()` migration to execute on every run by adding `true` as the third parameter. This is useful during development.

```php
$rm->once("once-demo", function() {
  bd('I will be executed as long as the third param is true!');
}, true);
```

--------------------------------

### Configure Files on Demand with a Callback

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/filesondemand/readme.md

Use a callback function to conditionally enable Files on Demand. This allows for specific files or fields to be excluded from automatic downloading, such as protected invoice PDFs.

```php
$config->filesOnDemand = function (Pagefile $file) {
  if ($file->field->name === RockInvoice::field_pdfs) return false;
  return 'https://my-live-site.com/';
};
```

--------------------------------

### Local Development Configuration for FilesOnDemand

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Add this configuration to your local site/config-local.php to enable FilesOnDemand, which automatically downloads production files only when needed.

```php

```

--------------------------------

### GitHub Actions Deployment Workflow

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Defines a GitHub Actions workflow to automate the deployment process using RockMigrations. It specifies the deployment target, credentials, and uses a reusable workflow from the RockMigrations repository.

```yaml
name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    # @main will use the latest version (main branch)
    # @v6.5.0 will use version 6.5.0
    uses: baumrock/RockMigrations/.github/workflows/deploy.yaml@main
    with:
      # document root (without /current and no trailing slash)
      PATH: ${{ vars.DEPLOY_PATH }}
      SSH_HOST: ${{ vars.SSH_HOST }}
      SSH_USER: ${{ vars.SSH_USER }}
      # SUBMODULES: true
      # PHP_COMMAND: "php81"
    secrets:
      SSH_KEY: ${{ secrets.SSH_KEY }}
      CI_TOKEN: ${{ secrets.CI_TOKEN }}
      KNOWN_HOSTS: ${{ secrets.KNOWN_HOSTS }}
```

--------------------------------

### Enable VSCode Snippet Sync

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Enable the `syncSnippets` option in your site configuration to use shipped VSCode snippets for RockMigrations.

```php
$config->rockmigrations = [
  "syncSnippets" => true,
];
```

--------------------------------

### Watch a Single File for Changes

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Watch a single file for changes. If the second parameter is `false`, the file is only watched and not executed as a migration script.

```php
$rm->watch(__FILE__, false);
```

--------------------------------

### DDEV Instance-Specific Configuration

Source: https://github.com/baumrock/rockmigrations/wiki/Setting-up-different-config.php-files

This file contains settings specific to a DDEV development environment. It should not be included in your git repository. It overrides common settings and configures database, salts, http hosts, and various modules.

```php
<?php

namespace ProcessWire;

/** @var Config $config */
$config->debug = true;
$config->advanced = true;
$config->dbName = 'db';
$config->dbUser = 'db';
$config->dbPass = 'db';
$config->dbHost = 'db';
$config->userAuthSalt = '1234';
$config->tableSalt = '1234';
$config->httpHosts = ['yourproject.ddev.site'];

// this will prevent logouts when using devtools mobile switch
$config->sessionFingerprint = false;

// RockFrontend
$config->livereload = 1;

// RockMigrations
// $config->filesOnDemand = 'https://your-live.site/';
$config->rockmigrations = [
  'syncSnippets' => true,
];

// TracyDebugger
$config->tracy = [
  'outputMode' => 'development',
  'guestForceDevelopmentLocal' => true,
  'forceIsLocal' => true,
  'localRootPath' => '/local/path/to/project/',
  'numLogEntries' => 100, // for RockMigrations
];

```

--------------------------------

### Custom Deployment with Translation Push

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy-advanced/readme.md

Use this snippet to define a custom deployment process that pushes specific directories, such as translation files, from the repository to the remote server. This ensures that changes made on development are reflected in staging and production environments.

```php
<?php

namespace RockMigrations;

$deploy = new Deployment($argv ?? []);

$deploy->push("site/assets/files/1030"); // german translations
$deploy->push("site/assets/files/1031"); // english translations

$deploy->run();

```

--------------------------------

### Configure RockShell Remotes

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/ProcessWire/config-rockshell.txt

Define remote server connections for RockShell. Specify SSH credentials and the project directory on the remote host.

```php
// rockshell config
$config->rockshell = [
  // 'remotePHP' => 'keyhelp-php81',
  'remotes' => [
    'staging' => [
      'ssh' => 'user@host.com',
      'dir' => '/path/to/webroot/current',
    ],
  ],
];
```

--------------------------------

### Enable FilesOnDemand Feature

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Configure the FilesOnDemand feature by providing the URL to your live site. This allows immediate access to production files and on-demand downloading.

```php
$config->filesOnDemand = 'https://your-live.site/';
```

--------------------------------

### Generate New User Auth Salt

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Generate a new, secure user authentication salt for the production environment.

```bash
openssl rand -base64 40
```

--------------------------------

### Watch Module for Changes with Force Option

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Watch a ProcessWire module for changes and trigger migrations, using the `force` option to ensure migration even if the module file itself hasn't changed. This is useful for modules like RockMatrix.

```php
$rm->watch($this, true, ['force'=>true]);
```

--------------------------------

### Watch a specific file for changes

Source: https://github.com/baumrock/rockmigrations/wiki/The-WATCH-feature

Use this method to explicitly tell RockMigrations to watch a file for changes. This is typically done during the initialization phase of a module.

```php
$rm->watch("/path/to/your/file");
```

--------------------------------

### Site-wide RockMigrations Constants File

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/config-migrations/readme.md

This file is auto-generated by RockMigrations and contains constants for site-wide fields and templates. Do not modify it manually.

```php
<?php

namespace ProcessWire;

// DO NOT MODIFY THIS FILE!
// IT IS AUTO-GENERATED BY ROCKMIGRATIONS!

class RockMigrationsConstants
{
  const field_from = 'from';
  const field_hours = 'hours';
  const field_notes = 'notes';
  const field_to = 'to';
  const template_effort = 'effort';
  const template_efforts = 'efforts';
  const template_todo = 'todo';
  const template_todos = 'todos';
}

```

--------------------------------

### Migrate Options Field

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Creates an options field with a predefined set of options, where each option has a value and a label.

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

--------------------------------

### Configure Files On Demand

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Set the URL for downloading files on demand. Supports basic HTTP authentication.

```php
$config->filesOnDemand = 'https://example.com';

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

--------------------------------

### Create Options Field with Multilang Labels

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Creates an options field and defines its options with multilingual labels for different languages.

```php
$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',
    ],
  ],
]);
```

--------------------------------

### Migrate Date Field

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Sets up a date field with a specific input format, datepicker behavior, and an option to default to the current date.

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

--------------------------------

### ProcessWire Module Boilerplate

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/ProcessWire/pw-createmodule.txt

This snippet provides the fundamental structure for a ProcessWire module. It includes the getModuleInfo method for module metadata and placeholders for initialization and configuration.

```php
<?php

namespace ProcessWire;

class Classname extends WireData implements Module, ConfigurableModule {

  public static function getModuleInfo() {
    return [
      'title' => 'Classname',
      'version' => '0.0.1',
      'summary' => 'Your module description',
      'autoload' => true,
      'singular' => true,
      'icon' => 'smile-o',
      'requires' => [],
      'installs' => [],
    ];
  }

  public function init() {
  }

  /**
   * Config inputfields
   * @param InputfieldWrapper $inputfields
   */
  public function getModuleConfigInputfields($inputfields) {
    return $inputfields;
  }

}
```

--------------------------------

### Push Language Translations to Deployment

Source: https://github.com/baumrock/rockmigrations/wiki/Deployment

Pushes the specified language translation folder to staging/production environments using the deployment script.

```php
$deploy->push('/site/assets/files/1025');
```

--------------------------------

### GitHub Actions Workflow for RockMigrations Deployment

Source: https://github.com/baumrock/rockmigrations/wiki/Deployment

This workflow deploys to specified paths based on the branch. Ensure PATHS are correctly formatted as JSON and do not have trailing slashes.

```yaml
name: Deploy via RockMigrations
on:
  push:
    branches:
      - main
      - dev
jobs:
  deploy:
    uses: baumrock/RockMigrations/.github/workflows/deploy.yaml@main
    with:
      # specify paths for deployment as JSON
      # syntax: branch => path
      # use paths without trailing slash!
      PATHS: '{
        "main": "/path/to/your/production/webroot",
        "dev": "/path/to/your/staging/webroot",
      }'
      SSH_HOST: your.server.com
      SSH_USER: youruser
      SUBMODULES: true
    secrets:
      CI_TOKEN: ${{ secrets.CI_TOKEN }}
      SSH_KEY: ${{ secrets.SSH_KEY }}
      KNOWN_HOSTS: ${{ secrets.KNOWN_HOSTS }}
```

--------------------------------

### ProcessWire Module Info Array

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/ProcessWire/pw-info.txt

Defines the core information for a ProcessWire module, including version, autoloading, and PHP requirements. The version is dynamically loaded from package.json.

```php
<?php

namespace ProcessWire;

$info = [
  'title' => '',
  'version' => json_decode(file_get_contents(__DIR__ . "/package.json"))->version,
  'summary' => '',
  'autoload' => true,
  'singular' => true,
  'icon' => 'magic',
  // requires php8.0 because of symfony yaml (also set in composer.json)
  'requires' => [
    'PHP>=8.0',
  ],
  'installs' => [],
];

```

--------------------------------

### Add Options Field

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/RockMigrations/rmf-options.txt

Defines an options field with a label, icon, and a set of key-value options. The 'type' must be set to 'options'.

```php
return [
  'type' => 'options',
  // 'inputfieldClass' => 'InputfieldRadios',
  'label' => '$1',
  'icon' => 'cubes',
  'options' => [
    10 => 'ONE|This is option one',
    20 => 'TWO',
    30 => 'THREE',
  ],
];
```

--------------------------------

### Create Project SSH Key

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Generates a project-specific SSH key pair for automated deployments. This key is intended to be stored securely within the project's repository and used by CI/CD systems like GitHub Actions.

```bash
ssh-keygen -t ed25519 -f ~/.ssh/id_rockmigrations -C "RM Deployment Key"
```

--------------------------------

### Test SSH Connection

Source: https://github.com/baumrock/rockmigrations/wiki/Deployment

Tests the SSH connection to the server using the configured private key. This verifies that passwordless SSH access is working correctly.

```bash
ssh -i ~/.ssh/id_rockmigrations user@your.server.com
```

--------------------------------

### Implement Custom Page List Label with MagicPage

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/pagelistlabel/readme.md

Use this pattern to define a custom label for a page in the ProcessWire admin. Ensure the `MagicPage` trait is used and the `pageListLabel()` method is implemented.

```php
<?php

namespace ProcessWire;

use RockMigrations\MagicPage;

class YourPage extends Page {
  use MagicPage;

  public function pageListLabel() {
    return "<span>foo</span> bar";
  }
}
```

--------------------------------

### Migrate File Field

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Sets up a file field with restrictions on the number of files, allowed extensions, and output format.

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

--------------------------------

### Add Config Inputfields to Module

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/ProcessWire/pw-configinputfields.txt

This method is used to add custom configuration inputfields to a ProcessWire module. It receives an InputfieldWrapper object and should return it after adding the desired fields.

```php
/**
  * Config inputfields
  * @param InputfieldWrapper $inputfields
  */
public function getModuleConfigInputfields($inputfields) {
  return $inputfields;
}
```

--------------------------------

### Add RockMoney Field Configuration

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/RockMigrations/rmf-money.txt

Use this configuration array to define a new RockMoney field. Ensure the 'type' is set to 'RockMoney' and provide a 'label' and 'icon'.

```php
// Add a RockMoney field via RockMigrations
return [
  'type' => 'RockMoney',
  'label' => '$1',
  'icon' => 'money',
];
```

--------------------------------

### Migrate PageClass with Child Templates

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/classloader/readme.md

This snippet demonstrates how to define child templates for a pageclass within the migrate method. It ensures that templates are created upfront, allowing for correct configuration even if classes are loaded in a different order.

```php
<?php

namespace RockCounter;

use ProcessWire\Page;

use function ProcessWire\rockmigrations;

class Root extends Page
{
  const tpl = 'rockcounter_root';
  const prefix = 'rockcounter_root_';

  public function migrate(): void
  {
    $rm = rockmigrations();
    $rm->migrate([
      'fields' => [],
      'templates' => [
        self::tpl => [
          'childTemplates' => [
            Users::tpl,
            Hits::tpl,
          ],
        ],
      ],
    ]);
  }
}
```

--------------------------------

### Create Field

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Create a new field with a specified type and label using RockMigrations.

```php
<?php namespace ProcessWire;
$rm->createField('foo', 'text');
```

--------------------------------

### GitHub Workflow for Auto-Release

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/releases/readme.md

Add this YAML file to your `.github/workflows` directory to enable automatic releases. It triggers on pushes to the main branch and uses the RockMigrations auto-release workflow.

```yaml
name: Auto-Release

# create a release when a commit is pushed to the main branch
on:
  push:
    branches:
      - main

# run the auto-release workflow from rockmigrations
jobs:
  auto-release:
    uses: baumrock/RockMigrations/.github/workflows/auto-release.yml@main
    # optionally set the email of the committer
    # with:
    #   email: "foo@example.com"
    secrets:
      token: ${{ secrets.CI_TOKEN }}
```

--------------------------------

### Add Integer Field Configuration

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/RockMigrations/rmf-integer.txt

This configuration defines an integer field. It specifies the field type as 'integer', sets a label, and assigns an icon.

```php
return [
  'type' => 'integer',
  'label' => '$1',
  'icon' => 'list-ol',
];
```

--------------------------------

### Integrating Module Constants Trait into Module

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/config-migrations/readme.md

This code shows how to include the generated RockMigrationsConstants trait in your module's main file to make the constants accessible.

```php
require_once __DIR__ . '/RockMigrationsConstants.php';
class MyModule extends WireData implements Module, ConfigurableModule
{
  use \MyModule\RockMigrationsConstants;
  // rest of the class
}

```

--------------------------------

### Read YAML File

Source: https://github.com/baumrock/rockmigrations/blob/main/readme.md

Read and parse data from a YAML file using RockMigrations.

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

--------------------------------

### Add Fieldset (Open+Close)

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/RockMigrations/rmf-fieldset.txt

Use this snippet to add a fieldset that includes both opening and closing tags. It requires a label and an icon.

```php
return [
  'type' => 'FieldsetOpen',
  'label' => '$1',
  'icon' => '$2',
];
```

--------------------------------

### Copy Public Key Content

Source: https://github.com/baumrock/rockmigrations/wiki/Deployment

Displays the content of the public SSH key, which can be manually copied and added to the 'authorized_keys' file on the remote server.

```bash
cat ~/.ssh/id_rockmigrations.pub
```

--------------------------------

### Wrap Fields with Fieldset

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/readme.md

Dynamically wrap form fields with a fieldset during form building. Allows runtime configuration of fields.

```php
// 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',
  ]);
})
```

--------------------------------

### ProcessModule Execute Method Boilerplate

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/ProcessWire/pw-process-execute.txt

This is a standard boilerplate for the execute method in a ProcessWire ProcessModule. It initializes a form, adds a markup field, and renders the form. Use this as a template for creating new process modules.

```php
// ProcessModule Execute Method Boilerplate
/**
 * $0
 */
public function execute$1() {
  $this->headline('$2');
  $this->browserTitle('$2');
  /** @var InputfieldForm $form */
  $form = $this->wire->modules->get('InputfieldForm');

  $form->add([
    'type' => 'markup',
    'label' => 'foo',
    'value' => 'bar',
  ]);

  return $form->render();
}
```

--------------------------------

### Create Personal SSH Key

Source: https://github.com/baumrock/rockmigrations/blob/main/docs/deploy/readme.md

Generates a personal SSH key pair for local development using the ed25519 algorithm. This key should remain on your local machine and is used for general development tasks.

```bash
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -C "your@email.com"
```

--------------------------------

### URL Field Configuration

Source: https://github.com/baumrock/rockmigrations/blob/main/snippets/RockMigrations/rmf-url.txt

Defines a URL field with a label, icon, and the TextformatterEntities formatter.

```php
return [
  'type' => 'URL',
  'label' => '$1',
  'icon' => 'link',
  'textformatters' => [
    'TextformatterEntities',
  ],
];
```