Assert Laravel Package

Technical Evaluation

Architecture Fit

• Validation Layer Synergy: Aligns with Laravel’s service layer and domain-driven design by providing granular, reusable assertions for input/output validation. Complements (but does not replace) Laravel’s built-in Validator for HTTP requests.
• Type Safety: Addresses PHP’s dynamic typing weaknesses with runtime type checks (e.g., isListOf, isMapOf), reducing runtime errors in complex data structures like DTOs or API payloads.
• Domain-Specific Extensions: Fills gaps in webmozart/assert with niche validations (e.g., Bank, Coordinates, IBAN/BIC), critical for industries like finance, logistics, or geospatial applications.
• Error Clarity: Human-readable error messages improve debugging velocity and developer experience, especially in microservices where data flows across boundaries.

Integration Feasibility

• Zero Laravel Overhead: Pure PHP package with no framework dependencies, ensuring drop-in compatibility with existing Laravel monoliths or microservices.
• PSR-4 Compliance: Works seamlessly with Laravel’s autoloader, requiring no additional configuration beyond composer require.
• Facade/Service Provider Pattern: Can be wrapped in Laravel’s DI container for consistent namespace usage (e.g., app()->make('assert') or Assert::isListOf()).
• Testability: Assertions are deterministic and isolatable, making them ideal for unit/integration tests (e.g., validating service inputs in PHPUnit).

Technical Risk

• Low Critical Risk: Built on webmozart/assert (10M+ downloads), with minimal surface area for failure. MIT license eliminates legal concerns.
• High Opportunity Risk:
  • False Sense of Security: Assertions are not a substitute for business logic validation (e.g., "Is this order amount valid?"). Risk of over-reliance on type checks for semantic rules.
  • Edge Case Gaps: Niche validations (e.g., IBAN, BIC) may have undocumented limitations (e.g., locale-specific formats). Requires custom testing.
• Performance Anti-Patterns:
  • N+1 Problem: Deeply nested isListOf/isMapOf calls could lead to exponential validation time for complex structures. Mitigate with early exits or batch validation.
  • Exception Overhead: Throws exceptions on failure, which may bubble unpredictably in async contexts (e.g., queues). Use try-catch or custom handlers.
• Dependency Maturity:
  • Low Stars/Dependents: Indicates early-stage adoption. Monitor for abandonment or security patches.
  • No CI/CD: Absence of visible testing pipelines suggests untested edge cases. Plan for internal test coverage.

Key Questions

1. Validation Strategy:
   • How will this integrate with Laravel’s FormRequest validation? Should assertions be used for domain logic only, or also for API input validation?
   • Example: Use atournayre/assert in App\Services\OrderService but Laravel Validator in App\Http\Requests\StoreOrderRequest.
2. Error Handling:
   • Should assertion failures map to Laravel’s ValidationException for consistent API responses, or use custom exceptions?
   • Example:

     try {
         Assert::isListOf($request->items, Product::class);
     } catch (InvalidArgumentException $e) {
         throw ValidationException::withMessages(['items' => [$e->getMessage()]]);
     }
     

3. Testing Coverage:
   • What edge cases must be tested for niche assertions (e.g., IBAN validation for non-EU countries)?
   • Plan for property-based testing (e.g., with PestPHP) to generate invalid inputs.
4. Maintenance Ownership:
   • Who will triage issues if bugs emerge (e.g., Coordinates validation fails for antipodal points)?
   • Should the team fork the repo if the package stagnates?
5. Alternatives Assessment:
   • Compare with:
     • symfony/validator: More feature-rich but heavier.
     • spatie/laravel-validation-rules: Laravel-specific, but lacks domain assertions.
     • Custom validation traits: Higher maintenance but more control.
   • Decision Matrix:

     Criteria	atournayre/assert	symfony/validator	Custom Traits
     Domain Assertions	✅ (IBAN, Coordinates)	❌	✅ (but manual)
     Performance	⚠️ (Exceptions)	✅ (Batch validation)	✅ (Optimized)
     Laravel Integration	✅ (Easy)	⚠️ (Complex)	✅ (Native)
     Maintenance	❌ (External)	✅ (Active)	❌ (Internal)

Integration Approach

Stack Fit

• Primary Use Cases:
  • Service Layer: Validate method inputs/outputs in Laravel services (e.g., OrderService::calculateTotal()).
  • DTOs/Data Transfer: Enforce type safety for internal data structures (e.g., assert($dto->metadata, isMapOf(Metadata::class))).
  • Microservices: Validate payloads in queue consumers or event listeners (e.g., assert($event->payload, isListOf(OrderItem::class))).
  • CLI/Artisan: Validate command arguments (e.g., assert($args['iban'], isBankAccount())).
• Anti-Patterns:
  • Replacing Laravel’s Validator: Avoid using assertions for HTTP request validation (use FormRequest instead).
  • ORM Constraints: Not suitable for database-level validation (use model observers or database constraints).
  • Performance-Critical Paths: Avoid in high-frequency loops (e.g., bulk processing) due to exception overhead.

Migration Path

1. Pilot Phase (1–2 Sprints):
   • Scope: Select one non-critical service (e.g., UserProfileService) to replace manual validation with assertions.
   • Steps:
     1. Add to composer.json:

        composer require atournayre/assert
        

     2. Replace manual checks:

        // Before
        if (!is_array($data['items']) || !isset($data['items'][0]['id'])) {
            throw new \InvalidArgumentException("Invalid items format.");
        }
        
        // After
        Assert::isListOf($data['items'], Item::class, "Items must be an array of Item objects.");
        

     3. Write unit tests for assertions (see Testing section below).
2. Standardization Phase:
   • Create a Laravel Facade:

     // app/Providers/AppServiceProvider.php
     use Atournayre\Assert\Assert;
     
     public function register()
     {
         $this->app->singleton('assert', function () {
             return new Assert();
         });
     }
     

   • Document Usage:
     • Add PHPDoc examples to services:

       /**
        * @throws \InvalidArgumentException if $items is not a list of Product.
        */
       public function processItems(array $items): void
       {
           Assert::isListOf($items, Product::class);
           // ...
       }
       

3. Error Handling Integration:
   • Map Assertions to Laravel Exceptions:

     // app/Exceptions/Handler.php
     public function register()
     {
         $this->renderable(function (\InvalidArgumentException $e, $request) {
             return response()->json([
                 'message' => $e->getMessage(),
                 'errors' => ['validation' => [$e->getMessage()]],
             ], 422);
         });
     }
     

   • Middleware for API Validation:

     // app/Http/Middleware/ValidateAssertions.php
     public function handle($request, Closure $next)
     {
         try {
             $next($request);
         } catch (\InvalidArgumentException $e) {
             throw ValidationException::withMessages([
                 'error' => [$e->getMessage()]
             ]);
         }
     }
     

Compatibility

• Laravel Versions: Compatible with LTS releases (8.x–10.x). No framework-specific dependencies.
• PHP Versions: Requires PHP 8.0+ (check webmozart/assert compatibility).
• Dependency Conflicts: None expected. webmozart/assert is a low-level dependency with no known conflicts.
• Testing Compatibility:
  • Works with PHPUnit, PestPHP, and Laravel’s testing helpers.
  • Example test:

    use Atournayre\Assert\Assert