Laravel Enum Translatable Laravel Package

Technical Evaluation

Architecture fit: EnumWrappable is a small, dependency-light trait that sits in the domain-model layer of a Laravel app — it turns loosely-typed input (request payloads, DB columns, queue payloads, third-party IDs) into a typed backed-enum case. That is exactly the kind of narrow, high-leverage utility that is cheap to adopt and cheap to remove. It does not impose an architectural pattern, does not touch the container, Eloquent, or HTTP, and therefore does not constrain application design. Fit is good wherever the codebase already uses backed enums as domain vocabulary; it is irrelevant (and should not be introduced) where enums are not already the idiom.

Integration feasibility: High. Adoption is per-enum via use EnumWrappable; and per-call-site via Status::wrap($value). No migrations, no config publishing implied by the notes, no service provider changes mentioned. The 2.4 work is almost entirely about making the static type honest (?static instead of ?BackedEnum), which directly improves PHPStan/Psalm results and IDE completion at call sites — a net reduction in integration friction for teams running static analysis at level 6+.

Technical risk: The risk in 2.4 is concentrated in one behavioral change, not in the type signature:

• Foreign-enum pass-through removed. Previously Status::wrap(Role::ADMIN) returned Role::ADMIN unchanged (an unrelated enum instance leaking out of a Status-typed API). Now it unwraps Role::ADMIN to its backing value and re-resolves against Status. This is a correctness fix but a runtime behavior change. Any caller that relied on the pass-through — including defensive instanceof checks, match arms written for mixed enum types, or serializers that tolerated heterogeneous enum output — will now receive a Status case, null, or a ValueError. This is a candidate breaking change shipped under a minor version.
• New ValueError throw path. Strict mode now throws where it previously returned the foreign enum. Uncaught, this surfaces as a 500 on any input path that feeds a foreign enum in. This needs auditing against HTTP/queue boundaries.
• Return type narrowing to ?static. Safe at runtime, but it can surface new static-analysis errors in downstream code that assigned the result to a ?BackedEnum variable or passed it into a wider-typed parameter. Expect a small wave of "fixed" CI failures on upgrade — noise, not breakage.
• '0'-backed fix. Strictly a bug fix (the empty() short-circuit was silently nulling valid '0' cases). Low risk, but it changes results for any enum with a '0' case — which is precisely the case where the old behavior was wrong.

Net: low systemic risk, non-trivial localized risk. The blast radius is proportional to how many call sites pass non-homogeneous or externally-sourced enum values.

Key questions:

1. Was the foreign-enum behavior change intentional in a minor release, and is the maintainer treating it as breaking? If yes, ask for a 3.0.0 or an explicit upgrade note; if the package is pre-1.0-adopted or internal-only, downgrade the concern.
2. Does wrap() accept BackedEnum|int|string|null in 2.4, or only the previously-supported inputs? The notes imply enums are now an accepted input class — confirm the full accepted-input contract.
3. What exactly triggers strict vs. non-strict mode — constructor/config/per-call flag? Is strict mode the default? This determines whether ValueError is an opt-in or opt-out hazard.
4. Is ValueError the intended public exception type, or a placeholder? For HTTP-facing code we would want a catchable, package-owned exception or guidance to wrap it.
5. Any deprecation of the old return contract, or is this a hard cutover with no shim?

Integration Approach

Stack fit: PHP 8.1+ (backed enums) and any Laravel version in support. No framework coupling means it also drops into non-Laravel PHP services and shared domain packages — useful if the enum vocabulary is shared across an API and a worker fleet.

Migration path: Treat 2.4 as a behavioral upgrade even though it is a patch-level bump from 2.3. Recommended path:

1. Pin to the exact 2.4.x in composer.json and upgrade in one PR rather than letting it float.
2. Grep the codebase for ::wrap( and classify each call site by argument source: (a) request/DB input that is same-type — safe; (b) values that could be a foreign enum — audit; (c) results fed into ?BackedEnum-typed variables or widened parameters — expect static-analysis churn.
3. For category (b), decide per site whether the new resolution semantics are what you want (usually yes) and add an explicit try/catch (ValueError) or confirm non-strict mode at HTTP/queue boundaries.
4. Run static analysis before and after; treat new errors as the type-narrowing signal, not as regressions.

Compatibility: Runtime-compatible with 2.3 for homogeneous inputs. Source-compatible for callers using the documented contract. Not behavior-compatible for callers relying on foreign-enum pass-through or on '0'-backed cases returning null. There is no indication of a compatibility shim or feature flag.

Sequencing:

1. Upgrade the dependency alone; run the full suite plus static analysis. Fix or explicitly baseline the type-narrowing fallout.
2. Audit and harden all foreign-enum call sites (ValueError handling at boundaries).
3. Only then extend usage — the corrected foreign-enum rule is genuinely useful for mapping between parallel enum vocabularies (e.g. HTTP status ↔ domain status), and the '0' fix removes a real footgun.
4. Update internal docs/README excerpts to reflect the new rule; the package README already documents it, so mirror it into onboarding material.

Operational Impact

Maintenance: Very low steady-state burden. Single-purpose trait, no runtime services, no config surface implied, no scheduled jobs, no storage. The upgrade cost is front-loaded into the audit described above and then amortizes to zero. The main ongoing cost is version discipline: a package that ships a behavior change in a minor release requires exact-version pinning and a changelog read on every bump — cheap, but it must be a habit rather than an assumption.

Support: Support load is developer-facing, not user-facing. Two predictable ticket classes: (a) "why did wrap() start throwing ValueError" — answer is the 2.4 foreign-enum rule plus strict mode; (b) "why does my '0' case now resolve instead of returning null" — answer is the empty() fix. Both are one-line answers once documented internally, but they will arrive if the upgrade is done quietly. Publish an internal upgrade note.

Scaling: Effectively free. Static method, in-process, no I/O, no shared state, constant-time resolution. Performance does not register against any realistic enum-cardinality workload. Nothing here becomes a bottleneck or a contention point as traffic grows.

Failure modes:

• Uncaught ValueError in strict mode — highest-severity failure mode; manifests as a 500 on any path that admits a foreign enum. Mitigation: catch at HTTP/queue/console boundaries, or run non-strict where the input is genuinely heterogeneous.
• Silent null in non-strict mode — a foreign enum with no match returns null rather than throwing. This is a footgun if downstream code assumes non-null. Mitigation: assert non-null at the boundary where the value is known to be required.
• Static-analysis drift — the ?static narrowing will break builds for teams treating analysis failures as CI-blocking. Mitigation: sequence the type fix into the same PR as the dependency bump.
• Upstream re-reversal — because this shipped in a minor version with no shim, a follow-up patch could plausibly adjust the foreign-enum rule again. Mitigation: pin exactly and read release notes before any bump.
• Assumption risk — this assessment rests on release notes only; no source, no version-support matrix, no CI status. Verify the accepted-input contract and the strict-mode default before committing to the migration.

Ramp-up: Near-zero for any PHP developer who knows backed enums. One example in the internal style guide — showing Status::wrap($input), the strict/non-strict distinction, and the foreign-enum resolution rule — is sufficient. The 2.4 changes to wrap() should be documented as the canonical behavior, since they now align the runtime with what the README already promised; older tribal knowledge about pass-through is wrong and should be retired explicitly.