README.md

Migrator

📦 Packagist | :floppy_disk: Repository | :bug: Issue tracker

A PHP library to perform migrations of files with a calculated diff between two code bases using three-way merge. Uses the cypresslab/gitelephant package for any Git operations and provides an interface for custom differ implementations.

🚀 Features

• Automatic file content migration
• Various implementations for source and target code base
• Interface for custom differ implementations

🔥 Installation

composer require cpsit/migrator

⚡ Usage

Command-line

vendor/bin/migrator [options] <base-directory> <source-directory> <target-directory>

Available options:

• --dry-run does not perform migrations, but only calculates and shows diff between code bases
• --verbose shows the calculated diff (implicitly enabled with --dry-run)

PHP

use CPSIT\Migrator\Diff;
use CPSIT\Migrator\Formatter;
use CPSIT\Migrator\Migrator;
use CPSIT\Migrator\Resource;

// Base contains all files that should be migrated
$base = new Resource\Collector\DirectoryCollector('/path/to/base/directory');

// Source and target define the code bases
// that are used to generate a diff
$source = new Resource\Collector\DirectoryCollector('/path/to/old/revision/files');
$target = new Resource\Collector\DirectoryCollector('/path/to/current/revision/files');

// Decide whether to actually perform migrations
// or just calculate a diff between the code bases
$performMigrations = true;

// Create differ, migrator and formatter
$differ = new Diff\Differ\GitDiffer();
$migrator = new Migrator($differ, $performMigrations);
$formatter = new Formatter\TextFormatter();

// Migrate files in your base directory
$diffResult = $migrator->migrate($source, $target, $base);

// Format diff
echo $formatter->format($diffResult);

🎢 Architecture

Lifecycle

In order to generate a diff between two code bases, you must provide two collections of resources. This, for example, can be a directory with template files of a previous revision compared to a directory with template files of a current revision. Additionally, you must provide a base directory containing all files to be migrated.

The migration is calculated by a differ. It will generate and apply a diff between both code bases and the provided base files using the three-way merge strategy.

Resource

All relevant code bases (source and target) must be represented by a Resource\Collector\CollectorInterface. The following implementations are currently available:

• ArrayCollector holds all relevant resources in a plain array.
• CallbackCollector provides all relevant resources through a configured callback function.
• ChainedCollector holds multiple collectors that are called one after the other.
• DirectoryCollector provides all relevant resources within a configured base directory.
• FileCollector provides a single file as resource collection.

Differ

Diffs are calculated by an implementation of Diff\Differ\Differ. The following implementations are currently available:

• GitDiffer uses the native Git binary to create diffs. This is done by the great library cypresslab/gitelephant.

Formatter

Formatters can be used to properly display a calculated Diff\DiffResult. Each formatter implements Formatter\Formatter. The following implementations are currently available:

• CliFormatter is used on command line. It displays the calculated diff with ANSI colors, targeting Symfony's console output.
• TextFormatter can be used in other contexts than command line, e.g. to properly display the calculated diff in case ANSI colors are not available.

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

⭐ License

This project is licensed under GNU General Public License 3.0 (or later).