← All 40 libraries

SugarDiff

SugarDiff

Unified-diff engine — hunks, writer, and patch scanner

component-package diff patch

SugarDiff code coverage

A unified-diff engine the whole ecosystem can share: LCS line diffing, numbered context hunks, a GNU diff -u writer, and a scanner that numbers the rows of any patch. Extracted from candy-code's BuildsUnifiedDiff trait (now a delegating consumer) and the DiffGutter region model (which still keeps its own copy today). First-party — there is no 1:1 Go counterpart.

Install

composer require sugarcraft/sugar-diff:@dev

Quickstart

use SugarCraft\Diff\Diff;
use SugarCraft\Diff\DiffOptions;
use SugarCraft\Diff\Reader\UnifiedScan;

$before = "Hello World\n";
$after  = "Hello PHP\n";
$diff = Diff::compute($before, $after);

$patchText = $diff->unified('file.txt');
echo $patchText;
// --- a/file.txt
// +++ b/file.txt
// @@ -1 +1 @@
// -Hello World
// +Hello PHP

// Immutable, fluent options — the defaults reproduce candy-code's hunk
// bodies and grouping (headers are GNU-faithful).
$wide = Diff::compute($before, $after, DiffOptions::new()
    ->withContextLines(10)
    ->withIgnoreWhitespace()
    ->withNoNewlineMarker()
    ->withDevNullOnEmptySide());

// Number the rows of an existing patch (gutter/viewer support):
foreach (UnifiedScan::lines($patchText) as $row) {
    // $row->old, $row->new, $row->fileHeader, $row->kind (ScanRowKind enum)
}

The model

Diffcompute() entry point; lines, hunks, per-side counts and final-newline facts; isEmpty/addedLines/removedLines/unified/hunkText.
Hunk / Line / LineKindOne @@ block; one numbered row; eq/del/ins. All immutable value objects.
Writer\UnifiedFormatRenders the GNU diff -u shape: headers (path labels quoted when they carry control bytes), @@ ranges with GNU count elision, opt-in "\ No newline" markers and /dev/null labels.
Writer\SideBySideFormat / SideBySideRowPairs a diff into [left?, right?] rows for split viewers — from a computed Diff or raw patch text, one shared pairing rule.
Reader\UnifiedScanWalks any rendered unified diff, honouring each hunk's declared counts and classifying every row with ScanRowKind — the gutter model without the gutter.

Use it for

Source

Try the quickstart →

API

ClassMethodDescription
Diffcompute(string|list<string> $before, string|list<string> $after, ?DiffOptions $options = null): selfLine-mode LCS diff; `degraded` reports the cell-budget fallback (candy-code defaults reproduced for hunk bodies and grouping)
Diffunified(string $oldPath, ?string $newPath = null): stringFull diff -u text with --- / +++ headers; the second argument names the new side only
DiffhunkText(): stringHunks only, no file headers
DiffisEmpty() / addedLines() / removedLines(): int|boolSummary counts
Hunkheader() / lines() / removedCount() / addedCount()The @@ block (GNU-elided single-line ranges), its rows, and -/+ row tallies
Line / LineKindkind / text / oldNumber / newNumber; marker() / toUnifiedRow()One numbered verbatim row; eq/del/ins vocabulary
DiffOptionswithContextLines(int) / withMaxLcsCells(int)Context window (DEFAULT_CONTEXT_LINES = 3) and LCS cell budget (DEFAULT_MAX_LCS_CELLS = 250 000, counted as the table's real (n+1)×(m+1) footprint)
DiffOptionswithIgnoreWhitespace() / withIgnoreCase()Fold comparisons; emitted rows keep original bytes
DiffOptionswithNoNewlineMarker() / withDevNullOnEmptySide()GNU annotations, opt-in (the marker only annotates STRING sides)
UnifiedFormatwrite(Diff, string $oldPath, ?string $newPath) / hunksOnly(Diff): stringThe writer behind Diff::unified()/hunkText(); NO_NEWLINE_ROW; path labels are control-byte-safe
SideBySideFormatrows(Diff) / fromUnified(string|list<string>): list<SideBySideRow>Split-view pairing; SideBySideRow->left/->right, isPaired()
UnifiedScanlines(string|list<string>): list<ScannedLine>Per-row old/new line numbers, fileHeader flag, and ScanRowKind; declared-count budgets, fail-closed boundaries (MAX_LINE_NUMBER_DIGITS caps start fields)
UnifiedScanfileHeaders(string|list<string>): list<bool> / rowsOf(string): list<string>Which rows start a new file; the writer-compatible row split