Php Types Laravel Package

Technical Evaluation

Architecture fit

tdn/php-types is a primitive-obsession wrapper library: it boxes PHP scalars (Int, String, Float, Bool, Arr) into immutable value objects with validation and fluent accessors. Architecturally it is a pure domain-layer utility with no framework coupling — no service provider, no facade, no config, no Eloquent integration. That means it is trivially isolatable, but also that "Laravel/PHP package" overstates the integration surface: there is nothing to register in config/app.php or bootstrap/providers.php.

Fit depends entirely on whether the codebase already practices value-object modeling. In a typical Laravel CRUD application the wrappers would be an impedance mismatch — they collide with Eloquent casts, Illuminate\Support\Collection, json_encode serialization, and Laravel's own Str/Arr helpers. In a tightly modelled domain core (hexagonal/DDD), the pattern is legitimate, but the implementation is a decade old.

Integration feasibility

Mechanically easy, practically poor:

• Composer-installable with PSR-4 autoloading; no transitive dependency tree to audit.
• No meaningful SemVer history beyond a 2015-era lineage; the 2.0.1 tag arrives with no LTS policy, and constraint resolution will likely still resolve to dev-master semantics for support purposes.
• No Laravel service provider, no published casts, no factories, no config — every integration point (Eloquent casting, validation rules, request hydration, API resources) must be hand-written by us.
• No CI badge, no coverage report, no documentation site (release notes claim "Updated documentation," but no hosted docs) — integration knowledge must be reverse-engineered from source.
• The 2.0.1 release introduces class aliases intended to avoid PHP 7.0 reserved-keyword collisions, which partially addresses the previous go/no-go blocker. This must be verified at the bytecode level — aliases only help if the legacy reserved-name classes are no longer autoloaded under PHP 8.x.

Technical risk

Key questions

1. Does the repository contain any license file, and has legal cleared it for our distribution model? (Unchanged — still the primary gate.)
2. New: Which class names survive as loaded classes vs. aliases in 2.0.1, and do class_alias targets resolve on PHP 8.2 without fataling on reserved words? This replaces the previous yes/no parse check with a file-level and autoload-level audit.
3. Is our objective type-safety enforcement or domain vocabulary? If the former, native PHP 7+ scalar types, PHP 8.1 readonly properties, and native enum cover ~90% of the value with zero dependency risk.
4. Which specific wrapper types have we identified as genuinely needed, and what is the cost of writing two or three in-house (still likely <1 day each)?
5. Would a maintained alternative (webmozart/assert, ramsey/uuid, brick/money, native DTOs) cover the same need?
6. New: Does the Boolean::invoke addition reflect any contract change, or is it purely additive? Confirm no BC break for anyone who already vendored the class.

Integration Approach

Stack fit

Poor as a dependency; reasonable as a pattern reference. The library provides no Laravel touchpoints, and the modern PHP runtime has absorbed its core value proposition. 2.0.1's alias strategy confirms the original authors knew the design was future-hostile — but aliases are a migration aid, not an ergonomic solution. Treat it as a catalog of ideas to copy, not a component to install.

Migration path

1. Do not add to composer.json. No new runtime dependency enters the lockfile. The 2.0.1 alias change does not alter this recommendation.
2. Vendor-by-copy selectively — only if legal clears the license, extract the two or three wrapper classes we actually need into our own namespaced value-object folder, rewritten for PHP 8.2 with final, readonly, typed properties, Stringable/JsonSerializable implementations. Skip the alias machinery entirely; alias shims are dead weight in greenfield code.
3. If the license does not clear, reimplement from scratch against the pattern (the semantics are unprotectable; the specific source is not).
4. Retire the originals — if any legacy code already uses the package, replace with native typed properties and enums incrementally, branch by branch.

Compatibility

