README

Introduction

When working with revisions of text one sometimes faces the problem that there are several revisions based off the same original text. Rather than choosing one and discarding the other we want to merge the two revisions.

Git does that already wonderfully. In a php application we want a simple tool that does the same. There is the xdiff PECL extension which has the xdiff_string_merge3 function. But xdiff_string_merge3 does not behave the same way as git and xdiff may not be available on your system.

PhpMerge is a small library that solves this problem. There are two classes: \PhpMerge\PhpMerge and \PhpMerge\GitMerge that implement the \PhpMerge\PhpMergeInterface which has just a merge method.

PhpMerge uses SebastianBergmann\Diff\Differ to get the differences between the different versions and calculates the merged text from it. GitMerge uses Gitonomy\Git\Repository or Symplify\GitWrapper\GitWrapper, writes the text to a temporary file and uses the command line git to branch, add and merge the text. Using GitMerge is not recommended for performance reasons, but if you want to merge with git then this is the simplest way.

Usage

Simple example:

use PhpMerge\PhpMerge;

// Create a merger instance.
$merger = new PhpMerge();

// Get the texts to merge.
$original = <<<'EOD'
unchanged
replaced
unchanged
normal
unchanged
unchanged
removed

EOD;

$version1= <<<'EOD'
added
unchanged
replacement
unchanged
normal
unchanged
unchanged

EOD;

$version2 = <<<'EOD'
unchanged
replaced
unchanged
normal??
unchanged
unchanged

EOD;

$expected = <<<'EOD'
added
unchanged
replacement
unchanged
normal??
unchanged
unchanged

EOD;

$result = $merger->merge($original, $version1, $version2);
// $result === $expected;

With merge conflicts:

// Continuing from before with:
use Phpmerge\MergeException;
use PhpMerge\MergeConflict;


$conflicting = <<<'EOD'
unchanged
replaced
unchanged
normal!!
unchanged
unchanged

EOD;

try {
    $merger->merge($original, $version2, $conflicting);
} catch (MergeException $exception) {
    /** @var MergeConflict[] $conflicts */
    $conflicts = $exception->getConflicts();

    $original_lines = $conflicts[0]->getBase();
    // $original_lines === ["normal\n"];
    
    $version2_lines = $conflicts[0]->getRemote();
    // $version2_lines === ["normal??\n"];
    
    $conflicting_lines = $conflicts[0]->getLocal();
    // $conflicting_lines === ["normal!!\n"];
    
    $line_number_of_conflict = $conflicts[0]->getBaseLine();
    // $line_number_of_conflict === 3; // Count starts with 0.
    
    // It is also possible to get the merged version using the first version
    // to resolve conflicts.
    $merged = $exception->getMerged();
    // $merged === $version2;
    // In this case, but in general there could be non-conflicting changes.
    
    $line_in_merged = $conflicts[0]->getMergedLine();
    // $line_in_merged === 3; // Count starts with 0.
}

Using the command line git to perform the merge:

use PhpMerge\GitMerge;

$merger = new GitMerge();

// Use as the previous example.

Installation

PhpMerge can be installed with Composer by adding the library as a dependency to your composer.json file.

{
    "require": {
        "bircher/php-merge": "~4.0"
    }
}

To use the command line git with GitMerge:

{
    "require": {
        "bircher/php-merge": "~4.0",
        "gitonomy/gitlib": "^1.3"
    }
}

or with the deprecated symplify/git-wrapper

{
    "require": {
        "bircher/php-merge": "~4.0",
        "symplify/git-wrapper": "^9.1|^10.0"
    }
}

Please refer to Composer's documentation for installation and usage instructions.

Maintenance

This library is feature complete. This means it does the thing I set out to do. But of course the code doesn't exist in a vacuum and the php ecosystem keeps changing. Most notably Sebastian keeps adopting new php language features in our dependency sebastian/diff and drops support for older php versions. This means that new major versions are tagged and composer doesn't want to install bircher/php-merge on systems that updated sebastian/diff. So far it has mostly been pretty easy to just update composer.json, but I have not always noticed straight away because this library is not my primary focus, and so it would seem that the project is abandoned. Over the years people have forked the library as it is their right to do under the MIT license. Usually between the holidays and the new year I check the forks and merge the contributions back to the library. While it would probably be more speedy to contact me, I do appreciate your contributions also this way.

Difference to ~3.0

In the ~4.0 version we switch from cpliakas/git-wrapper to symplify/git-wrapper or gitonomy/gitlib since the former is deprecated. This update means that there is no change when only using PhpMerge\PhpMerge.

bircher / php-merge

Maintainers

Details