Enumeration Laravel Package

Technical Evaluation

Architecture fit. somnambulist/enumeration is a plain-PHP value-object library that predates native PHP 8.1 enums. It provides typed enumeration classes (single-value enums, multiton-style keyed sets, and composite value objects) intended to replace magic strings/ints in domain models. Architecturally it slots in cleanly for teams that want class-based constants with behaviour (methods, validation, comparison, serialization) attached. For a Laravel codebase, that means it can back Eloquent castable attributes, form request validation rules, and domain state machines without any framework coupling — the library has no service provider, no config, and no container obligations. That is both a strength (low blast radius, easy to isolate) and a ceiling (no first-class Laravel ergonomics such as validation rule objects or cast helpers; you write those yourself).

Integration feasibility. Mechanically trivial: composer require somnambulist/enumeration, autoload, extend the base class. No migrations, no config publishing, no queue/event implications. The real feasibility question is not "can we install it" but "should we adopt a class-based enum abstraction in a codebase that may already target PHP 8.1+". For greenfield work on modern PHP, native backed enums plus a small trait cover 80–90% of the same surface area with zero third-party risk. For brownfield systems pinned to PHP 7.4 or carrying a large existing eloquent/enumeration footprint, this fork is a plausible drop-in continuation.

Technical risk. The dominant risk is provenance and longevity, not code quality. The package is a community fork of an abandoned upstream (eloquent/enumeration), published under a single maintainer's namespace, with zero stars and zero dependents on the recorded registry snapshot. That is the weakest possible community signal: no downstream canary, no issue traffic, no external contributor base. Concretely:

• Bus factor of one. A single maintainer's availability governs patch cadence and PHP-version support.
• Fork drift. Forks of dead libraries accumulate silent divergence from upstream; behaviour differences in edge cases (comparison semantics, serialization, jsonSerialize) may not be documented.
• Native-enum obsolescence. The entire value proposition is being eroded by the language itself; expect the maintenance case to weaken over time, not strengthen.
• Supply-chain surface. Small, low-visibility packages are a known vector for typo-squatting and abandoned-namespace takeover. Pin exact versions and verify the maintainer identity before adoption.
• Licensing is clean (MIT), so legal/redistribution is a non-issue.

None of this is disqualifying for a bounded, low-criticality use, but it rules the package out as a load-bearing primitive in a long-lived platform without a documented exit plan.

Key questions to resolve before commitment.

1. What is the supported PHP version matrix, and does it explicitly cover the PHP version(s) we run today and will run in the next 24 months?
2. What is the concrete delta from eloquent/enumeration — bug fixes only, or behavioural changes? Is there a changelog we can audit?
3. Does the maintainer publish a support/security policy, or is this effectively "as-is, best effort"?
4. How does it behave under static analysis (PHPStan/Psalm) and with strict types? Are generics/type annotations usable?
5. Does it interoperate cleanly with Eloquent's casts for attribute hydration/dehydration, or do we need our own cast classes?
6. Is there any active issue/PR history that indicates the maintainer is responsive to security reports?
7. What is the fallback if the package is abandoned mid-cycle — is the class surface small enough to vendor or reimplement natively?

Integration Approach

Stack fit. The package is framework-agnostic PHP and imposes no Laravel assumptions, so it fits any Laravel 8/9/10/11 application without touching the container, middleware, or bootstrapping. Its natural insertion points are: Eloquent castable attributes for status/type columns, form-request validation rules, domain-layer value objects for money/unit/interval types, and switch replacement in service classes. It does not fit modern codebases that have already standardised on native PHP 8.1 backed enums — mixing both abstractions in one domain is a net readability loss and should be avoided.

Migration path. Two directions, and the direction matters more than the mechanics:

• Inbound (adopting the fork from upstream): because it is a fork rather than a rename, the API is expected to be largely source-compatible with eloquent/enumeration. Replacement should be a composer-level swap plus a namespace import diff, followed by a regression pass over any class that overrides comparison, serialization, or validation behaviour. Treat that regression pass as mandatory — fork drift hides in exactly those overrides.
• Outbound (retiring the package in favour of native enums): map each enum class to a backed enum, preserve constant names, and shim any helper methods onto the enum via traits. This is a mechanical but wide refactor; plan it as a dedicated piece of work, not opportunistic cleanup.

