Input Manager Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require alexanevsky/input-manager-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Alexanevsky\InputManagerBundle\InputManagerBundle::class => ['all' => true],
   ];
   

2. First Use Case: Inject InputManager into a controller or service:

   use Alexanevsky\InputManagerBundle\InputManager;
   
   public function __construct(private InputManager $inputManager) {}
   

3. Basic Deserialization: Create an InputInterface class (e.g., UserInput) with public properties matching your request data.

   class UserInput implements InputInterface {
       public string $firstName;
       public string $lastName;
   }
   

   Deserialize JSON input:

   $json = '{"firstName": "John", "last_name": "Doe"}';
   $input = $this->inputManager->deserializeInput($json, UserInput::class);
   

Implementation Patterns

Workflows

1. Request Handling:

   • Use deserializeInput() to convert raw request data (JSON, form, etc.) into an InputInterface object.
   • Example:

     $input = $this->inputManager->deserializeInput(
         $request->getContent(),
         UserInput::class
     );
     

2. Validation:

   • Apply Symfony constraints (e.g., @Assert\NotBlank) to InputInterface properties.
   • Validate with:

     $errors = $this->inputManager->validate($input);
     

   • For custom validation, implement InputValidatorInterface:

     $errors = $this->inputManager->validate($input, CustomValidator::class);
     

3. Mapping to Models:

   • Use the map() method to transform validated input into a model/entity:

     $user = $this->inputManager->map($input, User::class);
     

4. Nested and Collections:

   • For nested objects, define InputInterface classes for each level.
   • For collections, extend AbstractInputCollection:

     class CategoryInputCollection extends AbstractInputCollection {
         public function getClass(): string { return CategoryInput::class; }
     }
     

5. Entity Resolution:

   • Use @EntityFromId to resolve entities by ID:

     #[EntityFromId(Category::class)]
     public Category $category;
     

Integration Tips

• Symfony Forms: Use InputInterface as a DTO for form data binding.
• APIs: Leverage deserialization for JSON payloads (e.g., in API controllers).
• Testing: Mock InputManager to test validation and mapping logic in isolation.

Gotchas and Tips

Pitfalls

1. Property Naming:

   • The deserializer converts snake_case to camelCase (e.g., last_name → lastName). Override with explicit setters if needed.

2. Type Conversion:

   • Empty strings ("") are converted to false for boolean properties. Use @Assert\NotBlank to enforce non-empty values.

3. Entity Resolution:

   • Ensure the entity’s identifier property (e.g., id) matches the expected key in the input (e.g., category_id). Customize with @EntityFromId attributes.

4. Validation Order:

   • Symfony constraints run first; custom validators only execute if constraints pass.

5. Circular References:

   • Avoid circular dependencies in nested inputs (e.g., UserInput referencing ArticleInput which references UserInput).

Debugging

• Validation Errors: Check $errors for TranslatableMessage objects. Use $errors['property']->getMessage() to extract messages.
• Deserialization Issues: Verify property names and types in InputInterface classes. Enable debug mode for detailed exceptions.

Extension Points

1. Custom Modifiers:

   • Implement InputModifiableInterface to modify input data post-deserialization:

     public function modify(): void {
         $this->title = strtoupper($this->title);
     }
     

2. Custom Validators:

   • Extend AbstractInputValidator for reusable validation logic:

     class CustomValidator extends AbstractInputValidator {
         public function validate(): array {
             return ['field' => new TranslatableMessage('Custom error')];
         }
     }
     

3. Type Casting:

   • Override default type conversion by implementing custom logic in InputInterface setters.

4. Configuration:

   • Configure global settings (e.g., default entity managers) via InputManager services.