Type Laravel Package

Product Decisions This Supports

• Build vs. Buy: Buy for type validation, serialization/deserialization, and runtime type checking. Avoid reinventing a robust type system when this package provides a comprehensive, battle-tested abstraction over PHP’s native types and PHPDoc syntax.
• Feature Roadmap:
  • API Contracts: Enforce strict input/output types for APIs (e.g., GraphQL, REST) by validating requests/responses against Typhoon\Type schemas.
  • Data Validation: Replace manual validation logic (e.g., in forms, configs) with declarative type constraints (e.g., nonEmptyStringT, intRangeT).
  • Serialization/Deserialization: Power a type-safe mapper (like Mapper in the example) to convert between JSON/XML and typed PHP objects, reducing runtime errors.
  • Documentation Generation: Auto-generate PHPDoc blocks from Typhoon\Type definitions for IDE support (e.g., PHPStorm).
  • Runtime Type Checking: Add dynamic type guards (e.g., if ($value instanceof nonEmptyStringT())) to replace is_string() + strlen() checks.
• Use Cases:
  • Internal Tools: Validate configs (e.g., Laravel service providers, Symfony bundles) or CLI arguments.
  • SDKs/Libraries: Ensure third-party integrations adhere to type contracts (e.g., payment gateways, auth providers).
  • Legacy Code Modernization: Gradually introduce type safety to untyped PHP codebases by wrapping critical paths with Typhoon\Type checks.

When to Consider This Package

• Adopt if:
  • Your team prioritizes type safety but lacks PHP 8’s native attributes or strict typing.
  • You need runtime type validation beyond static analysis (e.g., PHPDoc or Psalm).
  • Your project involves complex data structures (nested arrays, generics, PHPDoc-compatible types) that would be cumbersome to validate manually.
  • You’re building a DSL, mapper, or validation layer (e.g., for APIs, configs, or domain models).
• Look elsewhere if:
  • You’re using PHP 8.2+ attributes (e.g., #[\Assert\Valid]) or strict typing—native tools may suffice.
  • Your use case is pure static analysis (e.g., Psalm, PHPStan) without runtime enforcement.
  • You need reflection-based type inference (e.g., fromReflection()), which is intentionally removed from this package (see typhoon/algebra).
  • Your team lacks PHP 8.0+ (this package requires modern PHP features like named arguments, union types).

How to Pitch It (Stakeholders)

For Executives:

*"Typhoon Type lets us catch bugs at runtime with minimal dev effort. Instead of writing verbose validation logic (e.g., if (!is_array($data) || !isset($data['people']))), we define types once—like arrayShapeT(['people' => nonEmptyListT(objectT(Person::class))])—and let the library enforce them. This reduces:

• Support costs (fewer runtime errors in production).
• Onboarding time (self-documenting code via PHPDoc).
• Tech debt (no need to maintain custom validators).

ROI: Faster development cycles for APIs, configs, and SDKs—with zero performance overhead (types are checked only when needed)."*

For Engineers:

*"This is PHP’s answer to TypeScript’s runtime types. Key wins:

1. Declarative Validation: Replace is_array() + array_key_exists() spaghetti with Typhoon\Type constraints.
2. Mapper Integration: The example shows how to auto-convert JSON to typed objects—imagine this for API requests, database rows, or CLI args.
3. PHPDoc Alignment: Types like nonEmptyStringT or intRangeT(-5, 6) map directly to PHPDoc, so your IDE gets free type hints.
4. Extensible: Need custom types? Build on the Visitor pattern (e.g., add is() checks or serialization rules).

Tradeoff: Some advanced features (e.g., reflection-based types) are in typhoon/algebra, but this package covers 90% of runtime needs with a clean API.

Proposal:

• Start with input validation (e.g., API requests, configs).
• Replace 1–2 critical validation functions (e.g., a config loader) as a proof of concept.
• Expand to serialization (e.g., JSON ↔ typed objects) if the mapper example resonates."*