Immutable Laravel Package

Technical Evaluation

Architecture fit. teknoo/immutable is a small, single-purpose utility for enforcing immutability on PHP objects — most likely one or more traits/abstract base classes that block post-construction mutation (via __set/__unset guards, clone-on-write accessors, or similar) and an ImmutableInterface marker. Architecturally it slots into the domain layer of a Laravel application: DDD value objects (Money, Email, TenantId, DateRange), domain events, command/query DTOs, and event-sourced aggregate snapshots. It is not a framework-level concern and does not touch presentation, persistence, or transport — which is good: the blast radius of adoption is contained.

Integration feasibility. Composer-installable, BSD-3-Clause, no framework coupling implied. Integration is trivial in isolation, but the feasibility question is not "can it install" — it's "should it." Signals are weak: 4 stars, 0 dependents, overall score 0.02. That is effectively zero ecosystem validation. Expect to read the source (it is likely small) rather than rely on docs or Stack Overflow answers.

Technical risk.

• Native-language displacement. PHP 8.1 readonly properties and PHP 8.2 readonly classes deliver most of this package's value with zero third-party surface, better IDE/static-analysis support, and no runtime magic. If the fleet is on 8.2+, the package's core justification largely evaporates. This is the dominant risk: adopting a dependency to replicate a language feature.
• Vendor concentration. Very likely a single-maintainer project under an umbrella org (Teknoo). No evidence of a paid support tier, LTS policy, or security disclosure process.
• Magic-method interference. __set/__get/__clone trickery commonly collides with Eloquent hydration and PHP serialization, and can confuse static analyzers (PHPStan/Psalm) and Laravel's $casts pipeline.
• Version ceiling. Unverified PHP 8.2/8.3/8.4 support. Stale composer.json constraints are a common blocker on Laravel 11/12 upgrades.

Key questions to resolve before committing.

1. What is the exact API surface — an interface, a trait, an abstract class, or all three — and does it offer withX() clone-on-write helpers or only mutation guards?
2. Which PHP versions and which composer.json constraint does the latest tag declare?
3. Last commit date, open-issue count, and whether tagged releases exist (vs. dev-main only).
4. Does it implement __serialize/__unserialize and __clone correctly? (Serialization is the usual breakage point.)
5. Are there tests, and what is the CI matrix?
6. Any license or transitive-dependency issues versus the org's approved list?

Integration Approach

Stack fit. Fits a Laravel codebase that already aspires to DDD: app/Domain/**/ValueObject, app/Domain/**/Event, and read-model DTOs. It does not fit Eloquent models, form requests, or any object that Laravel hydrates by reflection and assignment — the mutation guards will fight the framework.

Migration path. Do not retrofit. Adopt greenfield, in this order:

1. Isolate one value object (e.g., Money) behind an internal interface your code owns — App\Domain\Contracts\ImmutableValueObject. The package trait sits behind that interface.
2. Wrap, don't leak. Never let Teknoo\Immutable\* types appear in public method signatures outside the value-object package. This makes the eventual swap to native readonly a one-line-per-class change.
3. Evaluate against native readonly in parallel. Implement the same Money twice — once with the trait, once as a final readonly class — and let the team compare ergonomics, static analysis results, and serialization behavior.
4. Decide and either promote or delete the experimental branch within one sprint.

Compatibility. Confirm the Composer constraint against the target PHP and Laravel versions first; a Laravel 11/12 app on PHP 8.2+ is the likely baseline, and that baseline is exactly where native readonly makes the package redundant. Check for conflicts with spatie/laravel-data, symfony/serializer, and any object-mapper already in the dependency graph — those libraries make strong assumptions about constructor shape and property mutability.

Sequencing. Composer audit and static-analysis run → isolated proof of concept → team review → decision gate. Budget roughly one engineer-week end to end. Do not sequence this ahead of anything; it is a low-priority hygiene task that should not block a release train.

Operational Impact

Maintenance. The real cost is not the package — it is the fork you will eventually own. With 0 dependents and a single maintainer, assume no upstream fixes for PHP 8.4/8.5 or for the next major PHP release. A vendored fork is manageable because the library is small, but that must be an explicit, resourced decision rather than a surprise at upgrade time.

Support. No commercial support, no SLA, no published security policy. Internal escalation path is "read the source." Acceptable for a 200-line utility; unacceptable for anything on a payment or auth path.

Scaling. Runtime cost is negligible — property guards and clone-on-write are nanoseconds. The scaling concern is cognitive and organizational: every new engineer must learn the library's specific immutability idiom, and "why don't we just use readonly?" will be asked repeatedly. Documentation debt compounds across teams.

Failure modes.

• Silent non-immutability — a guard that can be bypassed via reflection, unserialize, or Eloquent's forceFill. Immutability you believe you have is worse than none.
• Clone-semantics bugs — shallow clones sharing mutable nested arrays/objects, producing spooky cross-object mutation in aggregates.
• Serialization breakage — queue jobs and cache payloads failing to round-trip, surfacing only in production workers.
• Upgrade deadlock — a PHP or Laravel major bump blocked solely by this dependency, forcing an emergency fork or a rushed removal.
• Static-analysis noise — PHPStan/Psalm losing type inference through magic accessors, degrading the whole team's CI signal.

Ramp-up. Low. A competent PHP engineer reads the source in under an hour. The harder ramp is the discipline — teaching the team to design constructors, withX() transitions, and equality semantics correctly, and to keep Eloquent out of the domain layer. Plan a short internal brown-bag rather than assuming the README is sufficient.

Recommendation. Given 0 dependents, 4 stars, a 0.02 composite score, and — decisively — functional overlap with PHP 8.2 readonly, treat this as do-not-adopt for production unless the PoC reveals a genuinely superior ergonomic story. The likely best outcome is to borrow the pattern the library encodes (constructor-only initialization, clone-on-write accessors, marker interface) and implement it natively, capturing the design value with none of the vendor risk. If the team is stuck on PHP 8.1 or below and needs mutation guards today, a time-boxed, interface-isolated pilot is defensible — with a pre-agreed exit path to native readonly at the next PHP upgrade.