cpsit / migrator
Composer package for migrating files with a calculated diff
Requires
- php: ~8.1.0 || ~8.2.0 || ~8.3.0
- cypresslab/gitelephant: ^4.5
- symfony/console: ^5.4 || ^6.0 || ^7.0
- symfony/filesystem: ^5.4 || ^6.0 || ^7.0
- symfony/finder: ^5.4 || ^6.0 || ^7.0
Requires (Dev)
- armin/editorconfig-cli: ^1.6 || ^2.0
- cpsit/php-cs-fixer-config: ^1.1
- ergebnis/composer-normalize: ^2.30
- friendsofphp/php-cs-fixer: ^3.29
- phpstan/extension-installer: ^1.2
- phpstan/phpstan: ^1.10
- phpstan/phpstan-phpunit: ^1.3
- phpstan/phpstan-strict-rules: ^1.5
- phpstan/phpstan-symfony: ^1.2
- phpunit/phpunit: ^10.1
- rector/rector: ^0.16 || ^0.17 || ^0.18
README
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 librarycypresslab/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).