Type Laravel Package

Getting Started

Install as a dev dependency: composer require --dev sebastian/type. Focus first on ReflectionMapper and the Type hierarchy (ObjectType, UnionType, IntersectionType, etc.). The primary use case is building or extending static analysis tools—e.g., writing a custom PHPStan rule that checks for missing @return annotations by mapping ReflectionMethod to a Type object via ReflectionMapper::fromFunctionLikeType($method->getReturnType()). Start by reviewing src/Type.php and src/ReflectionMapper.php to see how PHP’s reflection API is normalized into composable value objects.

Implementation Patterns

• Static analysis tooling: Use ReflectionMapper::fromPropertyType() (added in v5.1.0) to convert ReflectionProperty::getType() into Type instances for enforcing field-level constraints (e.g., ensuring all DTO properties are typed as scalar or nullable).
• Custom PHPStan rules: Combine Type::equals() and is_subtype_of() to detect incompatible overrides (e.g., parent::save(): void vs child::save(): bool).
• Docblock generation: Serialize Type objects to strings (via toString()) when scaffolding API clients or OpenAPI specs from reflection data—especially useful for union/intersection types that PHP’s native ReflectionType::__toString() doesn’t fully capture.
• Test assertions: In unit tests, assert type compatibility with Type::isCompatibleWith() (e.g., verify that a function returning int|float is compatible with float|int, which is considered equal under commutativity).

Gotchas and Tips

• PHP version lock: v7.0.0+ drops support for PHP < 8.4. If your project supports PHP 8.3 (still widely used), pin to ^6.0. Verify with composer show sebastian/type—5.1.x supports up to PHP 8.3.
• iterable edge cases: Though fixed in 5.1.1+/6.0.2+, ReflectionMapper::fromType() historically mishandled unions like iterable|ArrayObject. Always test with edge cases (e.g., iterable|Traversable|Closure).
• No userland types: This library only represents PHP’s native types (int, string, object, unions/intersections). It does not support class-string, trait aliases, or custom user-defined types—extend Type carefully for domain-specific needs.
• Immutable by design: All Type objects are value objects—no setters, no mutation. If your code mutates types (e.g., appending null to a union), create a new UnionType instance.
• Debugging tip: Use var_dump($type) on a Type instance to see its internal structure (e.g., ObjectType shows the FQCN; UnionType lists all components). Pair with Xdebug to trace reflection mapping in complex code.