Diff Laravel Package

Getting Started

This package is a maintained fork of sebastian/diff, specifically created for use with ergebnis/composer-normalize. Since its primary purpose is tooling support — not general-purpose diffing — it’s best approached as a dependency you consume, not a library you build upon directly. Start by installing it via Composer if you’re using composer-normalize:

composer require --dev ergebnis/composer-normalize

This will pull in localheinz/diff as a transitive dependency. You won’t typically instantiate or use it directly — instead, it enables diff generation when composer normalize --dry-run or composer normalize runs. For context on how diffs are presented, see the OutputFormatter options in ergebnis/composer-normalize.

Implementation Patterns

You’ll rarely interact with localheinz/diff directly in application code. Its core value emerges in development workflows:

• Pre-commit hooks: Use it indirectly via composer-normalize in pre-commit (e.g., husky/lint-staged) to detect or auto-fix composer.json ordering, formatting, and stability preferences.
• CI pipelines: Add composer normalize --dry-run to your CI job to fail if composer.json isn’t normalized — the package’s diff engine powers the report showing what changed.
• Custom formatters: If building a tool that wraps composer-normalize, leverage the Patch and Diff classes (e.g., localheinz\Diff\Diff, localheinz\Diff\Output\UnifiedDiffOutputBuilder) to programmatically generate unified diffs from arrays of changes — though note that the API mirrors sebastian/diff closely.

Gotchas and Tips

• Don’t use this for new projects: The README explicitly warns: “Please use sebastian/diff instead.” Only install localheinz/diff if ergebnis/composer-normalize depends on it.
• PHP version compatibility: Despite supporting PHP 7.1–8.5 in its composer.json, the actual usable versions depend on sebastian/diff’s fork point. For modern PHP (8.1+), prefer sebastian/diff v4+ — this fork lags behind (last update Dec 2024, v1.2.0).
• No standalone CLI: Unlike sebastian/diff, this package has no CLI tool — diffs are consumed only via dependent tools like composer-normalize.
• Namespace changes: It retains the SebastianBergmann\Diff namespace (unlike some forks that rename), ensuring seamless drop-in replacement — but this is by design for compatibility.
• Debugging failures: If composer normalize misbehaves, inspect composer.json for malformed JSON or invalid references (e.g., ~ vs ^ version constraints). The diff output won’t show why something failed — only what would change.