Lingua Laravel Package

Technical Evaluation

Architecture fit

• whitecube/lingua is a stateless, dependency-light utility library that converts language identifiers between formats (ISO 639-1 two-letter, ISO 639-2/B and /T three-letter, ISO 639-3, and human-readable names). This is a pure domain concern, not infrastructure, so it slots naturally into a Laravel service layer or a small adapter class behind an interface.
• It is a strong fit for bounded, well-understood use cases: normalizing user locale preferences, canonicalizing language codes before persistence, rendering display names in admin UIs, parsing Accept-Language headers, and reconciling codes during CSV/API imports.
• It is a poor fit as a source of truth for complex i18n behavior — it is not a locale/BCP-47 library, does not do negotiation, pluralization, or region/script subtag handling, and should not be expected to.
• Because it is stateless and in-memory, it introduces no new runtime topology, no datastore, and no asynchronous surface area. Architectural risk is low; data-correctness risk is the real exposure.

Integration feasibility

• Standard Composer install; no framework lock-in implied by the description. If a Laravel service provider is not shipped, binding it as a singleton in AppServiceProvider is trivial.
• The public API is likely small (convert-to / convert-from style calls), meaning integration effort is measured in hours, not days.
• Testability is high: deterministic input/output with no I/O makes it easy to wrap in unit tests and property tests (round-trip conversion invariants).
• Verification checklist before commitment: confirm PHP 8.1/8.2/8.3 compatibility in composer.json, confirm PSR-4 autoloading, confirm whether the language tables cover ISO 639-3 fully (~7,800 entries) or only a curated subset, and confirm behavior for unmapped/ambiguous inputs (null vs. exception vs. silent fallback).

Technical risk

• Maintenance risk (high): last release November 2021, 44 stars, "repository unknown," score 0.4. This is effectively an unmaintained artifact with no verifiable upstream, no visible issue tracker, no security policy, and no release cadence. Supply-chain provenance cannot be audited.
• Runtime compatibility risk (medium-high): a PHP-7-era package may carry a ^7.x Composer constraint and PHP-8 deprecations. Unverified compatibility with current Laravel/PHP versions is the single most likely blocker.
• Data-completeness risk (medium): converters like this typically ship a hand-maintained table. Gaps or stale entries for deprecated codes, macrolanguages, and und/mul/zxx sentinels are common. Silent or lossy fallbacks are the dangerous failure mode.
• Abandonment risk (high): no upstream means no bug fixes, no CVE response, and no path to request new codes. Mitigation is cheap (fork/vendor), but must be planned for up front.
• Ambiguity risk (medium): ISO 639-2/B vs /T and bibliographic/terminological divergence is a classic source of subtle bugs; behavior must be pinned by tests, not assumed.

Key questions

1. Does the package declare PHP 8.x support and does it install cleanly under the target Laravel version without --ignore-platform-reqs?
2. Is a Laravel service provider / facade / config file included, or is it plain PHP only?
3. How complete and how current is the language table — full ISO 639-3, or a subset? What is the source of the data?
4. What is the documented behavior for unknown, deprecated, or ambiguous codes — exception, null, or best-effort fallback?
5. Is conversion bidirectional and lossless for the formats we actually use (639-1 ↔ 639-2B/T ↔ names)?
6. Who maintains it, and can the source be mirrored into our own VCS for supply-chain control?
7. What is the test coverage, and are there published round-trip guarantees?
8. Are there maintained alternatives already in the stack (symfony/intl, umpirsky/language-list) that would make this package redundant?

Integration Approach

Stack fit

• Fits a Composer-based Laravel 9/10/11 application as a leaf dependency. No database, queue, cache, or HTTP coupling, so it does not contend with existing architecture.
• Best positioned as an internal service — e.g., App\Support\Language\LanguageCodeConverter — that maps domain concepts to the library's API. Business code should never call the package directly.
• If symfony/intl is already transitively present (common in Laravel via other packages), evaluate whether it covers the same need before adding a second source of truth for language data.

Migration path

