PHPackages                             cpsit/migrator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. cpsit/migrator

ActiveLibrary[File & Storage](/categories/file-storage)

cpsit/migrator
==============

Composer package for migrating files with a calculated diff

0.2.0(5mo ago)3351[1 issues](https://github.com/CPS-IT/migrator/issues)GPL-3.0-or-laterPHPPHP ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0CI passing

Since Mar 9Pushed 1mo ago5 watchersCompare

[ Source](https://github.com/CPS-IT/migrator)[ Packagist](https://packagist.org/packages/cpsit/migrator)[ RSS](/packages/cpsit-migrator/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (15)Versions (14)Used By (0)

[![Screenshot](docs/screenshot.png)](#-installation)

Migrator
========

[](#migrator)

[![Coverage](https://camo.githubusercontent.com/35c03480d2c95a103472744238c96a70a15d3f2b608e64cc20a8285bf7080142/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c73436f7665726167652f6769746875622f4350532d49542f6d69677261746f723f6c6f676f3d636f766572616c6c73)](https://coveralls.io/github/CPS-IT/migrator)[![Tests](https://github.com/CPS-IT/migrator/actions/workflows/tests.yaml/badge.svg)](https://github.com/CPS-IT/migrator/actions/workflows/tests.yaml)[![CGL](https://github.com/CPS-IT/migrator/actions/workflows/cgl.yaml/badge.svg)](https://github.com/CPS-IT/migrator/actions/workflows/cgl.yaml)[![Latest Stable Version](https://camo.githubusercontent.com/ff1689396e4974775a2b6107f6f3b65eb508edad2bf3cc36d7a8f0fb42b408c1/687474703a2f2f706f7365722e707567782e6f72672f63707369742f6d69677261746f722f76)](https://packagist.org/packages/cpsit/migrator)[![Total Downloads](https://camo.githubusercontent.com/fdbf63e78cfbc4e416a6b68e1009bed777936e976ce06a382df2aa03f33dbcd8/687474703a2f2f706f7365722e707567782e6f72672f63707369742f6d69677261746f722f646f776e6c6f616473)](https://packagist.org/packages/cpsit/migrator)[![License](https://camo.githubusercontent.com/80eb2a74512c526e5790a4ae6ef3dfa486df6adab667af6620417b3dd13b871b/687474703a2f2f706f7365722e707567782e6f72672f63707369742f6d69677261746f722f6c6963656e7365)](LICENSE)

📦 [Packagist](https://packagist.org/packages/cpsit/migrator) | 💾 [Repository](https://github.com/CPS-IT/migrator) | 🐛 [Issue tracker](https://github.com/CPS-IT/migrator/issues)

A PHP library to perform migrations of files with a calculated diff between two code bases using three-way merge. Uses the [`cypresslab/gitelephant`](https://packagist.org/packages/cypresslab/gitelephant) package for any Git operations and provides an interface for custom differ implementations.

🚀 Features
----------

[](#-features)

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

🔥 Installation
--------------

[](#-installation)

```
composer require cpsit/migrator
```

⚡ Usage
-------

[](#-usage)

### Command-line

[](#command-line)

```
vendor/bin/migrator [options]
```

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

[](#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
--------------

[](#-architecture)

### Lifecycle

[](#lifecycle)

In order to generate a diff between two code bases, you must provide two collections of [resources](#resource). 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](#differ). It will generate and apply a diff between both code bases and the provided base files using the [three-way merge](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#_basic_merging)strategy.

### Resource

[](#resource)

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

- [`ArrayCollector`](src/Resource/Collector/ArrayCollector.php) holds all relevant resources in a plain array.
- [`CallbackCollector`](src/Resource/Collector/CallbackCollector.php) provides all relevant resources through a configured callback function.
- [`ChainedCollector`](src/Resource/Collector/ChainedCollector.php) holds multiple collectors that are called one after the other.
- [`DirectoryCollector`](src/Resource/Collector/DirectoryCollector.php) provides all relevant resources within a configured base directory.
- [`FileCollector`](src/Resource/Collector/FileCollector.php) provides a single file as resource collection.

### Differ

[](#differ)

Diffs are calculated by an implementation of [`Diff\Differ\Differ`](src/Diff/Differ/Differ.php). The following implementations are currently available:

- [`GitDiffer`](src/Diff/Differ/GitDiffer.php) uses the native Git binary to create diffs. This is done by the great library [`cypresslab/gitelephant`](https://packagist.org/packages/cypresslab/gitelephant).

### Formatter

[](#formatter)

Formatters can be used to properly display a calculated [`Diff\DiffResult`](src/Diff/DiffResult.php). Each formatter implements [`Formatter\Formatter`](src/Formatter/Formatter.php). The following implementations are currently available:

- [`CliFormatter`](src/Formatter/CliFormatter.php) is used on command line. It displays the calculated diff with ANSI colors, targeting Symfony's console output.
- [`TextFormatter`](src/Formatter/TextFormatter.php) 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
----------------

[](#‍-contributing)

Please have a look at [`CONTRIBUTING.md`](CONTRIBUTING.md).

⭐ License
---------

[](#-license)

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

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance76

Regular maintenance activity

Popularity12

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 53.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~111 days

Recently: every ~190 days

Total

10

Last Release

160d ago

PHP version history (5 changes)0.1.0PHP ~8.1.0 || ~8.2.0

0.1.5PHP ~8.1.0 || ~8.2.0 || ~8.3.0

0.1.7PHP ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0

0.1.8PHP ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0

0.2.0PHP ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/144cefe55242b883c87cb537463f3ba75a0f8198fc5b602b50c838aae31fe7ee?d=identicon)[eliashaeussler](/maintainers/eliashaeussler)

![](https://www.gravatar.com/avatar/a664c83f7a6760600d2a325f751b2a206f686b3dcb2f1dce5655ead343dc5a24?d=identicon)[cps](/maintainers/cps)

---

Top Contributors

[![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (436 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (218 commits)")[![eliashaeussler](https://avatars.githubusercontent.com/u/16313625?v=4)](https://github.com/eliashaeussler "eliashaeussler (153 commits)")[![mteu](https://avatars.githubusercontent.com/u/2636487?v=4)](https://github.com/mteu "mteu (5 commits)")

---

Tags

composer-librarydiffmergemigrationpatcherphpthree-way-merge

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/cpsit-migrator/health.svg)

```
[![Health](https://phpackages.com/badges/cpsit-migrator/health.svg)](https://phpackages.com/packages/cpsit-migrator)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19562.3M1.3k](/packages/drupal-core)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[prestashop/prestashop

PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers.

9.0k15.4k](/packages/prestashop-prestashop)[sonata-project/media-bundle

Symfony SonataMediaBundle

4625.5M71](/packages/sonata-project-media-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)