Immutable Laravel Package

Product Decisions This Supports

• Build vs. buy for value objects and collections. innmind/immutable supplies ready-made wrappers for PHP primitives (Str, NonEmptyString, Map, Set, Sequence, Vector, etc.). The decision it informs is whether your team hand-rolls a dozen DTO/VO classes per bounded context or adopts a small MIT-licensed dependency. For a team that has already written two or more internal "StringValue"/"Money"/"Id" base classes, this is a credible replacement for that bespoke layer.
• Investing in a functional core / imperative shell architecture. Adopting immutable primitives is the cheapest concrete step toward isolating pricing, discounting, tax, ledger, and eligibility rules into pure, side-effect-free functions. Roadmap implication: it enables parallel work on a rules engine or calculation module that is testable without database fixtures.
• Reliability roadmap: eliminating a class of production bugs. Shared mutable state is the root cause of a specific, expensive bug family — leaked state across requests under Laravel Octane/Swoole, mutation of an array passed by reference into a service, order totals that change after a job retries. Wrapping those values makes mutation a type error rather than a code-review catch. This supports a stated OKR around defect escape rate in money-touching code paths.
• Data integrity and auditability requirements. Orders, invoices, ledger entries, and audit snapshots benefit from values that cannot be mutated after construction. This is a product decision as much as a technical one: "the amount we recorded at authorization is the amount we can always show."
• Complex transformation features. Import pipelines, CSV/feed normalization, reporting aggregation, and multi-step filtering read more cleanly as chained map/filter/flatMap over immutable sequences than as nested foreach with accumulator arrays. Useful when scoping features like "configurable report builder" or "bulk pricing recalculation."
• Static analysis and refactor safety initiatives. These wrappers are strongly typed and composition-friendly, which supports a PHPStan/Psalm hardening goal and makes large refactors of a domain layer cheaper to validate.
• Explicitly not a decision driver: it does not replace Eloquent, does not touch persistence, and provides no HTTP, queueing, or validation-at-the-edge story. It is a domain-layer ingredient, not a framework.

When to Consider This Package

Consider it when:

• You have a high-integrity domain — payments, billing, pricing, inventory counts, financial reporting — where a mutation bug costs real money or requires a reconciliation incident.
• Your application runs in long-lived PHP processes (Octane, Swoole, RoadRunner) or high-volume queue workers, where accidental state retention across requests/jobs is a live risk.
• The team already reaches for functional idioms (pure functions, composition, map/filter) and would use these types naturally rather than fighting them.
• You are building or extracting a domain core and want its primitives frozen at the boundary — a natural fit for a modular monolith or hexagonal refactor.
• You want a small, permissively licensed (MIT), dependency-light library rather than a framework-sized ORM/DTO suite.
• You are willing to write the adapters yourself at the Eloquent/serialization boundary and accept that cost.

Look elsewhere when:

• The product is CRUD-shaped: forms, admin panels, resource controllers. Laravel's Collection, readonly properties (PHP 8.1+), and enums already cover 90% of the need with zero new dependency.
• The team is small, junior, or under delivery pressure. The functional style has a real ramp-up cost and this library has almost no tutorials, blog posts, or Stack Overflow footprint to lean on.
• You require vendor support, an SLA, a security review program, or broad hiring-pool familiarity. 75 stars, an unknown/unlisted repository, and an apparent single-maintainer model mean bus factor is the dominant risk. Treat it as "code you may have to fork."
• You need ecosystem interop: spatie/laravel-data, brick/math, ramsey/uuid, Laravel's Collection, or doctrine/collections give you wider community support and familiar APIs for the same problems.
• Performance is tight in hot loops — object wrapping per value adds allocation overhead versus plain arrays and scalars.
• The codebase is on older PHP or mixed-style, where immutable wrappers would create an inconsistent island.

Adoption criteria (gate before committing): a pilot in one bounded module; a documented boundary adapter to and from Eloquent models and JSON; a review of the dependency's release cadence and open issues; an internal fork/vendoring plan; and a team agreement that the style will be used in the target module only, not enforced globally.

How to Pitch It (Stakeholders)

To executives (30 seconds): "We're proposing a small MIT-licensed library for one specific module — [pricing / billing / ledger] — that makes our data values unchangeable once created. The business case is defect prevention, not features: it eliminates a class of bugs where a number or record gets silently altered mid-process and produces a wrong charge, wrong total, or wrong report. Those bugs are rare, hard to reproduce, and expensive to reconcile. Cost is near zero in licensing and roughly one sprint of team ramp-up, contained to one module. The honest risk is that the library is small and essentially one maintainer, so we'd pin the version and keep the option to vendor it. I'd like approval for a scoped pilot with a go/no-go at the end."

To engineering leadership / architects:

• It gives us typed, validated primitive wrappers (Str, NonEmptyString, Map, Sequence) so validation lives at construction rather than being re-checked in every method.
• It makes "this value must not change" a compiler/static-analysis-enforceable property instead of a comment and a code-review convention — meaningful as we move to Octane, where shared mutable state causes cross-request bleed.
• It moves our business rules toward pure functions: fewer database fixtures in tests, faster suites, safer refactors under PHPStan.
• The trade-offs are real and we should name them: a functional style the team must learn, manual adapters at the Eloquent and JSON boundaries, and an immature ecosystem around the dependency.
• Recommendation: adopt as a targeted tool in a single domain module behind an adapter layer, pinned to an exact version, with a documented exit path (fork or local reimplementation). Measure success by defect rate in that module, test-suite runtime, and review cycle time. If the module's defect rate doesn't move or the team's velocity drops, we revert — the wrappers are shallow enough that removal is cheap.