• Adopt behind our own interface from day one (convert(string $code, string $to): string), so the vendor can be swapped for a fork, an internal table, or symfony/intl without touching call sites.
• If PHP 8 compatibility fails, the fallback is a fork into an internal namespace (App\Vendor\Lingua) with the data tables preserved — the value of this package is the mapping data, not the code volume.
• If the table proves incomplete, extract the mapping into a config/PHP array we own and keep the library only as a thin lookup layer, or drop it entirely.
• Alternative replacements to hold in reserve: symfony/intl (region/language names), umpirsky/language-list (comprehensive code lists), or a generated static map from CLDR/ISO sources.

Compatibility

• Pin an exact version in composer.json (no ^), commit composer.lock, and mirror the package source into internal VCS or a private Composer repository to remove the "unknown repository" exposure.
• Validate under the actual CI matrix (PHP and Laravel versions in use), not just locally.
• Confirm behavior differences across PHP versions if the package relies on deprecated string/locale functions.

Sequencing

1. Spike (0.5–1 day): install in a throwaway branch, verify PHP/Laravel compatibility, exercise 20–30 representative codes including edge cases (und, mul, deprecated codes, bibliographic/terminological pairs).
2. Wrap (1–2 days): implement the internal interface plus a test suite of round-trip and negative cases; log unmapped codes as a metric.
3. Low-risk integration: apply to read-only/presentation paths first — admin display names, locale normalization at the request boundary, import validation warnings.
4. Write-path integration: only after the fallback metrics show a low unmapped rate, use it to canonicalize values before persistence.
5. Fork contingency: document the fork procedure and the alternative-library swap before the first production release, so abandonment is a scheduled task rather than an incident.

Operational Impact

Maintenance

• Expect zero upstream maintenance. Budget a named owner and roughly one to two days per year for dependency review, data-gap fixes, and PHP-version bumps. Treat the package as vendored code we maintain, not as a live dependency.
• No security-response channel exists; include it in SCA scanning and accept that any CVE will require an internal patch.
• Monitor for bit-rot on PHP major upgrades; this is the most likely scheduled work item.

Support

• Community-only, effectively none. Internal documentation and the wrapper's tests become the support surface. Onboarding should reference our interface, not the vendor docs.
• Keep a short ADR recording why the package was chosen, its known data gaps, and the designated replacement, so future maintainers do not have to re-derive the decision.

Scaling

• Negligible runtime cost: in-memory lookups, no I/O. Bind as a singleton so any lookup tables are loaded once per process, not per call.
• Watch memory only if full ISO 639-3 tables are loaded eagerly under PHP-FPM with large worker pools; lazy-load or compile to static arrays if profiling shows it.
• Horizontally scales trivially; no shared state.

Failure modes

• Unmapped code → exception or null propagating into user-facing flows; must be caught and defaulted with an explicit policy.
• Silent lossy conversion → a valid-but-ambiguous code mapped to the wrong language, persisting bad data. Highest-severity failure; guard with round-trip assertions and a reject-on-ambiguity rule at write boundaries.
• Case/whitespace sensitivity → en-US vs en-us, trailing spaces from CSV imports; normalize at the boundary, not inside the library call.
• Composer resolution failure on PHP upgrade → build breaks; pinned version plus a fork path contains the blast radius.
• Data staleness → codes added or deprecated after 2021 are absent; log every miss so gaps are visible rather than silent.

Ramp-up

• API surface is small; an engineer is productive in under half a day. The intellectual load is in ISO 639 semantics (B vs T, macrolanguages, sentinels), not in the package.
• Recommend a one-page internal note covering the wrapper contract, the ambiguity policy, and three worked examples. That note, not the vendor README, is what prevents misuse.

Overall recommendation Conditional adoption. The capability is genuinely useful and cheap to integrate, but the maintenance, provenance, and PHP-8 compatibility profile make direct, unwrapped usage unacceptable. Proceed only with: strict version pinning, an internal interface wrapper, a mirrored source, a mandatory compatibility spike, and a documented fork/replace exit. If the compatibility spike fails or the language table is materially incomplete, decline and implement the mapping internally or via symfony/intl — the effort is comparable to the mitigation work this package already requires.