Jolitypo Laravel Package

Technical Evaluation

Architecture fit. Jolitypo is a framework-agnostic, single-purpose PHP text transformer with no Laravel coupling, no service container assumptions, and no database or queue dependencies. That makes it a clean fit as an edge-of-pipeline concern rather than a core domain dependency: it belongs in the presentation/serialization layer (render-time), not in the persistence layer. The natural seam is a thin application service (TypographyFormatter) behind an interface, so the vendor class never leaks into controllers, Blade templates, or domain models. This keeps the blast radius small if the package is abandoned or replaced.

Integration feasibility. Low engineering effort: composer require, a config file, a service provider binding, and a Blade directive or formatter call. The hard part is not wiring — it is deciding where in the content lifecycle to apply it and proving it does not corrupt markup. HTML-safe processing is the package's core promise and also its primary technical risk; any HTML-aware string rewriter can mangle attributes, inline scripts, JSON-LD, <pre>/<code> blocks, or malformed markup. Verify behavior against the actual content shapes in our system (CMS rich text, Markdown-rendered HTML, email templates, generated PDFs) before committing.

Technical risk.

• HTML fidelity: unknown parser behavior on malformed or partial HTML, contenteditable fragments, attributes containing quotes/URLs, and embedded JSON. Must be tested, not assumed.
• Sanitization ordering: if it runs after our HTML sanitizer it may reintroduce or reorder content; if before, it may alter text the sanitizer depends on. Order must be explicitly defined and tested.
• Storage vs. render: writing corrected text changes the source of truth, breaks round-trip editing, shifts byte length (NBSP, entities), and desynchronizes full-text search. Render-time keeps data clean but costs CPU per request and can leak into API responses.
• Machine-readable surfaces: transforming JSON API payloads, webhook bodies, signatures/HMAC inputs, or idempotency keys would be a correctness bug, not a polish improvement.
• PDF/email glyph coverage: curly quotes, em dashes, and narrow no-break spaces require font support; missing glyphs produce tofu boxes in invoices and transactional email.
• Maturity signals: 352 stars and a recent release indicate active but niche adoption; MIT license is fine, but it is effectively a single-vendor dependency with no SLA.

Key questions.

1. Which surfaces (public web, email, PDF, API, admin UI) and which locales are in scope for phase one?
2. Is output guaranteed idempotent — does running it twice produce identical bytes?
3. Does it preserve HTML exactly outside text nodes, including <script>, <style>, <pre>, <code>, and comments?
4. What is the performance envelope on a 100–200 KB rendered page, and does it scale linearly?
5. How is locale determined — explicit argument, per-request app locale, or auto-detection? What happens with mixed-language content?
6. What are the PHP version and extension requirements (mbstring, intl), and do they match every environment we deploy to?
7. Does the maintainer publish a security policy and a predictable release cadence?
8. Do our PDF fonts and email clients render the target glyph set correctly?

Integration Approach

Stack fit. Composer-installable, PSR-compatible, no framework assumptions — compatible with any Laravel version whose PHP constraint the package satisfies. Fit is high for Laravel because the framework gives us the three things the package lacks: configuration management, locale resolution, and a place to put the wrapper. Recommended shape:

• config/typography.php — enabled flag, per-surface allowlist, locale map, excluded tags.
• App\Support\Typography\TypographyFormatter — interface plus adapter wrapping the vendor API; only this class imports vendor namespaces.
• TypographyServiceProvider — binds the interface, publishes config.
• Optional Blade directive (@typography) for template-level opt-in, deliberately not a global middleware.

Migration path. There is no data migration if we adopt render-time transformation; that is the recommended starting posture. If write-time normalization is later justified (e.g., for search consistency), treat it as a separate project: dry-run batch job, diff report per content type, editorial sign-off, backfill in cohorts, and a reversible flag. Never combine adoption of the library with a data rewrite in the same release.

Compatibility. Confirm the package's PHP constraint against the lowest PHP version in production, and confirm intl/mbstring are present in CI, staging, and all runtime images (including queue workers and PDF generators). Pin an exact version in composer.json; do not use a floating constraint for a rendering-affecting dependency.

Sequencing.

1. Spike (1–2 days): run the library against a representative corpus — CMS articles, emails, PDF sources, edge-case markup — and diff output. Gate on zero structural HTML changes.
2. Golden-file test suite: snapshot fixtures per locale and per content shape, including negative cases (code blocks, scripts, attributes).
3. Wrapper + config + feature flag: ship the abstraction with the feature disabled.
4. First surface: a single low-risk, high-visibility channel (e.g., French CMS article body rendering) at render time only.
5. Second surface: transactional email templates, after confirming encoding and client rendering.
6. Third surface: PDF generation, contingent on font glyph audit.
7. Defer: API responses, user-generated comments, and any write-time storage decision until the first three surfaces have run clean for a full release cycle.

Operational Impact

Maintenance. Low code footprint, but ownership is real: someone must track upstream releases, re-run golden tests on upgrade, and hold a fork-or-replace contingency. Budget a recurring half-day per quarter plus upgrade testing. Because only the adapter class imports the vendor namespace, replacement cost is bounded to one file and one test suite.

Support. No vendor SLA; support is internal. Document the wrapper, the locale map, and the exclusion rules in the runbook. Editorial stakeholders — not just engineers — need to own the typographic rules per locale, since "correct" French spacing is a content policy decision, not a code decision.

Scaling. Transformation is CPU-bound per request. For page rendering, measure p95 latency impact; if material, cache transformed output keyed by hash(content) + locale + library version. Batch surfaces (bulk exports, newsletter sends, PDF backfills) should run the transform in queue workers with chunking rather than in the request path. Watch memory on large HTML documents if the library builds a full parse tree.

Failure modes to instrument and gate.

• Broken HTML or dropped attributes — detect via structural diff assertions in CI and a sampled production diff monitor.
• Mangled inline scripts/JSON — assert byte-equality on <script> contents.
• Tofu glyphs in PDFs and emails — visual QA per template per locale.
• Search/display mismatch if transformation is render-only — decide explicitly and document.
• Cache key drift from content-hash changes — version the cache key with the library version.
• Locale misapplication on mixed-language or user-overridden content — allow per-record override.
• Non-idempotent output causing churn in diffs, version history, and CDN caches.
• Sanitizer interaction regressions — keep an integration test that runs sanitizer + typography in the real order.

Ramp-up. Engineering ramp is a day: the API is simple and the wrapper is thin. QA and editorial ramp is the larger cost — roughly a week to build locale-specific acceptance criteria and review fixtures for French, English, and any other launch locale, plus a font audit for document generation. Plan for a soft launch behind a flag with a per-surface kill switch, and define success as: no structural HTML diffs, no rendering regressions in visual QA, and a measurable improvement in editorial review comments about typography.