Type Laravel Package

Product Decisions This Supports

• Build vs. buy for type tooling: sebastian/type is the lowest-level building block for any product surface that needs to reason about PHP types — API contract generation, static analysis gates, IDE helpers, or custom validation rules. It converts "parse this type-hint string and hope" into a maintained, tested value-object model, so the buy decision is essentially settled for the type-model layer; build effort should go into the product logic on top (business rules, schema mapping, DX), not into re-implementing union/intersection/alias handling.
• Roadmap: type-safety as a feature, not a chore: Enables a credible internal "strict types" initiative — type-aware validation on FormRequests/DTOs, OpenAPI/GraphQL schema generation from reflection, and CI static-analysis gates. These are roadmap items that become schedulable rather than speculative once the type model is a dependency.
• Legacy modernization: Accurate assignability checks (including class-alias resolution, fixed in 7.0.1) let teams refactor toward stricter type hints with evidence instead of guesswork. This supports sequencing decisions like "tighten types on the money/health path first."
• Developer tooling investment: Justifies spending on internal PHPStan/Psalm rules and IDE integration, since the hard part (normalizing PHP's type system) is already solved upstream and kept current by a high-trust maintainer.
• Prioritization signal: Low stars (~1.5k) but enormous transitive adoption via PHPUnit means the real decision isn't "is this popular" but "which major version do we standardize on" — a PHP-version-driven roadmap constraint (v7 requires PHP 8.4+; v6 covers 8.2/8.3).
• Use cases to scope: type-safe event/webhook payload validation, DI container type-hint auditing, DTO round-trip tests, and generated API docs — each a candidate for its own increment rather than one big "type safety" epic.

When to Consider This Package

Adopt when:

• You are building tooling that must inspect types — static analysis rules, code generators, IDE/autocomplete helpers, schema extractors — and want a normalized object model (ObjectType, UnionType, intersection types) instead of string parsing.
• Class-alias assignability matters (e.g., DateTimeImmutable satisfying a DateTimeInterface/DateTime expectation) and you are on PHP 8.4+ with the 7.x line.
• Your product's correctness argument depends on type compatibility: DTO validation, contract tests, or migration tooling for legacy codebases.
• You want a runtime-free, dependency-light library that fits cleanly as a --dev or tooling-only Composer dependency.

Look elsewhere when:

• You need runtime enforcement of types in production request handling — native type hints, Laravel validation rules, or spatie/laravel-data-style DTO casting are the right layer; this library models types, it does not enforce them.
• You are on PHP 8.2/8.3 and cannot pin to ^6.0 — v7.0.0 dropped 8.3 support, and v6 will stop receiving fixes; treat that as a hard platform constraint, not a footnote.
• The requirement is domain modeling (e.g., a Money or UserId type) rather than PHP type introspection — you'd be extending upstream classes for business logic, which creates maintenance coupling for little gain.
• The stack is polyglot or non-PHP, or the team has no capacity to own custom analysis rules; a low-level library with this footprint needs an owner, not a drive-by install.
• A higher-level tool already covers the need end-to-end (PHPStan/Psalm with existing rule sets); adding this directly only makes sense if you're writing the rules yourself.

How to Pitch It (Stakeholders)

For executives: This is a small, zero-runtime-dependency library from the maintainer behind PHPUnit — effectively already in our dependency graph through the test and analysis toolchain. Adopting it deliberately, rather than incidentally, lets us build type-aware validation, API contract generation, and CI quality gates on a maintained foundation instead of bespoke parsers. The 7.0.1 release closed a real correctness gap (class-alias assignability) that has historically caused false positives in analysis and wasted engineering time. Cost is a Composer line; the return is fewer type-related production defects and faster, safer refactors on our highest-risk code paths. The main decision requiring your input is platform timing: v7 requires PHP 8.4+, so standardizing there is a prerequisite, not an implementation detail.

For engineering: This is the type-model layer we'd otherwise hand-roll. ReflectionMapper bridges PHP reflection to value objects, handling unions, intersections, iterable edge cases, and aliases — exactly the cases that make DIY type checking brittle. It won't enforce anything at runtime; it's the foundation for tooling we own: PHPStan/Psalm rules, OpenAPI generation from return types, DTO compatibility tests using isAssignableFrom(). Integration is a single dev dependency plus a ReflectionMapper binding, and there's no runtime or memory cost because it's analysis-time only. Two things to get right up front: pin the major version to our supported PHP range (v7 for 8.4+, v6 if we're stuck on 8.3, accepting no future fixes), and add alias and complex-union cases to our test fixtures so the 7.0.1 behavior is locked in by tests rather than assumed.