Hyphenator Laravel Package

Technical Evaluation

What it is: org_heigl/hyphenator is a pure-PHP implementation of Liang's TeX hyphenation algorithm (the same algorithm behind hyph-utf8 patterns used by LaTeX, InDesign, and browsers). It is a language/text-processing library, not a Laravel package — there is no service provider, facade, config file, or published assets. Value is entirely in correctness of hyphenation for justified or narrow-column text.

Architecture fit:

• Strong fit only for a narrow class of features: PDF/invoice/report generation (DomPDF, mPDF, wkhtmltopdf HTML input), print-ready exports, email/newsletter rendering, fixed-width terminal or label output, and justified web typography with ­ insertion.
• Poor fit as a general-purpose utility. It does nothing useful in API/JSON responses, search indexing, or DB storage. Adding it to a request path without a concrete rendering problem is cargo-culting.
• Clean layering: the library exposes Hyphenator with pluggable tokenizers (whitespace, non-word, regex) and filters (simple, array, text). That composability maps well to a domain service such as App\Support\Typography\HyphenationService, keeping the vendor API out of controllers and Blade.

Integration feasibility:

• composer require org_heigl/hyphenator — trivial. No native extensions, no external services, MIT license, no telemetry.
• Gap: Laravel wiring is manual. Realistic effort is 1–2 developer-days for a service provider, config file, locale allow-list, pattern-directory publishing, and a cached/singleton binding. This is a small, well-bounded adapter — low risk.
• v3.2.0 materially changes two prior unknowns. The "hyph-utf8 patterns" feature (PR #68) suggests first-class support for the upstream hyph-utf8 pattern corpus rather than ad-hoc .tex files — potentially removing the bespoke pattern-sourcing burden. And "apply single-letter hyphenation patterns" (PR #69) is a correctness fix in exactly the quality-sensitive area flagged previously (short syllables, German compounds, proper nouns). Both need confirmation against the actual code before scoping, but they point the right direction.
• Version line correction: prior assessment hedged on "2.x compatibility." The changelog establishes an active 3.x line (v3.1.0 → v3.2.0). Target version confirmation is still required, but the ambiguity is now about the 3.x PHP matrix, not about which major to use.

Technical risk:

• Adoption signal is still weak but improving. Low star count and few dependents persist, so there is still no meaningful production peer review. However, v3.2.0 shows the first substantive external contribution (@peratoner-louis, two feature PRs) — a small but real bus-factor mitigation, and evidence the maintainer accepts outside code.
• CI and supply-chain posture improved. "Run CI also on PRs" (PR #70) and "Improve SupplyChain security via Actions" (PR #67) address two prior due-diligence items partially: PRs are now gated, and workflow Actions are pinned/hardened. This does not answer which PHP versions are in the CI matrix — that question stays open — but the "no CI" implication from the previous assessment should be retired.
• Release metadata anomaly — downgraded, not closed. The earlier concern about a future-dated release is now corroborated by a coherent public changelog with a linked compare URL. Treat tag history as plausible; still verify signatures/provenance on the tag itself, but this is no longer a red flag.
• New dependency surface: pattern licensing. If the package now bundles or sources hyph-utf8 patterns, note that upstream pattern files carry per-language licenses (LPPL, GPL, MIT, BSD variants). MIT on the PHP code does not automatically cover the pattern data. This is a new, concrete legal/compliance task — verify the license of each locale we intend to ship before distributing.
• Bus factor of one remains. Single maintainer. Mitigation unchanged: MIT + pure PHP + upstream pattern corpus means a fork or in-house patch is cheap. Vendor lock-in risk stays genuinely low.
• Pattern-file cost. Per-language .tex pattern sets are multi-megabyte and parsed at runtime. If v3.2.0's hyph-utf8 support bundles more locales by default, the naive per-request memory profile gets worse, not better. Loaded-locale discipline becomes more important, not less.
• Security surface is small but non-zero. No network, no eval, no unserialize. The only injection vector is a user-influenced locale or pattern path — enforce a strict allow-list and never interpolate request input into a filesystem path. The v3.2.0 supply-chain work reduces build-time risk; runtime risk is unchanged.
• Correctness risk. Still quality-sensitive, but v3.2.0's single-letter pattern handling reduces one known class of defects. There is still no test suite you inherit; you must own golden-file tests per locale — and now should explicitly include single-letter-break fixtures to lock in the new behavior.

Key questions for the maintainer/team:

1. Which version line? Resolved: 3.x is active. New: which PHP versions are exercised in the CI matrix added by PR #70, and is 8.3/8.4 covered?
2. Does the hyph-utf8 pattern feature (PR #68) introduce a configurable pattern directory, or does it hardcode resolution? Can we point it at a read-only path inside the container image?
3. What licenses accompany the bundled/sourced hyph-utf8 pattern files for our target locales (de, nl, sv, en)?
4. What is the per-instance memory footprint for the largest locale we need, after the v3.2.0 pattern changes?
5. Do we need hyphenation at render time at all, or can it be precomputed and stored?
6. Fallback policy for unsupported locales — silently skip, or fail loudly?

Integration Approach

Stack fit: Framework-agnostic library; Laravel fit is entirely up to our adapter. Recommended shape:

config/hyphenation.php          -> enabled locales, leftMin/rightMin, pattern path
app/Providers/HyphenationServiceProvider.php
app/Support/Typography/HyphenationService.php   (wraps Hyphenator)
app/Support/Typography/HyphenationManager.php   (per-locale memoization)
Blade directive: @hyphenate($text, 'de_DE')

Bind HyphenationService as a singleton so pattern parsing happens once per worker. Expose a hyphenate(string $text, string $locale, string $mode): string method returning either soft-hyphen (­) or <wbr> output, with the mode a config concern rather than a caller concern.

Migration path:

1. Spike (0.5 day): install v3.2.0 pinned, hyphenate a German and an English corpus, diff against a known-good reference (browser hyphens: auto, or LaTeX output). Explicitly test single-letter-break cases, since that behavior changed in this release.
2. License check (0.5 day, parallel): enumerate pattern files pulled in by the hyph-utf8 feature and confirm redistribution terms for each locale in scope. Escalate before shipping if any are incompatible.
3. Adapter (1 day): service provider, config, locale allow-list, singleton binding, unit tests with golden fixtures.
4. Pilot (0.5 day): one low-risk surface — generated PDF invoices or a single report template. Measure memory delta and render time.
5. Rollout: expand to remaining render surfaces; leave interactive web typography behind a feature flag so it can be disabled without a deploy.

Compatibility:

• Pin an exact version in composer.json — recommend 3.2.0 specifically. The release cadence is low but the 3.x line is now demonstrably active; still avoid ^ until a second 3.x patch confirms stability.
• Verify CI coverage against our runtime rather than assuming it; PR-gated CI (new in v3.2.0) protects upstream, not our PHP version.
• Verify mbstring availability in the container (hyphenation is multibyte-sensitive for de, nl, ru).
• Confirm no conflict with existing symfony/string or intl usage — ideally benchmark against Symfony\Component\String\UnicodeString + a locale-aware alternative before committing, since that avoids a new dependency entirely.
• Laravel Octane: singletons are safe here because pattern data is read-only after load; still verify no mutable state on the Hyphenator instance is shared across requests — re-verify after the v3.2.0 pattern refactor, since new pattern-loading paths are the most likely place for lazy-initialized mutable state to appear.

Sequencing: correctness spike → license check → adapter + tests → pilot on a non-customer-facing render → feature-flagged rollout. Do not sequence it before the rendering problem is confirmed; this is a solution that should follow a diagnosed typography defect, not lead one.

Operational Impact

Maintenance: Low absolute maintenance cost, and slightly lower than previously judged. Upstream now has PR-gated CI and a hardened Actions posture, so regressions are more likely to be caught before they reach us, and an external contributor has demonstrated the patch path is open. Budget roughly 2–4 hours per quarter to review upstream activity, plus a fork contingency. A "quiet fork" remains credible — document that decision now so it is not a crisis later. Add one recurring task: re-check pattern-file licenses on each minor bump, since the hyph-utf8 integration may pull in new locale data.

Support: No vendor, no SLA, no commercial backing. Internal support burden is the adapter plus the pattern data. Add runbook notes covering: which locales are enabled, where pattern files live, how to add a locale, and what happens when a locale is unsupported. Most incidents will be "text rendered without breaks" rather than exceptions — silent quality degradation, which is harder to detect than a crash. The v3.2.0 single-letter fix is a reminder that correctness can shift between versions; golden-file tests are the only reliable way to notice.

Scaling:

• CPU/memory: pattern files dominate. Per-worker footprint scales with the number of simultaneously loaded locales — 1 MB-scale for one locale, materially more for five. If the hyph-utf8 integration widens the default pattern set, assume a higher baseline until measured. Under PHP-FPM this is per-process; under Octane it is per-worker. Cap loaded locales to those actually used, or lazy-load with an LRU.
• Throughput: hyphenation is linear in text length and fast per word, but bulk jobs (10k invoices) should be queued, not done inline. Chunk text and consider memoizing repeated phrases (addresses, product names) via cache()->remember() keyed on sha1(locale . text).
• Do not put this in a hot API loop. It is a rendering-time concern.

Failure modes:

Ramp-up:

• Developer: low — half a day to be productive with the API; the tokenizer/filter model is understandable in an hour. The real learning curve is typographic judgment, not code.
• Ops/SRE: near zero if deployed as a plain Composer dependency; slight increase if pattern files are baked into the image (preferred) versus mounted. Confirm image build pulls a pinned version so pattern provenance is reproducible.
• Legal/compliance: new, small but non-zero — the hyph-utf8 feature introduces third-party data with per-language licensing. One review pass at adoption, then only on locale additions.
• Product/design: needs a decision on break strategy (­ vs <wbr> vs precomputed) and on which locales are in scope, since each added locale is a maintenance and memory commitment.
• Overall organizational cost is low; the risk is spending that low cost to solve a problem nobody has. Validate the rendering defect first — if the actual requirement is "stop long words overflowing narrow cells," CSS overflow-wrap/hyphens: auto may close it with zero dependencies. v3.2.0 makes the package a stronger candidate than before, but it does not make it a solution to an undiagnosed problem.