cpsit/migrator

Composer package for migrating files with a calculated diff

0.1.6 2023-12-29 13:42 UTC

README

Screenshot

Migrator

Coverage Maintainability Tests CGL Latest Stable Version Total Downloads License

📦 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:

Differ

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

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).