Htmldiff Laravel Package

Technical Evaluation

Architecture fit. ssddanbrown/htmldiff is a framework-agnostic PHP library, not a Laravel package in the conventional sense: no service provider, no config file, no facade. It exposes a small object API that takes two HTML fragments and returns a display-ready HTML document with insertions/deletions marked up. For a Laravel codebase this is a low-ceremony fit — Composer autoloads it, and if we want container injection we write a thin binding ourselves. The absence of framework coupling is a genuine positive: it will not constrain Laravel upgrades or drag in transitive dependencies.

Integration feasibility. High on the technical axis, low on the confidence axis. Technically it is a composer require and three lines of code. The blockers are organizational and lifecycle-related:

• Archived upstream. The repository is marked archived and explicitly migrated to Codeberg. The Packagist entry likely still resolves, but there is no guarantee of future releases, PHP-version compatibility patches, or security response through the channel we would actually install from.
• Adoption signal is weak. 10 stars and a 0.07 score indicate near-zero community validation. There is no ecosystem of users to surface bugs or contribute fixes.
• Single-maintainer risk. This is effectively a bus-factor-of-one library authored as a component of a larger application (BookStack). It was likely extracted for that project's needs, not generalized for third-party consumption.
• Output is HTML by design. The library's core value — returning rendered HTML rather than a data structure — is also its main risk. Any diff output rendered into a Blade view must be treated as untrusted markup; we need a sanitization step and a clear stance on whether either input side can contain user-authored HTML.

Technical risk. Medium-to-high, concentrated in lifecycle rather than correctness. The algorithm itself is likely adequate for document-revision diffing (prose, markup, CMS content), which is the realistic use case. Risks worth naming: performance and memory on large or deeply nested documents, behavior on malformed/unbalanced HTML (common with user-edited content), multibyte and entity handling, and CSS/attribute-level changes being handled less gracefully than text nodes. MIT licensing removes legal friction and permits forking.

Key questions.

1. Is the Codeberg repository actively maintained, and will Packagist continue to receive releases from it? If not, this is a vendored fork from day one.
2. What is the actual maintenance delta between the archived GitHub tree and the current Codeberg head?
3. Does the diff engine preserve or mangle attributes, inline styles, and script/style blocks?
4. What are the measured time and memory ceilings at our largest realistic document size?
5. Which maintained alternative (caxy/php-htmldiff or similar) wins on a bake-off, and does either produce output we can trust without sanitization?
6. Who internally owns the fork if we adopt it?

Integration Approach

Stack fit. Good. It slots into the Laravel layer as a pure domain utility: a HtmlDiffService wrapper bound in a service provider, injected into the controller or job that renders version comparisons. Because it has no framework opinions, it can be swapped for an alternative behind the same interface with no changes to call sites. That interface is the single most important design decision here.

Migration path. Given the archived status, do not depend on the upstream package directly in composer.json long-term. The pragmatic path is:

1. Spike — install via Composer, run against three or four real document pairs from our own data (largest, messiest, most attribute-heavy).
2. Fork — if the spike passes, vendor the Codeberg head into a private repository under our namespace, or use a Composer VCS repository pointing at a pinned commit. Publishing a private fork gives us a place to patch PHP-version issues and a clear ownership record.
3. Wrap — expose one narrow interface (diff(string $old, string $new): string) and never call the library from application code directly. This is the hedge that makes replacement cheap.
4. Sanitize — pipe the returned HTML through an allowlist sanitizer before it touches a view, regardless of how trusted the inputs are.

Compatibility. Verify against the PHP versions in our support matrix (8.1–8.4 typical) before committing; an archived package will not have been tested past whatever PHP was current at the March 2024 release. Composer constraint should be pinned exactly, not ranged, since we control the source.

Sequencing. Spike and fork in the same sprint — do not adopt the upstream package "temporarily" and defer the fork, because that is how archived dependencies become permanent. Sanitization and the wrapper interface land before the first production call site. Any UI work (diff toggle, side-by-side view) comes after the service is proven on real data.

Operational Impact

Maintenance. Low routine cost, non-zero ownership cost. The codebase is small and single-purpose; a mid-level PHP developer can read all of it. Realistically we are adopting it, not consuming it — budget a few hours per PHP minor release to confirm it still runs, and a half-day if we ever need to patch it. No dependency tree means no supply-chain churn, which is a real advantage over heavier diff libraries.

Support. Effectively self-support. There is no vendor, no SLA, and the upstream channel has moved to a platform where the project may be dormant. Documentation is whatever the README says. Internal knowledge must be captured deliberately — a short ADR plus a runbook entry — because there is no external source to consult later.

Scaling. CPU- and memory-bound, not I/O-bound. Diffing is the kind of workload that degrades non-linearly with document size, so it belongs in a queued job with a timeout and a size guard, not in a synchronous request. Cache diff results keyed on the pair of revision hashes; revision comparisons are immutable, so cache hit rates should be high. If diffing is a core user-facing feature, set an explicit max-document threshold and degrade to a "changes too large to display" message rather than timing out.

Failure modes.

• Silent degradation — pathological input produces a slow, memory-hungry render that surfaces as a worker timeout rather than a clear error. Needs bounds and monitoring.
• Markup corruption — malformed HTML produces visually wrong or structurally broken output; users lose trust in the diff view quickly.
• Injection — unsanitized output rendered into Blade is an XSS vector if either revision contains user-supplied HTML.
• Upgrade break — a PHP minor release breaks the library and no upstream fix arrives. Mitigated by the fork.
• Encoding — multibyte content and HTML entities mishandled in comparison logic.

Ramp-up. Low. A developer unfamiliar with the package can be productive in under a day; the API is small and the wrapper interface means most engineers never touch the library itself. The real onboarding cost is the fork's ownership model — who merges vendor updates, who reviews patches — and that is an organizational decision to make at adoption time, not a technical one to discover later.

Recommendation. Adopt only if HTML diffing is a genuine product requirement, and adopt it as an internally owned fork behind a sanitizing wrapper with a queued, size-capped execution path. If the need is speculative, defer and revisit alongside a bake-off against maintained alternatives.