Document the exit plan at adoption time. If the answer to "how do we get off this in two years" is not written down, the integration should not proceed.

Compatibility. Verify four axes explicitly: PHP runtime version, Composer 2 resolution against the rest of the lockfile, static-analysis level, and Eloquent version. The last is subtle — cast behaviour around null, array casting, and query binding of enum-backed attributes has shifted across Laravel majors. Because the package has no dependents, there is no community evidence that it has been exercised against your specific Laravel/Eloquent combination; you are the first integration test.

Sequencing. Adopt in this order:

1. Spike in a scratch branch — install, define three representative enums (simple, keyed, value-object), wire one Eloquent cast and one validation rule, and run static analysis at the project's configured level.
2. Boundary proof — confirm the package appears in the lockfile with a pinned version, that no transitive weight is added, and that the namespace does not collide with existing domain code.
3. Pilot in one bounded module — a leaf domain with low write volume, not the core billing or auth path.
4. Codify conventions — where enums live, how they serialize to JSON/API responses, how they persist, and how they are validated. Undocumented convention is the main way these abstractions rot.
5. Widen only after a full release cycle with no incidents, and only if the native-enum exit has been formally deferred with a date.

Operational Impact

Maintenance. The library is effectively in caretaker mode. Expect no proactive features, slow response to PHP-version bumps, and occasional dormancy. Budget for the possibility that your team becomes the de facto maintainer — either via a pinned internal fork or via vendoring the ~small class surface. The correct posture is to treat it as vendored code with a convenience Composer entry, not as an actively supported dependency. That framing changes who owns it (platform team, not feature teams) and how urgently a break is escalated.

Support. There is no vendor, no SLA, and no commercial backing. Internal support therefore means: a named owner, a documented "how to patch in a hurry" runbook, and a fork-and-fix capability in the platform team. The zero-star, zero-dependent profile also means you will find no Stack Overflow corpus and little blog coverage — onboarding and troubleshooting time will be higher than for a mainstream package of comparable complexity, because there is no external knowledge base to fall back on.

Scaling. Runtime scaling is a non-issue: these are lightweight in-process objects with no I/O, no caches, and no global state, so they add negligible overhead at any request volume. The scaling concern is organisational, not technical — the abstraction scales poorly across a large engineering org because there is no shared public reference, no native-idiom recognition, and every new team re-derives the same conventions. A large team is better served by a language-native primitive that every PHP developer already knows.

Failure modes. In rough order of likelihood and impact:

• PHP major-version incompatibility — the package stops installing or emits deprecations on a runtime upgrade, blocking the platform upgrade. Highest-impact, slowest to remediate externally; mitigated by vendoring.
• Silent behavioural drift from upstream — code copied against upstream docs behaves subtly differently post-fork, surfacing as data-corruption or serialization bugs rather than hard errors. Mitigated by a regression suite over comparison/serialization paths.
• Namespace or package abandonment — the maintainer disappears or the namespace is repurposed. Mitigated by exact version pinning and a lockfile committed to source control.
• Persistence coupling — enum values written to the database become a de facto schema. Changing a constant's underlying value later requires a data migration. Enforce a rule that stored values are explicit and immutable, and never derived from class names or ordinals.
• Serialization inconsistency — mixed jsonSerialize/toArray/cast behaviour across the codebase producing inconsistent API payloads. Mitigated by a single shared base class or trait, mandated by convention.

Ramp-up. For a developer already fluent in Laravel, the concept (typed value objects) is a half-day of learning, but the absence of documentation, examples, and community Q&A pushes practical fluency to roughly one to two days plus code review guidance. The genuine ramp-up cost is conceptual discipline: teams must agree on when to use these objects versus native enums versus plain constants. In a codebase that has already adopted PHP 8.1 enums, expect sustained confusion and review friction. Recommend a short internal ADR, two worked examples in the repo, and a lint rule or code-review checklist — otherwise the abstraction degrades into a second, inconsistent convention alongside whatever the team was already doing.

Bottom line for a TPM. Low-to-moderate value, low technical complexity, elevated governance risk. Justifiable only as a time-boxed bridge in a PHP 7.x brownfield system with an existing eloquent/enumeration footprint and a written exit plan to native enums. Not justifiable as a new architectural primitive in a greenfield or PHP 8.1+ codebase, where the language already solves the problem with better tooling, zero dependencies, and no bus-factor exposure.