## Getting Started

### Minimal Steps
1. **Installation**:
   ```bash
   composer require symfony/http-kernel:^8.1

Laravel already uses Symfony HttpKernel under the hood, but direct usage now requires awareness of v8.1 breaking changes (e.g., stricter type handling, security fixes).

First Use Case: Create a minimal HTTP kernel with v8.1 security patches (e.g., HEAD request fixes):

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\HttpKernelInterface;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\EventDispatcher\EventDispatcher;

$dispatcher = new EventDispatcher();
$kernel = new class implements HttpKernelInterface {
    public function handle(Request $request, $type = self::MAIN_REQUEST, $catch = true) {
        // HEAD requests now properly bypass method filters (CVE-2026-45075)
        return new Response('Hello, Symfony HttpKernel v8.1!');
    }
};

// Add security-focused middleware
$dispatcher->addListener(KernelEvents::REQUEST, function (RequestEvent $event) {
    $request = $event->getRequest();
    if ($request->isMethod('HEAD')) {
        $event->setResponse(new Response('', 200, [], false)); // No body for HEAD
    }
});

$request = Request::createFromGlobals();
$response = $kernel->handle($request, HttpKernelInterface::MAIN_REQUEST, true);
$response->send();

Where to Look First:
- Symfony HttpKernel v8.1 Upgrade Guide
- Security: CVE-2026-45075 (HEAD request fixes).
- Laravel’s Illuminate\Foundation\Application (now uses Symfony v8.1 under the hood).
- Focus on:
  - HttpKernelInterface (strict type hints in v8.1).
  - Request/Response (HEAD method handling).
  - EventDispatcher (security event listeners).

Implementation Patterns

Core Workflows

Security-Conscious Middleware: Leverage v8.1 security fixes (e.g., IsGranted, IsCsrfTokenValid attributes now respect HEAD requests):

$dispatcher->addListener(KernelEvents::REQUEST, function (RequestEvent $event) {
    $request = $event->getRequest();
    if ($request->isMethod('HEAD') && !$request->headers->has('X-CSRF-Token')) {
        $event->setResponse(new Response('', 403)); // Block insecure HEAD
    }
});

Attribute-Based Routing (v8.1): Use Symfony’s [Route] attribute (requires PHP 8.0+):

use Symfony\Component\Routing\Annotation\Route;

#[Route('/api', methods: ['GET', 'HEAD'])]
public function index(Request $request) {
    return new Response($request->isMethod('HEAD') ? '' : 'Data');
}

Caching with HEAD Support: HttpCache now properly handles HEAD requests (v8.1 fix):

use Symfony\Component\HttpKernel\HttpCache\HttpCache;

$cache = new HttpCache($kernel, $cachePool, $logger);
$response = $cache->handle($request, HttpKernelInterface::MAIN_REQUEST);
// HEAD responses will now cache correctly

Sub-Requests for SSR: Use HttpKernelInterface::SUB_REQUEST with v8.1’s stricter type safety:

$subRequest = Request::create('/partial', 'GET');
$fragment = $kernel->handle($subRequest, HttpKernelInterface::SUB_REQUEST);

Laravel-Specific Patterns

Extending Laravel’s Kernel with v8.1: Override handle() to integrate Symfony’s HEAD request fixes:

// app/Http/Kernel.php
public function handle($request)
{
    $symfonyRequest = Request::create(
        $request->path(),
        $request->method(), // HEAD requests now properly filtered
        $request->query->all(),
        $request->cookies->all(),
        $request->server->all(),
        $request->content()
    );
    $response = $this->symfonyKernel->handle($symfonyRequest);
    return new Illuminate\Http\Response(
        $response->getContent(),
        $response->getStatusCode(),
        $response->headers->all()
    );
}

Event-Driven Middleware with Security Focus: Replace Laravel middleware with Symfony events (now HEAD-safe):

$dispatcher->addListener(KernelEvents::REQUEST, function (RequestEvent $event) {
    $request = $event->getRequest();
    if ($request->isMethod('HEAD')) {
        $event->getRequest()->attributes->set('is_head', true);
    }
});

Custom Value Resolvers for Laravel: Extend ValueResolverInterface with v8.1’s named-attribute support:

use Symfony\Component\HttpKernel\Controller\ValueResolverInterface;

class LaravelRouteResolver implements ValueResolverInterface {
    public function resolve(Request $request, $argument, array $attributes = []): iterable {
        $route = $request->attributes->get('_route');
        yield $request->route()->parameter('model');
    }
}

Gotchas and Tips

Pitfalls

HEAD Request Security Bypass (CVE-2026-45075):
- Issue: Older code using IsGranted/IsCsrfTokenValid attributes may bypass checks for HEAD requests.
- Fix: Explicitly handle HEAD in middleware:
```
if ($request->isMethod('HEAD') && !$this->isCsrfTokenValid($request)) {
    throw new AccessDeniedHttpException();
}
```
Strict Type Hints in v8.1:
- Issue: HttpKernelInterface now enforces stricter return types (e.g., Response must be an instance of Symfony\Component\HttpFoundation\Response).
- Fix: Ensure all responses implement the interface:
```
return new Response('OK', 200, [], false); // Explicitly no body for HEAD
```
Named-Attribute Override Breaking Change:
- Issue: Request/Session value resolvers may override named attributes unexpectedly (fixed in v8.1).
- Fix: Use attributes->get($name, $default) instead of direct access.
CSRF Token Validation for HEAD:
- Issue: Symfony’s CsrfTokenValidator now blocks HEAD requests by default if no token is provided.
- Fix: Configure Laravel to exclude HEAD from CSRF checks:
```
// config/session.php
'csrf' => [
    'except' => ['HEAD'],
];
```

Debugging Tips

Log HEAD Requests: Use KernelEvents::REQUEST to debug HEAD method handling:

$dispatcher->addListener(KernelEvents::REQUEST, function (RequestEvent $event) {
    \Log::debug('Request method:', [$event->getRequest()->getMethod()]);
    if ($event->getRequest()->isMethod('HEAD')) {
        \Log::debug('HEAD request detected');
    }
});

Inspect Attribute Routing: Dump route attributes for debugging:

$attributes = $request->attributes->get('_route_params');
dd($attributes);

Middleware Order for Security: Prioritize security middleware before other listeners:

$dispatcher->addListener(KernelEvents::REQUEST, [$this, 'validateCsrf'], -100); // Highest priority

Extension Points

Custom Kernel with HEAD Support: Extend HttpKernelInterface to handle HEAD requests explicitly:

class ApiKernel implements HttpKernelInterface {
    public function handle(Request $request, $type = self::MAIN_REQUEST, $catch = true) {
        if ($request->isMethod('HEAD')) {
            return new Response('', 200, [], false); // No body
        }
        return $this->next->handle($request, $type, $catch);
    }
}

Dynamic Resolvers for Laravel: Add runtime resolvers for v8.1-compatible type safety:

$resolver->addResolver(new class implements ValueResolverInterface {
    public function resolve(Request $request, $argument, array $attributes = []): iterable {
        if ($argument instanceof \DateTimeInterface) {
            yield new \DateTime();
        }
    }
});

HTTP Exceptions with HEAD Awareness: Convert Laravel exceptions to Symfony’s `Http

Http Kernel Laravel Package