Types Laravel Package

Technical Evaluation

Architecture Fit

• Type Safety Alignment: The package provides extended type definitions (e.g., value objects, custom scalar types) that align with modern static analysis tools (PHPStan, Psalm, Rector). This is a strong fit for Laravel applications where type safety is critical (e.g., domain-driven design, ETL pipelines, or data validation layers).
• Laravel Ecosystem Synergy: While Laravel has its own typing conventions (e.g., Illuminate\Support\Collection, Carbon), this package could complement:
  • Request/Response DTOs (e.g., replacing manual array/mixed with strongly typed objects).
  • Database interactions (e.g., typed query builders or Eloquent models with custom scalar types like Email, UUID).
  • ETL/Event pipelines where data consistency is paramount.
• Monorepo Dependency: Being a subtree split from flow-php/flow suggests it’s part of a larger ecosystem (e.g., Flow PHP’s ETL tools). If the Laravel app interacts with Flow PHP’s other packages (e.g., flow-php/flow), this could enable seamless type sharing.

Integration Feasibility

• Low Friction for New Projects: Ideal for greenfield Laravel apps where type safety is a priority from the start. Minimal boilerplate if using Laravel’s built-in type hints (PHP 8.0+) alongside this package.
• Legacy App Challenges:
  • Backward Compatibility: Existing apps using mixed/array types would require refactoring to adopt the package’s value objects (e.g., replacing string with Email).
  • Static Analysis Tooling: Requires PHPStan/Psalm to fully leverage type checks. Laravel’s default tooling (PHPUnit, Pest) may need augmentation.
• Database Layer: If using Eloquent, the package’s types could enforce stricter validation (e.g., UUID fields), but would need custom accessors/mutators or model traits to bridge Laravel’s ORM and the package’s types.

Technical Risk

Key Questions

1. Use Case Clarity:
   • Is this for internal type safety (e.g., domain models) or external APIs (e.g., request/response validation)?
   • Will it replace Laravel’s native types (e.g., Carbon) or augment them?
2. Tooling Maturity:
   • Are PHPStan/Psalm already used in the project? If not, what’s the cost to adopt them?
3. Database Integration:
   • How will the package’s types map to database columns (e.g., UUID vs. string)?
4. Team Buy-in:
   • Is the team comfortable with strict typing and the refactoring effort?
5. Long-Term Maintenance:
   • Who will handle updates if Flow PHP’s ecosystem evolves (e.g., breaking changes)?

Integration Approach

Stack Fit

• PHP 8.3–8.5: Aligns with Laravel’s supported versions (Laravel 10+).
• Symfony Polyfill: No conflicts with Laravel’s dependencies.
• Static Analysis Tools:
  • PHPStan: Recommended for strict type checking (configure level: 8).
  • Psalm: Alternative if PHPStan isn’t preferred.
  • Rector: Useful for automated type migration (e.g., converting string to Email).
• Laravel-Specific Integrations:
  • Request Validation: Replace array request data with typed value objects (e.g., CreateUserRequest with Email, Password fields).
  • API Responses: Use the package’s types in Fractal/JSON API serializers.
  • Queue Jobs: Enforce types in job payloads (e.g., ProcessOrderJob with OrderId type).

Migration Path

1. Phase 1: Adopt in New Code
   • Start with DTOs for API requests/responses.
   • Example:

     use FlowTypes\Email;
     use FlowTypes\UUID;
     
     class UserRequest {
         public function __construct(
             public Email $email,
             public string $name,
         ) {}
     }
     

2. Phase 2: Retrofit Existing Code
   • Use Rector to automate type conversions (e.g., string → Email).
   • Example Rector rule:

     // rector.php
     return [
         TypeHintingRule::TYPE_HINT_PARAMETER_TO_TYPE_OBJECT(
             Email::class,
             'string'
         ),
     ];
     

3. Phase 3: Database Layer
   • Create Eloquent model traits to cast database fields to package types:

     trait CastsFlowTypes {
         protected function castEmailAttribute(string $value): Email {
             return new Email($value);
         }
     }
     

4. Phase 4: Static Analysis Enforcement
   • Configure PHPStan to fail on untyped code:

     # phpstan.neon
     level: 8
     types:
         - FlowTypes/
     

Compatibility

• Laravel Services: No direct conflicts, but custom types may need serialization handling (e.g., JsonSerializable for API responses).
• Third-Party Packages: Ensure no type collisions with existing libraries (e.g., Ramsey/UUID vs. FlowTypes\UUID).
• Testing: Use Pest/PHPUnit with type-aware assertions:

  expect($userRequest->email)->toBeInstanceOf(Email::class);
  

Sequencing

1. Proof of Concept (PoC):
   • Integrate into a single module (e.g., user registration).
   • Validate with PHPStan and manual tests.
2. Tooling Setup:
   • Configure PHPStan/Psalm in CI (fail builds on type errors).
3. Incremental Rollout:
   • Prioritize high-risk areas (e.g., API contracts, database layers).
4. Deprecation Plan:
   • Gradually replace mixed/array with typed alternatives.
   • Use deprecated attributes for legacy code:

     #[Deprecated('Use Email type instead')]
     public function setEmail(string $email): void { ... }
     

Operational Impact

Maintenance

• Pros:
  • Reduced Runtime Errors: Catches type mismatches at development time.
  • Self-Documenting Code: Types serve as API contracts (e.g., Email vs. string).
• Cons:
  • Type Evolution: If Flow PHP’s types change (e.g., Email validation rules), Laravel code must adapt.
  • Tooling Overhead: PHPStan/Psalm require configuration maintenance (e.g., suppressing false positives).
• Mitigations:
  • Use custom PHPStan rules to enforce Laravel-specific constraints.
  • Document type migration strategies in the team’s style guide.

Support

• Developer Experience:
  • IDE Support: Modern IDEs (PHPStorm, VSCode) will provide autocompletion for custom types.
  • Onboarding: New developers benefit from clear type boundaries, but initial ramp-up may require training on static analysis.
• Debugging:
  • Better Error Messages: PHPStan will flag issues like:

    Argument 1 passed to User::setEmail() must be FlowTypes\Email, string given.
    

  • Runtime Safeguards: Add runtime type guards for critical paths:

    if (!$email instanceof Email) {
        throw new InvalidArgumentException('Email must be a FlowTypes\Email');
    }
    

Scaling

• Performance:
  • Minimal Overhead: Value objects are pass-by-reference in PHP 8.1+.
  • Benchmark: Test serialization/deserialization in API-heavy workflows (e.g., GraphQL).
• Horizontal Scaling:
  • No impact on Laravel’s queue workers or horizon scaling (types are resolved at dev time).
• Database Scaling:
  • Read Models: Consider materialized views for performance if types add query complexity.

Failure Modes