PHP Diff

https://github.com/jfcherng/php-diff
Admin
A comprehensive PHP library for generating and rendering differences between two strings in multiple...
Tokens:16,386
Snippets:131
Trust Score:9.6
License:BSD-3-Clause
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start PHP development server

Source: https://github.com/jfcherng/php-diff/blob/v7/example/README.md

Run this command in the project root to start the PHP development server for the web demo. After starting, visit http://localhost:12388/demo_web.php in a browser.

```bash
composer run-script server
```

--------------------------------

### Install with Composer

Source: https://github.com/jfcherng/php-diff/blob/v7/README.md

Install the jfcherng/php-diff package via Composer. Requires PHP >= 8.3.0 and the iconv extension.

```bash
composer require jfcherng/php-diff
```

--------------------------------

### Run CLI demo

Source: https://github.com/jfcherng/php-diff/blob/v7/example/README.md

Execute this command in the example directory to run the CLI demo. It uses the demo_cli.php script.

```bash
php demo_cli.php
```

--------------------------------

### Unified Diff Format Example

Source: https://github.com/jfcherng/php-diff/blob/v7/README.md

Shows a sample diff in the Unified format, as described by the linked Wikipedia article. The example includes line additions, deletions, and context lines.

```diff
@@ -1,3 +1,4 @@
-<p>Hello World!</p>
+<div>Hello World!</div>
 ~~~~~~~~~~~~~~~~~~~
+Let's add a new line here.
 X
@@ -7,6 +8,5 @@
 N
-Do you know in Chinese, "金槍魚罐頭" means tuna can.
+Do you know in Japanese, "魚の缶詰" means fish can.
 This is just a useless line.
 G
-// remember to delete this line
 Say hello to my neighbors.
```

--------------------------------

### Context Diff Format Example

Source: https://github.com/jfcherng/php-diff/blob/v7/README.md

Shows a sample diff in the Context format, as described by the linked Wikipedia article. The example is hidden behind a collapsible details element and includes line additions, deletions, and context lines.

```diff
***************
*** 1,3 ****
! <p>Hello World!</p>
 ~~~~~~~~~~~~~~~~~~~
  X
--- 1,4 ----
! <div>Hello World!</div>
 ~~~~~~~~~~~~~~~~~~~
+ Let's add a new line here.
  X
***************
*** 7,12 ****
  N
! Do you know in Chinese, "金槍魚罐頭" means tuna can.
  This is just a useless line.
  G
- // remember to delete this line
  Say hello to my neighbors.
--- 8,12 ----
  N
! Do you know in Japanese, "魚の缶詰" means fish can.
  This is just a useless line.
  G
  Say hello to my neighbors.
```

--------------------------------

### Basic diff calculation and rendering with Differ and RendererFactory

Source: https://github.com/jfcherng/php-diff/blob/v7/README.md

Shows how to compare files or strings using DiffHelper, or use Differ and RendererFactory for custom rendering. Includes configuration of DifferOptions and RendererOptions. The example uses the 'Unified' renderer and demonstrates JSON rendering for HTML output.

