Laminas Httphandlerrunner Laravel Package

## Getting Started

### Minimal Setup
1. **Installation** (PHP 8.5 compatible):
   ```bash
   composer require laminas/laminas-httphandlerrunner:^2.13

Add to composer.json under require if not using autoloader.

2. First Use Case (PHP 8.5 syntax compatible):

   use Laminas\HttpHandlerRunner\Emitter\SapiEmitter;
   use Laminas\HttpHandlerRunner\RequestHandlerRunner;
   use Laminas\Diactoros\Response;
   use Laminas\Diactoros\ServerRequestFactory;
   
   // Create a request from globals
   $request = ServerRequestFactory::fromGlobals();
   
   // Create a simple handler (PHP 8.5 compatible)
   $handler = static fn (\Psr\Http\Message\ServerRequestInterface $request) => new Response('Hello, World!');
   
   // Run the handler and emit
   $runner = new RequestHandlerRunner($handler);
   $response = $runner($request);
   $emitter = new SapiEmitter();
   $emitter->emit($response);
   

3. Where to Look First:

   • PSR-15 Middleware Interface for handler expectations.
   • Laminas\HttpHandlerRunner\RequestHandlerRunner for core execution logic.
   • Laminas\HttpHandlerRunner\Emitter interfaces for response emission.
   • New: PHP 8.5 compatibility notes in migration guide.

Implementation Patterns

Middleware Stacks (PHP 8.5 compatible)

Leverage RequestHandlerRunner with modern PHP syntax:

use Laminas\HttpHandlerRunner\RequestHandlerRunner;

$middlewareStack = [
    static fn (\Psr\Http\Message\ServerRequestInterface $request, callable $next) => $next($request),
    static fn (\Psr\Http\Message\ServerRequestInterface $request, callable $next) => $next($request),
];

$runner = new RequestHandlerRunner($middlewareStack);
$response = $runner($request);

Integration with Laravel (PHP 8.5)

Use in Laravel middleware with type safety:

// app/Http/Middleware/ExampleMiddleware.php
public function handle(
    ServerRequestInterface $request,
    Closure $next
): ResponseInterface {
    $runner = new RequestHandlerRunner($next);
    return $runner($request);
}

Custom Emitters (PHP 8.5)

Extend with modern attributes:

#[Attribute]
class CustomEmitter implements EmitterInterface {
    public function emit(ResponseInterface $response): void {
        // Custom logic
    }
}

Dependency Injection (PHP 8.5)

Register with modern container syntax:

// app/Providers/AppServiceProvider.php
$this->app->bind(RequestHandlerRunner::class, function () {
    return new RequestHandlerRunner($this->app->make(RequestHandlerInterface::class));
});

Gotchas and Tips

Pitfalls

1. PHP 8.5 Breaking Changes:

   • Deprecated: array() constructor syntax is now discouraged. Use [] instead.
   • New: PHP 8.5's static fn syntax is now fully supported for handlers.
   • Fix: Update all array constructors in middleware/handlers.

2. Response Emission:

   • Forgetting to emit responses remains critical. Add this to your base middleware:

     $emitter = new SapiEmitter();
     $emitter->emit($response);
     

3. Middleware Order:

   • PHP 8.5's array_unshift() behavior is preserved. Reverse arrays explicitly:

     $middlewareStack = array_reverse($stack);
     

Debugging (PHP 8.5)

• Log Responses with modern syntax:

  $body = $response->getBody()->getContents();
  \Log::debug('Response', ['body' => $body, 'status' => $response->getStatusCode()]);
  

Extension Points

1. Custom Error Handling (PHP 8.5):

   class CustomRunner extends RequestHandlerRunner {
       public function __invoke(ServerRequestInterface $request): ResponseInterface {
           return match (true) {
               $request->getMethod() === 'HEAD' => new Response('', 200, [], false),
               default => parent::__invoke($request),
           };
       }
   }
   

2. Async Support (PHP 8.5):

   $loop = React\EventLoop\Factory::create();
   $reactEmitter = new ReactEmitter($loop);
   $reactEmitter->emit($response);
   $loop->run();
   

3. Testing (PHP 8.5):

   $this->expectException(InvalidArgumentException::class);
   $runner(new class implements RequestHandlerInterface {
       public function __invoke(ServerRequestInterface $request): ResponseInterface {
           throw new InvalidArgumentException();
       }
   });
   

Config Quirks

• PHP 8.5 Compatibility:
  • SapiEmitter now defaults to strict type checking. Disable with:

    $emitter = new SapiEmitter(['strict_types' => false]);
    

• New: Added UPGRADE.md with PHP 8.5 migration notes.

NO_UPDATE_NEEDED would not apply here as the PHP 8.5 compatibility update warrants significant adjustments to the assessment.