README

Migrator

📦 Packagist | 💾 Repository | 🐛 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).

cpsit / migrator

Maintainers

Details