# Diff

> Git-compatible line diff for PHP

Package entry: `php-forge/diff`. Requires PHP `>=8.3`. Checked 2026-10-27. [View the entry in the package directory](</docs/packages/php-forge/diff/index.md>)

**Git-compatible line diff for PHP**

_A port of Git's default diff, indent heuristic included, plus a unified diff renderer, with no runtime dependencies._

## Features

![Feature Overview](/docs/_astro/features.F-h5lvi5.svg)

## Installation

```bash
composer require php-forge/diff:^0.1
```

## Quick start

`LineDiffer` implements `PHPForge\Diff\DifferInterface`. `diff()` splits both strings on `"\n"` and returns an ordered
list of `DiffLine` objects, each tagged with a `DiffOp`:

- `DiffOp::Remove`: the line exists only in `$old`.
- `DiffOp::Add`: the line exists only in `$new`.
- `DiffOp::Context`: the line exists on both sides.

Every input line appears exactly once, so dropping the `Add` lines reconstructs `$old` and dropping the `Remove` lines
reconstructs `$new`.

```php
use PHPForge\Diff\{DiffOp, LineDiffer};

$old = "apple\nbanana\ncherry";
$new = "apple\nblueberry\ncherry";

foreach ((new LineDiffer())->diff($old, $new) as $line) {
    echo match ($line->op) {
        DiffOp::Context => ' ',
        DiffOp::Remove => '-',
        DiffOp::Add => '+',
    } . $line->line . "\n";
}
```

```text
 apple
-banana
+blueberry
 cherry
```

`UnifiedDiffRenderer` turns two texts into a unified diff in Git's format, hunk headers and function context included,
without the `diff --git` and `index` lines.

```php
use PHPForge\Diff\UnifiedDiffRenderer;

$old = "apple\nbanana\ncherry\n";
$new = "apple\nblueberry\ncherry\n";

echo (new UnifiedDiffRenderer())->render($old, $new, 'a/fruit.txt', 'b/fruit.txt');
```

```text
--- a/fruit.txt
+++ b/fruit.txt
@@ -1,3 +1,3 @@
 apple
-banana
+blueberry
 cherry
```

## What you get

| Class                 | Result                                                      | Cost                                         |
| --------------------- | ----------------------------------------------------------- | -------------------------------------------- |
| `LineDiffer`          | The edit script of `git diff` with its default settings     | O((N + M) · D) time, linear memory           |
| `UnifiedDiffRenderer` | The text of `git diff --unified=<n>` from the `---` line on | The injected differ plus one pass over edits |

N and M are the line counts of `$old` and `$new`, and D is the edit distance. Like Git, `LineDiffer` favours readable
scripts over the shortest one, so its edit count is not always minimal. Unlike Git, it has no cost limit, so on very
expensive inputs its script can differ from Git's. See the [algorithms guide](/docs/extensions/diff/algorithms/index.md) for the pipeline and
its trade-offs.

## Documentation

- 📚 [Installation guide](/docs/extensions/diff/installation/index.md)
- 🧮 [Algorithms guide](/docs/extensions/diff/algorithms/index.md)
- 💡 [Usage examples](/docs/extensions/diff/examples/index.md)
- 🧪 [Testing guide](/docs/extensions/diff/testing/index.md)
- 🤖 [AI assistance](/docs/extensions/diff/agents/index.md)

## AI assistance

AI agents: read the [documentation index](https://yii2-framework.github.io/docs/llms.txt) and fetch the Markdown version
of a page by appending `index.md` to its URL. The
[AI agents guide](https://yii2-framework.github.io/docs/project/ai-agents/) covers skill installation, client setup and
verification.

- 🤖 [`php-forge-diff` skill](/docs/extensions/diff/agents/index.md): Line edit scripts and unified diffs.

If hosted documentation does not match the installed revision or is unavailable, use the
[repository guides](#documentation), the [skill source](https://github.com/php-forge/diff/blob/main/skills/php-forge-diff/SKILL.md), the source PHPDoc and the
[changelog](https://github.com/php-forge/diff/blob/main/CHANGELOG.md).

## Our social networks

[Follow on X](https://x.com/Terabytesoftw)
[Follow on Facebook](https://www.facebook.com/wilmer.arambula.9)

## License

[License](https://github.com/php-forge/diff/blob/main/LICENSE)

## Package

- Source code and issues: [php-forge/diff](https://github.com/php-forge/diff). Star the repository if the package is useful to you.
- Composer package: [php-forge/diff](https://packagist.org/packages/php-forge/diff).
- Changelog: [CHANGELOG.md](https://github.com/php-forge/diff/blob/main/CHANGELOG.md).