```php
<?php

include __DIR__ . '/vendor/autoload.php';

use Jfcherng\Diff\Differ;
use Jfcherng\Diff\DiffHelper;
use Jfcherng\Diff\Factory\RendererFactory;
use Jfcherng\Diff\Options\DifferOptions;
use Jfcherng\Diff\Options\RendererOptions;
use Jfcherng\Diff\Renderer\RendererConstant;

$oldFile = __DIR__ . '/example/old_file.txt';
$newFile = __DIR__ . '/example/new_file.txt';

$old = 'This is the old string.';
$new = 'And this is the new one.';

// renderer class name:
//     Text renderers: Context, JsonText, Unified
//     HTML renderers: Combined, Inline, JsonHtml, SideBySide
$rendererName = 'Unified';

// the Differ options
$differOptions = new DifferOptions(
    // show how many neighbor lines; Differ::CONTEXT_ALL shows the whole file
    context: 3,
    // ignore case difference
    ignoreCase: false,
    // ignore line ending difference
    ignoreLineEnding: false,
    // ignore whitespace difference
    ignoreWhitespace: false,
    // if the input sequence is too long, give up (especially for char-level diff)
    lengthLimit: 2000,
    // when inputs are identical, render the whole content rather than an empty result
    fullContextIfIdentical: false,
);

// the renderer options
$rendererOptions = new RendererOptions(
    // how detailed the rendered HTML in-line diff is? (none, line, word, char)
    detailLevel: 'line',
    // renderer language: eng, cht, chs, jpn, ...
    // or an array which has the same keys with a language file
    // check the "Custom Language" section in the readme for more advanced usage
    language: 'eng',
    // show line numbers in HTML renderers
    lineNumbers: true,
    // show a separator between different diff hunks in HTML renderers
    separateBlock: true,
    // show the (table) header
    showHeader: true,
    // render spaces/tabs as <span class="ch sp"> </span> tags (visualised via CSS)
    spaceToHtmlTag: false,
    // convert consecutive spaces to &nbsp; in HTML output
    spacesToNbsp: false,
    // HTML renderer tab width (negative = do not convert into spaces)
    tabSize: 4,
    // Combined renderer: merge replace-blocks whose changed ratio is at or below this threshold (0–1)
    mergeThreshold: 0.8,
    // Unified/Context renderers CLI colorization:
    // RendererConstant::CLI_COLOR_AUTO   = colorize if possible (default)
    // RendererConstant::CLI_COLOR_ENABLE = force colorize
    // RendererConstant::CLI_COLOR_DISABLE = force no color
    cliColorization: RendererConstant::CLI_COLOR_AUTO,
    // JSON renderer: emit op tags as human-readable strings instead of ints
    outputTagAsString: false,
    // JSON renderer: flags passed to json_encode()
    // see https://www.php.net/manual/en/function.json-encode.php
    jsonEncodeFlags: \JSON_UNESCAPED_SLASHES | \JSON_UNESCAPED_UNICODE,
    // word-level diff: adjacent segments joined by these characters are merged into one
    // e.g. "<del>good</del>-<del>looking</del>" → "<del>good-looking</del>"
    wordGlues: ['-', ' '],
    // return this string verbatim when the two inputs are identical; null = renderer default
    resultForIdenticals: null,
    // extra CSS classes added to the diff container <div> in HTML renderers
    wrapperClasses: ['diff-wrapper'],
);

// one-line simply compare two files
$result = DiffHelper::calculateFiles($oldFile, $newFile, $rendererName, $differOptions, $rendererOptions);
// one-line simply compare two strings
$result = DiffHelper::calculate($old, $new, $rendererName, $differOptions, $rendererOptions);
// or even shorter if you are happy with default options
$result = DiffHelper::calculate($old, $new, $rendererName);

// custom usage
$differ = new Differ(explode("\n", $old), explode("\n", $new), $differOptions);
$renderer = RendererFactory::make($rendererName, $rendererOptions); // or your own renderer object
$result = $renderer->render($differ);

// use the JSON result to render in HTML
$jsonResult = DiffHelper::calculate($old, $new, 'Json'); // may store the JSON result in your database
$htmlRenderer = RendererFactory::make('Inline', $rendererOptions);
$result = $htmlRenderer->renderArray(json_decode($jsonResult, true));
```
```

--------------------------------

### Before (v6): Renderer options as plain array

Source: https://github.com/jfcherng/php-diff/blob/v7/UPGRADING/UPGRADING_v7.md

Shows the v6 way of passing renderer options as an associative array to RendererFactory::make(). This is the 'Before' example for the breaking change to RendererOptions.

```php
<?php

$renderer = RendererFactory::make('Inline', [
    'detailLevel' => 'line',
    'language' => 'eng',
    'lineNumbers' => true,
    'separateBlock' => true,
    'showHeader' => true,
    'spacesToNbsp' => false,
    'tabSize' => 4,
    'mergeThreshold' => 0.8,
    'cliColorization' => RendererConstant::CLI_COLOR_AUTO,
    'outputTagAsString' => false,
    'jsonEncodeFlags' => JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE,
    'wordGlues' => ['-', ' '],
    'resultForIdenticals' => null,
    'wrapperClasses' => ['diff-wrapper'],
]);
```

--------------------------------

### Before (v6): Differ options as plain array

Source: https://github.com/jfcherng/php-diff/blob/v7/UPGRADING/UPGRADING_v7.md

Shows the v6 way of passing Differ options as an associative array to the Differ constructor. This is the 'Before' example for the breaking change to DifferOptions.

```php
<?php

