Type Laravel Package

Product Decisions This Supports

• Build vs. Buy: Justifies investing in custom type safety tooling (e.g., PHPStan/Psalm extensions, Laravel validation rules, or API contract generators) instead of relying on third-party solutions. Reduces dependency on external tools for type introspection, validation, and static analysis.
• Roadmap Prioritization:
  • Type Safety Initiatives: Accelerates development of strict type validation for Laravel APIs, DTOs, and domain models, aligning with modern PHP best practices.
  • Legacy Code Modernization: Enables safe refactoring by providing accurate type assignability checks, critical for resolving class alias issues (e.g., DateTimeImmutable vs. DateTime).
  • Developer Tooling: Supports internal IDE plugins, CI/CD static analysis gates, and custom validation logic with precise type rules.
• Use Cases:
  • API Contract Generation: Normalize PHP types into OpenAPI/Swagger schemas or GraphQL types for consistent API documentation.
  • Custom Validation Logic: Extend Laravel’s Validator or FormRequest with type-aware rules (e.g., "this field must accept int|string").
  • Dependency Injection: Validate constructor/property type hints in service containers (e.g., ensure DateTimeInterface is satisfied by DateTimeImmutable).
  • Testing: Assert type compatibility in unit tests (e.g., verify a method’s return type is assignable to an expected type).
  • Static Analysis: Integrate with PHPStan/Psalm to enforce type consistency across the codebase, reducing runtime errors.

When to Consider This Package

Adopt when: ✅ Your project requires deep PHP type introspection (e.g., static analysis, code generation, or custom validation logic). ✅ You’re building type-aware tooling (e.g., PHPStan/Psalm rules, IDE helpers, or API clients). ✅ Class alias resolution is critical (e.g., DateTimeImmutable as a DateTime substitute) and you’re on PHP 8.4+. ✅ You need to reduce technical debt in legacy codebases by ensuring type consistency. ✅ Laravel/PHP ecosystems demand strict type safety (e.g., financial systems, healthcare APIs, or high-assurance applications). ✅ You’re developing DTOs, domain models, or API contracts that require precise type definitions.

Look elsewhere if: ❌ You need runtime type enforcement (use PHP’s native type hints, php-types, or spatie/array-to-object). ❌ Your stack uses non-PHP languages (e.g., TypeScript, Java, or Go). ❌ You lack developer resources to integrate custom type rules (this is a low-level library requiring tooling expertise). ❌ You’re on PHP < 8.4 (v7.0.0+ drops support; use ^6.0 for PHP 8.2/8.3). ❌ You need user-defined types (e.g., custom classes, traits, or interfaces beyond PHP’s native types). ❌ Your project is prototype-only with no long-term type safety requirements.

How to Pitch It (Stakeholders)

For Executives: *"This package is a strategic investment in type safety that will reduce bugs, accelerate development, and future-proof our Laravel ecosystem. By adopting sebastian/type, we can:

• Cut costs by eliminating outsourcing for custom static analysis tools (e.g., PHPStan rules), saving 30–50% on tooling development.
• Speed up API development with auto-generated, type-accurate contracts that enforce consistency across microservices.
• Reduce production incidents by fixing critical type resolution issues (e.g., DateTimeImmutable vs. DateTime aliases), which were a known pain point in legacy systems.
• Align with modern PHP standards (PHP 8.4+) and Laravel’s long-term roadmap, ensuring our stack remains competitive.

The recent v7.0.1 fix resolves a high-impact edge case in class alias resolution, making this a low-risk, high-reward decision. For a minimal Composer dependency, we gain precision in type validation—critical for compliance, scalability, and developer productivity."*

For Engineering Teams: *"This is the missing piece for our static analysis and type-aware tooling. Here’s why it’s a game-changer:

• No more reinventing the wheel: The ReflectionMapper handles edge cases (like class aliases) out of the box, so we can focus on business logic.
• Seamless Laravel integration: Works with PHPStan/Psalm, Laravel’s validator, and custom DTOs without friction.
• Future-proof: The fix for class alias resolution (v7.0.1) ensures our type checks won’t break on legacy code or third-party libraries.
• Zero runtime overhead: Only affects static analysis, which runs in CI/CD or development environments.

Action items:

1. Add as a dev dependency:

   composer require --dev sebastian/type
   

2. Test with ReflectionMapper::fromType() and Type::isAssignableFrom() in your static analysis tools.
3. Validate edge cases (e.g., iterable|ArrayObject, DateTimeImmutable as DateTime).

Key wins:

• Faster onboarding: New developers get type safety out of the box.
• Fewer bugs: Catch type mismatches early in CI/CD.
• Cleaner code: Enforce consistent type usage across the codebase.

Let’s start with PHPStan rules and expand to API contracts and validation logic."*