Input Hydrator Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require azjezz/input-hydrator
   

   Add to composer.json under autoload-dev if using for testing:

   "autoload-dev": {
       "psr-4": {
           "Azjezz\\InputHydrator\\": "vendor/azjezz/input-hydrator/src/"
       }
   }
   

2. Basic Usage Define a DTO class (e.g., CreateUserRequest):

   namespace App\DTO;
   
   use Azjezz\InputHydrator\Hydratable;
   
   class CreateUserRequest implements Hydratable
   {
       public string $name;
       public string $email;
       public int $age;
   }
   

3. First Hydration In a controller or service:

   use Azjezz\InputHydrator\Hydrator;
   
   $hydrator = new Hydrator();
   $dto = $hydrator->hydrate(CreateUserRequest::class, $request->all());
   

Implementation Patterns

Common Workflows

1. Request Validation + Hydration Combine with Laravel's validation:

   $validated = $request->validate([
       'name' => 'required|string',
       'email' => 'required|email',
       'age' => 'nullable|integer|min:18',
   ]);
   $dto = $hydrator->hydrate(CreateUserRequest::class, $validated);
   

2. Nested DTOs Support hierarchical data:

   class UserWithAddressRequest implements Hydratable
   {
       public CreateUserRequest $user;
       public AddressRequest $address;
   }
   

3. Service Layer Integration Use in services to decouple request handling:

   class UserService {
       public function create(UserRegistrationRequest $request) {
           // Business logic using $request properties
       }
   }
   

4. Form Requests Extend Laravel's FormRequest for type safety:

   use Azjezz\InputHydrator\Hydratable;
   
   class StoreUserRequest extends FormRequest implements Hydratable {
       public CreateUserRequest $dto;
   }
   

Integration Tips

• Laravel Service Provider Bind Hydrator as a singleton:

  $this->app->singleton(Hydrator::class, function ($app) {
      return new Hydrator();
  });
  

• Dependency Injection Inject Hydrator into controllers/services:

  public function __construct(private Hydrator $hydrator) {}
  

• Custom Rules Extend Hydratable for custom logic:

  class CustomRequest implements Hydratable {
      public function hydrate(array $data): void {
          $data['processed'] = strtoupper($data['name']);
          parent::hydrate($data);
      }
  }
  

Gotchas and Tips

Pitfalls

1. Property Visibility Only public properties are hydrated by default. Use:

   $hydrator->hydrate(CreateUserRequest::class, $data, ['privateProperties' => true]);
   

   Or add #[Hydrate] attribute (if supported in newer versions).

2. Type Mismatches Silent failures occur if input types don’t match DTO properties. Validate first:

   $request->validate([
       'age' => 'integer',
   ]);
   

3. Circular References Avoid recursive DTO structures (e.g., User → Address → User). Use #[Hydrate(ignore: true)] or flatten data.

4. Null Handling Undefined array keys default to null. Explicitly set defaults:

   class UserRequest {
       public ?string $bio = null; // Explicit nullability
   }
   

Debugging

• Enable Strict Mode

  $hydrator->setStrict(true); // Throws exceptions on missing properties
  

• Inspect Hydrated Data Use getHydratedData() to debug:

  $hydrator->hydrate(CreateUserRequest::class, $data);
  dd($hydrator->getHydratedData());
  

Extension Points

1. Custom Hydrators Implement Azjezz\InputHydrator\HydratorInterface for custom logic:

   class CustomHydrator implements HydratorInterface {
       public function hydrate(string $class, array $data, array $options = []): object {
           // Custom logic
       }
   }
   

2. Post-Hydration Processing Use hydrated event (if supported) or a decorator:

   $hydrator->afterHydrate(function ($dto) {
       if ($dto instanceof CreateUserRequest) {
           $dto->email = strtolower($dto->email);
       }
   });
   

3. Configuration Override defaults via constructor:

   $hydrator = new Hydrator([
       'ignore_missing' => false,
       'allow_extra' => true,
   ]);
   

Performance

• Reuse Instances Hydrator is stateless; reuse the same instance across requests.
• Avoid Reflection Overhead For critical paths, pre-compile DTO metadata (if possible) or use #[Attribute] (PHP 8+).