Http Extra Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alks/http-extra-bundle
   

2. Enable the Bundle: Add to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   Alks\HttpExtraBundle\HttpExtraBundle::class => ['all' => true],
   

3. Enable Annotations (if using Symfony 4+): Add to config/packages/framework.yaml:

   framework:
       annotations:
           cache: null  # Disable annotation cache for development
   

First Use Case: Query Parameter Binding

Create a controller with @RequestParam to bind a query parameter to a method argument:

use Alks\HttpExtraBundle\Annotation as Http;

class UserController extends AbstractController
{
    /**
     * @Route("/user/{id}", methods={"GET"})
     * @Http\RequestParam(name="id", bindTo="userId")
     */
    public function show(int $userId)
    {
        return $this->json(['id' => $userId]);
    }
}

Request: GET /user/123?id=456 → $userId becomes 456.

Implementation Patterns

1. DTO Deserialization

Use @RequestBody to deserialize JSON/XML into a DTO:

use Alks\HttpExtraBundle\Annotation as Http;

class PostController extends AbstractController
{
    /**
     * @Route("/posts", methods={"POST"})
     * @Http\RequestBody(type="json", bindTo="postDto")
     */
    public function create(PostDto $postDto)
    {
        // $postDto is automatically populated from request body
        return $this->json(['success' => true]);
    }
}

Request Body:

{"title": "Hello", "content": "World"}

2. Doctrine Entity Resolution

Resolve Doctrine entities from query params:

/**
 * @Route("/user/{id}", methods={"GET"})
 * @Http\RequestParam(name="id", bindTo="user", repository="AppBundle\Repository\UserRepository")
 */
public function show(User $user)
{
    return $this->json($user);
}

3. Response Customization

Add headers or context to responses:

/**
 * @Route("/data", methods={"GET"})
 * @Http\Response(type="json", context={"groups": {"api"}})
 */
public function getData()
{
    return new Post(); // Automatically serialized with API groups
}

4. Combining Annotations

Mix @RequestParam, @RequestBody, and @RequestData:

/**
 * @Route("/update", methods={"PUT"})
 * @Http\RequestParam(name="id", bindTo="id")
 * @Http\RequestBody(type="json", bindTo="data")
 */
public function update(int $id, array $data)
{
    // $id from query, $data from body
}

5. Validation Integration

Leverage Symfony’s validator with DTOs:

use Symfony\Component\Validator\Constraints as Assert;

class PostDto
{
    /**
     * @Assert\NotBlank()
     */
    public $title;
}

The bundle auto-validates and throws HttpException on failure.

Gotchas and Tips

Pitfalls

1. Annotation Caching:

   • In Symfony 4+, disable annotation cache (cache: null) during development to avoid stale annotations.
   • Fix: Clear cache (php bin/console cache:clear) after adding new annotations.

2. Doctrine Entity Resolution:

   • Requires repository attribute to point to a valid Doctrine repository class.
   • Error: HttpException if the repository doesn’t exist or the entity isn’t found.
   • Tip: Use defaultRepository in config to avoid repetition:

     alks_http_extra:
         default_repository: AppBundle\Repository
     

3. Content Negotiation:

   • The bundle relies on willdurand/negotiation. Ensure Accept headers are set for non-default formats (e.g., XML).
   • Tip: Force format via @Http\Response(type="json").

4. Symfony 4+ Compatibility:

   • The bundle was last updated in 2017 and may not fully support Symfony 5+. Test thoroughly.
   • Workaround: Use symfony/serializer and symfony/expression-language as dev dependencies for compatibility.

5. Validation Errors:

   • Validation errors return HttpException with status 400. Customize error responses via:

     alks_http_extra:
         validation_error_handler: AppBundle\EventListener\ValidationErrorListener
     

Debugging Tips

1. Enable Debug Mode:

   • Set APP_DEBUG=1 to see detailed HttpException messages for binding/validation failures.

2. Check Resolver Logs:

   • Enable Symfony’s profiler to inspect argument resolvers:

     // config/packages/dev/debug.yaml
     framework:
         profiler: { only_exceptions: false }
     

3. Override Default Behavior:

   • Extend the bundle’s services (e.g., http_extra.request_body_resolver) to customize deserialization.

Extension Points

1. Custom Resolvers:

   • Implement Alks\HttpExtraBundle\Resolver\ResolverInterface for custom argument binding logic.

2. Response Transformers:

   • Override Alks\HttpExtraBundle\Response\Transformer\TransformerInterface to modify response serialization.

3. Configuration:

   • Extend config/packages/alks_http_extra.yaml:

     alks_http_extra:
         default_format: json  # Override default response format
         validation_groups: [Default, Api]  # Global validation groups
     

Performance Notes

• Caching: Annotations are parsed once per request (Symfony 3.1+). For high-traffic apps, consider pre-compiling annotations.
• Validation: Disable validation in bulk operations (e.g., imports) by setting validation: false in the annotation:

  @Http\RequestBody(validation=false)