Rest Request Validator Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require coka/rest-request-validator-bundle
   

   Add the bundle to config/bundles.php:

   CedrickOka\RestRequestValidatorBundle\CedrickOkaRestRequestValidatorBundle::class => ['all' => true],
   

2. First Use Case: Define a validator for a controller action using annotations:

   use CedrickOka\RestRequestValidatorBundle\Annotation\ValidateRequest;
   
   class UserController extends AbstractController
   {
       /**
        * @ValidateRequest({
        *     "name": {"required": true, "type": "string"},
        *     "email": {"required": true, "type": "email"}
        * })
        */
       public function create(Request $request)
       {
           // Logic here
       }
   }
   

3. Key Files:

   • src/Annotation/ValidateRequest.php (for annotations)
   • config/packages/cedrickoka_rest_request_validator.yaml (default config)

Implementation Patterns

Common Workflows

1. Annotation-Based Validation: Use @ValidateRequest on controller methods to enforce rules:

   /**
    * @ValidateRequest({
    *     "user": {
    *         "required": true,
    *         "type": "object",
    *         "properties": {
    *             "id": {"type": "integer"},
    *             "name": {"type": "string", "maxLength": 50}
    *         }
    *     }
    * })
    */
   public function update(Request $request, int $id)
   {
       // ...
   }
   

2. Dynamic Rule Loading: Load rules from YAML/JSON files (e.g., config/validation/rules.yml):

   user_create:
     name: {required: true, type: string}
     email: {required: true, type: email}
   

   Reference in annotation:

   @ValidateRequest("user_create")
   

3. Event-Based Integration: Subscribe to kernel.request event to validate globally:

   public function onKernelRequest(GetResponseEvent $event)
   {
       $request = $event->getRequest();
       if ($request->isMethod('POST') && $request->getPathInfo() === '/api/users') {
           $validator = $this->container->get('cedrickoka_rest_request_validator.validator');
           $validator->validate($request, ['name', 'email']);
       }
   }
   

4. Custom Validators: Extend the validator service to add business logic:

   $validator->addCustomRule('is_active', function ($value) {
       return $value === 'true' || $value === '1';
   });
   

Integration Tips

• Symfony Forms: Use alongside Symfony’s Validator for hybrid validation.
• API Platform: Combine with API Platform’s Validation extension for OpenAPI schema generation.
• Testing: Mock the validator in PHPUnit:

  $validator = $this->createMock(ValidatorInterface::class);
  $validator->expects($this->once())->method('validate');
  $this->container->set('cedrickoka_rest_request_validator.validator', $validator);
  

Gotchas and Tips

Pitfalls

1. Annotation Parsing:

   • Ensure doctrine/annotations is installed (composer require doctrine/annotations).
   • Cache annotations after changes:

     php bin/console cache:clear
     

2. Rule Conflicts:

   • Overlapping rules (e.g., required: true + default: null) may cause unexpected behavior. Test edge cases.

3. Performance:

   • Avoid validating large payloads (e.g., file uploads) in annotations. Use event listeners for heavy validation.

4. Type System:

   • The bundle uses loose type checking (e.g., "type": "integer" accepts "123" but not "abc"). For strict validation, combine with Symfony’s Assert\Type.

Debugging

• Enable Debug Mode:

  # config/packages/cedrickoka_rest_request_validator.yaml
  debug: true
  

  Logs validation errors to Symfony’s profiler.

• Error Handling: Customize error responses in config/packages/cedrickoka_rest_request_validator.yaml:

  error_handler:
      http_status: 422
      format: json
      message: "Validation failed: %errors%"
  

Extension Points

1. Custom Rule Providers: Implement CedrickOka\RestRequestValidatorBundle\Validator\RuleProviderInterface to add reusable rule sets.

2. Event Dispatching: Extend the bundle’s events (e.g., ValidationFailedEvent) to trigger side effects:

   $dispatcher->addListener(
       'cedrickoka_rest_request_validator.validation_failed',
       function (ValidationFailedEvent $event) {
           // Log, notify, or retry logic
       }
   );
   

3. Configuration Overrides: Override default rules in config/packages/cedrickoka_rest_request_validator.yaml:

   default_rules:
       email: {type: email, message: "Invalid email format"}
   

Pro Tips

• Reuse Rules: Define reusable rule sets in YAML and reference them across controllers.
• Partial Validation: Validate only specific fields:

  $validator->validate($request, ['name', 'email'], ['skip_missing' => true]);
  

• Localization: Support multi-language error messages via Symfony’s translation system:

  # config/packages/cedrickoka_rest_request_validator.yaml
  error_handler:
      translation_domain: "validation"