$differ = new Differ($old, $new, [
    'context' => 3,
    'ignoreCase' => false,
    'ignoreLineEnding' => false,
    'ignoreWhitespace' => false,
    'lengthLimit' => 2000,
    'fullContextIfIdentical' => false,
]);
```

--------------------------------

### Composer scripts for testing, analysis, formatting, and dev server

Source: https://github.com/jfcherng/php-diff/blob/v7/AGENTS.md

Run these Composer scripts to execute the project's main workflows: test runs PHPUnit, analyze runs Phan and PHPCS, fix auto-formats with PHP-CS-Fixer, and server starts a dev server at localhost:12388.

```bash
composer run-script test      # phpunit --verbose
composer run-script analyze   # phan --color && phpcs --colors -n
composer run-script fix       # php-cs-fixer fix --verbose (auto-format)
composer run-script server    # dev server at localhost:12388
```

--------------------------------

### After (v7): Renderer options as RendererOptions object

Source: https://github.com/jfcherng/php-diff/blob/v7/UPGRADING/UPGRADING_v7.md

Shows the v7 way of passing renderer options as a typed RendererOptions object with named arguments. This is the 'After' example for the breaking change to RendererOptions.

```php
<?php

use Jfcherng\Diff\Options\RendererOptions;

$renderer = RendererFactory::make('Inline', new RendererOptions(
    detailLevel: 'line',
    language: 'eng',
    lineNumbers: true,
    separateBlock: true,
    showHeader: true,
    spaceToHtmlTag: false,
    spacesToNbsp: false,
    tabSize: 4,
    mergeThreshold: 0.8,
    cliColorization: RendererConstant::CLI_COLOR_AUTO,
    outputTagAsString: false,
    jsonEncodeFlags: JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE,
    wordGlues: ['-', ' '],
    resultForIdenticals: null,
    wrapperClasses: ['diff-wrapper'],
));
```

--------------------------------

### After (v7): Differ options as DifferOptions object

Source: https://github.com/jfcherng/php-diff/blob/v7/UPGRADING/UPGRADING_v7.md

Shows the v7 way of passing Differ options as a typed DifferOptions object with named arguments. This is the 'After' example for the breaking change to DifferOptions.

```php
<?php

use Jfcherng\Diff\Options\DifferOptions;

$differ = new Differ($old, $new, new DifferOptions(
    context: 3,
    ignoreCase: false,
    ignoreLineEnding: false,
    ignoreWhitespace: false,
    lengthLimit: 2000,
    fullContextIfIdentical: false,
));
```

--------------------------------

### Override language translations with custom overrides

Source: https://github.com/jfcherng/php-diff/blob/v7/README.md

Use this snippet to override specific translations of an existing language by providing the base language code (e.g., 'eng') followed by an associative array of key-value overrides. The 'differences' key is replaced with 'Diff' in this example. Additional overrides can be added to the array as needed.

```php
$rendererOptions = [
  'language' => [
    // use English as the base language
    'eng',
    // your custom overrides
    [
      // use "Diff" as the new value of the "differences" key
      'differences' => 'Diff',
    ],
    // maybe more overrides if you somehow need them...
  ],
]
```

--------------------------------

### Combined Renderer Options

Source: https://github.com/jfcherng/php-diff/blob/v7/README.md

Sets the detail level to 'word' for the Combined renderer. This renderer is suitable for articles and always has no line number information.

```php
<?php $rendererOptions = ['detailLevel' => 'word'];
```

--------------------------------

### Inline Renderer Options

Source: https://github.com/jfcherng/php-diff/blob/v7/README.md

Sets the detail level to 'line' for the Inline renderer. This is the default detail level.

```php
<?php $rendererOptions = ['detailLevel' => 'line'];
```
Tokens:
Raw