Request Handler Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require middlewares/request-handler
   

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

2. Basic Usage Register the middleware in app/Http/Kernel.php:

   protected $middleware = [
       \Middlewares\RequestHandler::class,
   ];
   

3. First Use Case Define a handler class (e.g., app/Handlers/ValidateRequest.php):

   namespace App\Handlers;
   
   use Middlewares\RequestHandler\HandlerInterface;
   use Psr\Http\Message\ResponseInterface;
   use Psr\Http\Message\ServerRequestInterface;
   
   class ValidateRequest implements HandlerInterface
   {
       public function __invoke(ServerRequestInterface $request, ResponseInterface $response): ResponseInterface
       {
           if (!$request->getAttribute('valid')) {
               return $response->withStatus(400);
           }
           return $response;
       }
   }
   

   Bind the handler in AppServiceProvider:

   public function boot()
   {
       $this->app->bind(\Middlewares\RequestHandler\HandlerInterface::class, \App\Handlers\ValidateRequest::class);
   }
   

Implementation Patterns

Core Workflows

1. Chaining Handlers Use middleware groups or stack handlers via HandlerInterface:

   // app/Handlers/ChainHandlers.php
   class ChainHandlers implements HandlerInterface
   {
       public function __invoke(ServerRequestInterface $request, ResponseInterface $response)
       {
           $handler = $this->app->make(HandlerInterface::class);
           return $handler($request, $response);
       }
   }
   

2. Conditional Execution Skip handlers based on request attributes or routes:

   if (!$request->getAttribute('skip_validation')) {
       return $handler($request, $response);
   }
   

3. Dependency Injection Inject services into handlers via Laravel’s container:

   class AuthHandler implements HandlerInterface
   {
       protected $auth;
   
       public function __construct(AuthManager $auth)
       {
           $this->auth = $auth;
       }
   
       public function __invoke(ServerRequestInterface $request, ResponseInterface $response)
       {
           if (!$this->auth->check()) {
               return $response->withStatus(401);
           }
           return $response;
       }
   }
   

Integration Tips

• Laravel Routes: Use middleware in route definitions:

  Route::middleware(RequestHandler::class)->group(function () {
      // Routes here
  });
  

• Testing: Mock handlers in PHPUnit:

  $this->app->instance(HandlerInterface::class, MockHandler::class);
  

• Performance: Cache handler instances if stateless (e.g., validation).

Gotchas and Tips

Pitfalls

1. Circular Dependencies Avoid binding handlers that depend on other handlers in the same stack. Use explicit service binding instead.

2. Request/Response Mutations Handlers may unintentionally modify $request or $response. Document expectations clearly:

   // Example: Do NOT modify $request->getParsedBody() if downstream handlers rely on it.
   

3. Middleware Order The package executes handlers after Laravel’s middleware. Reorder in Kernel.php if needed:

   protected $middlewareGroups = [
       'web' => [
           // Custom middleware first...
           \Middlewares\RequestHandler::class,
       ],
   ];
   

4. PSR-15 Compliance Ensure responses adhere to PSR-7 (e.g., withStatus() over setStatusCode()).

Debugging

• Handler Not Triggering? Verify the handler is bound and no exceptions are silently caught. Use:

  try {
      $handler($request, $response);
  } catch (\Throwable $e) {
      report($e); // Log via Laravel's error handler
  }
  

• Response Overrides If a handler returns a response, subsequent handlers won’t execute. Use next($request) pattern if chaining.

Extension Points

1. Custom Handler Resolvers Override the default resolver via a service provider:

   $this->app->bind(
       \Middlewares\RequestHandler\HandlerResolver::class,
       \App\Handlers\CustomResolver::class
   );
   

2. Handler Metadata Tag handlers for dynamic routing (e.g., #[Handler(priority: 10)] via attributes).
3. Async Support Wrap handlers in Laravel\Bus\Queueable for background processing:

   class AsyncHandler implements HandlerInterface, ShouldQueue
   {
       // ...
   }