• 2.0.1 reduces the reserved-word collision risk, but verify on our PHP 8.2 target in a throwaway container — aliasing reserved names is a subtle area and PHP 8's engine can still reject autoloaded symbol collisions depending on order of declaration.
• Provide Eloquent CastsAttributes implementations per wrapper if persistence is needed — net-new code the package still does not supply.
• Ensure API Resources and queue serialization have explicit converters; without them, wrappers leak into JSON and break clients.
• Confirm Boolean::invoke is additive and does not alter equals/toBool semantics that callers may depend on.

Sequencing

1. Week 1 — Legal + runtime spike. License review; smoke-test the 2.0.1 artifact specifically (not 1.x) on our PHP version in a throwaway container. Watch for alias-ordering fatals. Expect the spike to be more likely to pass than before, but the license gate still decides the outcome.
2. Week 1 — Threat-model the alternative. Draft native-PHP equivalent for the two or three concrete use cases driving the request.
3. Week 2 — Decision gate. Adopt-fork, build-in-house, or use native primitives. Default recommendation remains native primitives, with in-house value objects only where a real invariant needs enforcing.
4. Week 2+ — Rollout only into new domain code; no retrofitting of stable modules.

Operational Impact

Maintenance

Effectively unbounded and unfunded. The 2.0.1 release demonstrates the maintainers can still publish, but a single mid-2015-era release cycle does not establish an ongoing maintenance contract. No issue triage, no PHP-version guarantee. Every PHP minor release becomes our regression test. Any fork we create is permanently ours — headcount must be allocated, not assumed.

Support

No vendor, no community, no maintainers, low visibility. Internal support burden falls wholly on the team that adopts it. Any incident — a fatal on a PHP upgrade, a serialization bug in production — has no escalation path. The 2.0.1 fix to a decade-old risk (reserved words) is exactly the kind of issue that should have been retired in 2017, not 2.0.1.

Scaling

Runtime cost of boxing scalars in hot paths (collections, loops, hydration) is non-trivial versus native types: allocation per value plus method-call overhead. At high request volume this is measurable, though rarely decisive. The larger scaling cost is cognitive: every boundary (job payloads, cache, JSON, database) requires an explicit conversion layer that must scale with the team, not the code.

Failure modes

• Hard fatal on PHP upgrade — reduced by 2.0.1's aliasing, but not eliminated. Autoload ordering and reserved-name symbol resolution remain sharp edges; re-verify on every PHP minor.
• Silent type coercion — wrapper equals/compare semantics from the 2015 lineage may not match PHP 8's comparison rules, yielding subtle logic bugs. Boolean::invoke is new and untested against our workloads.
• Serialization breakage — wrappers leaking into JSON responses or queue payloads, producing objects where consumers expect scalars.
• Legal exposure — unclear license surfacing during due diligence or acquisition. 2.0.1 does not remediate; this remains the single largest blocker.
• Orphaning — the fork diverges and can never merge upstream, while still carrying the original's design debt.
• Alias drift — if the alias strategy is imperfect (partial coverage, order-dependent declaration), a future PHP change could reintroduce a fatal in a way that is harder to diagnose than the original, because the class name that appears in stack traces may not be the class on disk.

Ramp-up

Low conceptual ramp-up (the primitive-wrapper pattern is well understood, and engineers familiar with value-object/money libraries will recognize it immediately), but negative net ramp-up in practice: onboarding engineers must learn both our domain and a bespoke, undocumented API surface with no external references or examples to search. The 2.0.1 alias layer adds a second mental model (aliased vs. original class names) that no external resource explains. New hires cannot Google it.

TPM recommendation: Do not adopt as a dependency. The 2.0.1 release is a net-neutral signal for adoption: it removes one technical objection (reserved-word parsing) while leaving the dominant blocker (license ambiguity) and the dominant risk (no maintainer, no PHP-8 guarantee, no serialization integration) untouched. Escalate the license question to legal, verify the alias behavior empirically in a spike, and satisfy the underlying requirement with native PHP 8 typed properties, readonly DTOs, and enums — with a short internal spike to prove no functional gap. The package score remains near the floor: 2.0.1 signals the project can ship, not that it will be maintained.