Skip to content
Snippets Groups Projects
README.md 6.76 KiB
Newer Older
Sebastian Bergmann's avatar
Sebastian Bergmann committed
[![Latest Stable Version](https://poser.pugx.org/sebastian/diff/v)](https://packagist.org/packages/sebastian/diff)
[![CI Status](https://github.com/sebastianbergmann/diff/workflows/CI/badge.svg)](https://github.com/sebastianbergmann/diff/actions)
Sebastian Bergmann's avatar
Sebastian Bergmann committed
[![codecov](https://codecov.io/gh/sebastianbergmann/diff/branch/main/graph/badge.svg)](https://codecov.io/gh/sebastianbergmann/diff)

# sebastian/diff
Sebastian Bergmann's avatar
Sebastian Bergmann committed
Diff implementation for PHP, factored out of PHPUnit into a stand-alone component.

## Installation

You can add this library as a local, per-project dependency to your project using [Composer](https://getcomposer.org/):
Sebastian Bergmann's avatar
Sebastian Bergmann committed

```
composer require sebastian/diff
```

If you only need this library during development, for instance to run your project's test suite, then you should add it as a development-time dependency:

```
composer require --dev sebastian/diff
```
SpacePossum's avatar
SpacePossum committed
#### Generating diff

The `Differ` class can be used to generate a textual representation of the difference between two strings:

Philipp Scheit's avatar
Philipp Scheit committed
```php
use SebastianBergmann\Diff\Differ;
Sebastian Bergmann's avatar
Sebastian Bergmann committed
use SebastianBergmann\Diff\Output\UnifiedDiffOutputBuilder;

$differ = new Differ(new UnifiedDiffOutputBuilder);
print $differ->diff('foo', 'bar');
Philipp Scheit's avatar
Philipp Scheit committed
```

The code above yields the output below:
Sebastian Bergmann's avatar
Sebastian Bergmann committed

Gabriel Caruso's avatar
Gabriel Caruso committed
```diff
--- Original
+++ New
@@ @@
-foo
+bar
```
Sebastian Bergmann's avatar
Sebastian Bergmann committed
The `UnifiedDiffOutputBuilder` used in the example above generates output in "unified diff"
format and is used by PHPUnit, for example.
SpacePossum's avatar
SpacePossum committed

Sebastian Bergmann's avatar
Sebastian Bergmann committed
The `StrictUnifiedDiffOutputBuilder` generates output in "strict unified diff" format with
hunks,  similar to `diff -u` and compatible with `patch` or `git apply`.
SpacePossum's avatar
SpacePossum committed

Sebastian Bergmann's avatar
Sebastian Bergmann committed
The `DiffOnlyOutputBuilder` generates output that only contains the lines that differ.
SpacePossum's avatar
SpacePossum committed

Sebastian Bergmann's avatar
Sebastian Bergmann committed
If none of these three output builders match your use case then you can implement
`DiffOutputBuilderInterface` to generate custom output.
SpacePossum's avatar
SpacePossum committed

#### Parsing diff

The `Parser` class can be used to parse a unified diff into an object graph:

```php
use SebastianBergmann\Diff\Parser;
use SebastianBergmann\Git;

$git = new Git('/usr/local/src/money');

$diff = $git->getDiff(
  '948a1a07768d8edd10dcefa8315c1cbeffb31833',
  'c07a373d2399f3e686234c4f7f088d635eb9641b'
);

$parser = new Parser;

print_r($parser->parse($diff));
```

The code above yields the output below:

    Array
    (
        [0] => SebastianBergmann\Diff\Diff Object
            (
                [from:SebastianBergmann\Diff\Diff:private] => a/tests/MoneyTest.php
                [to:SebastianBergmann\Diff\Diff:private] => b/tests/MoneyTest.php
                [chunks:SebastianBergmann\Diff\Diff:private] => Array
                    (
                        [0] => SebastianBergmann\Diff\Chunk Object
                            (
                                [start:SebastianBergmann\Diff\Chunk:private] => 87
                                [startRange:SebastianBergmann\Diff\Chunk:private] => 7
                                [end:SebastianBergmann\Diff\Chunk:private] => 87
                                [endRange:SebastianBergmann\Diff\Chunk:private] => 7
                                [lines:SebastianBergmann\Diff\Chunk:private] => Array
                                    (
                                        [0] => SebastianBergmann\Diff\Line Object
                                            (
                                                [type:SebastianBergmann\Diff\Line:private] => 3
                                                [content:SebastianBergmann\Diff\Line:private] =>      * @covers SebastianBergmann\Money\Money::add
                                            )

                                        [1] => SebastianBergmann\Diff\Line Object
                                            (
                                                [type:SebastianBergmann\Diff\Line:private] => 3
                                                [content:SebastianBergmann\Diff\Line:private] =>      * @covers SebastianBergmann\Money\Money::newMoney
                                            )

                                        [2] => SebastianBergmann\Diff\Line Object
                                            (
                                                [type:SebastianBergmann\Diff\Line:private] => 3
                                                [content:SebastianBergmann\Diff\Line:private] =>      */
                                            )

                                        [3] => SebastianBergmann\Diff\Line Object
                                            (
                                                [type:SebastianBergmann\Diff\Line:private] => 2
                                                [content:SebastianBergmann\Diff\Line:private] =>     public function testAnotherMoneyWithSameCurrencyObjectCanBeAdded()
                                            )

                                        [4] => SebastianBergmann\Diff\Line Object
                                            (
                                                [type:SebastianBergmann\Diff\Line:private] => 1
                                                [content:SebastianBergmann\Diff\Line:private] =>     public function testAnotherMoneyObjectWithSameCurrencyCanBeAdded()
                                            )

                                        [5] => SebastianBergmann\Diff\Line Object
                                            (
                                                [type:SebastianBergmann\Diff\Line:private] => 3
                                                [content:SebastianBergmann\Diff\Line:private] =>     {
                                            )

                                        [6] => SebastianBergmann\Diff\Line Object
                                            (
                                                [type:SebastianBergmann\Diff\Line:private] => 3
                                                [content:SebastianBergmann\Diff\Line:private] =>         $a = new Money(1, new Currency('EUR'));
                                            )

                                        [7] => SebastianBergmann\Diff\Line Object
                                            (
                                                [type:SebastianBergmann\Diff\Line:private] => 3
                                                [content:SebastianBergmann\Diff\Line:private] =>         $b = new Money(2, new Currency('EUR'));
                                            )
                                    )
                            )
                    )
            )
    )

Note: If the chunk size is 0 lines, i.e., `getStartRange()` or `getEndRange()` return 0, the number of line returned by `getStart()` or `getEnd()` is one lower than one would expect. It is the line number after which the chunk should be inserted or deleted; in all other cases, it gives the first line number of the replaced range of lines.