Http Kernel Laravel Package

Getting Started

Minimal steps

1. Install or update the component:

   composer require symfony/http-kernel
   composer update symfony/http-kernel
   

   Laravel already ships this component. If you are on the 5.4 LTS line, upgrade to v5.4.54+ to receive the latest security fixes; use the equivalent patch for your Symfony version.

2. Core concepts

   • HttpKernelInterface turns a Request into a Response through a structured pipeline.
   • Key classes: HttpKernelInterface, Request, Response, EventDispatcher, HttpKernel.
   • Laravel’s App\Http\Kernel extends Illuminate\Foundation\Http\Kernel and implements Symfony’s HttpKernelInterface; it does not extend Symfony’s Kernel.

3. First use case

   use Illuminate\Http\Request;
   use Illuminate\Contracts\Http\Kernel;
   
   $request = Request::capture();
   $response = app(Kernel::class)->handle($request);
   $response->send();
   

4. Where to look first

   • Laravel: app/Http/Kernel.php and Illuminate\Foundation\Http\Kernel.
   • Symfony docs: HttpKernel Component.
   • Vendor source: vendor/symfony/http-kernel/.

Implementation Patterns

Request handling pipeline

$response = app(\Illuminate\Foundation\Http\Kernel::class)->handle(
    $request,
    \Symfony\Component\HttpKernel\HttpKernelInterface::MAIN_REQUEST,
    true // catch exceptions
);

• MAIN_REQUEST runs the full HTTP lifecycle.
• SUB_REQUEST is used for fragments and internal dispatches.

Middleware integration Laravel uses its own middleware pipeline, not Symfony’s MiddlewareInterface:

// app/Http/Kernel.php
protected $middleware = [
    \App\Http\Middleware\TrustProxies::class,
    // ...
];

Use middleware for cross-cutting request/response concerns; use kernel events when you need to hook the Symfony-level lifecycle.

Event-driven extensions

use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\HttpKernel\Event\RequestEvent;

$dispatcher->addListener(KernelEvents::REQUEST, function (RequestEvent $event) {
    $request = $event->getRequest();
    // inspect or modify the request
});

Register listeners in a service provider or a package boot method.

Sub-requests for fragments

$subRequest = $request->duplicate(null, null, ['_route' => 'partial.route']);
$fragment = app(\Illuminate\Foundation\Http\Kernel::class)->handle(
    $subRequest,
    \Symfony\Component\HttpKernel\HttpKernelInterface::SUB_REQUEST
);

HttpCache

use Symfony\Component\HttpKernel\HttpCache\HttpCache;

$cache = new HttpCache($kernel, $cacheDir);
$response = $cache->handle($request);

After v5.4.54, cache-internal headers are stripped from backend responses; do not rely on those headers surviving the cache layer.

Integration tips

• Extend Laravel’s kernel rather than building a custom Symfony kernel for normal HTTP work.
• Use HttpKernelBrowser for lightweight kernel-level tests:

  use Symfony\Component\HttpKernel\HttpKernelBrowser;
  
  $client = new HttpKernelBrowser($kernel);
  $client->request('GET', '/');
  

• When using HttpCache in long-running or worker environments, ensure the cache directory is shared and writable.

Gotchas and Tips

Pitfalls

1. Security release v5.4.54

   • Upgrade to v5.4.54+ (or the corresponding patch for your branch). It includes fixes for UriSigner, profiler token handling, session ID reuse, HttpCache header stripping, and unserialize hardening.
   • Treat this as a required patch if you run 5.4 LTS.

2. HttpCache internal headers

   • v5.4.54 strips cache-internal headers from backend responses. If you previously inspected those headers in application code, move that inspection into cache-specific debugging instead of relying on them in normal responses.

3. UriSigner hash parameter

   • The release fixes a TypeError when the hash parameter is not a string. Still validate signed URL input; do not assume query parameters have the expected type.

4. Profiler token validation

   • Profiler tokens are now validated before being used as file names. If you have custom profiler storage or tooling, validate tokens before using them in file paths or cache keys.

5. Session ID reuse in long-running processes

   • The kernel now ignores a session ID PHP kept from a previous request. This matters for Octane/RoadRunner-style workers; ensure you are on the patched version before relying on session isolation between requests.

6. Unserialize hardening

   • CacheWarmerAggregate, LoggerDataCollector, and HttpCache store now use allowed_classes => false when unserializing. If you store custom objects in those areas, verify the data still round-trips correctly.

7. Locale handling

   • Symfony’s kernel resets the router locale after handling a request. Preserve and restore it manually if your API depends on locale persistence.

8. HEAD requests

   • Method-based security filters should explicitly account for HEAD. Do not assume GET-only checks cover HEAD.

9. Enum and argument handling

   • Backed enums from request payloads can fail silently or throw; handle ValueError explicitly.
   • Validate controller argument references early if you build them dynamically.

Debugging tips

$dispatcher->addListener(KernelEvents::EXCEPTION, function ($event) {
    \Log::error('Kernel exception', [
        'exception' => $event->getThrowable(),
        'request' => $event->getRequest()->query->all(),
    ]);
});

• Dump requests and responses during development, but avoid leaving verbose dumps in production paths.
• Check deprecations when upgrading across major versions; prefer KernelInterface::VERSION over deprecated constants.

Extension points

1. Custom event listeners

   $dispatcher->addListener(KernelEvents::FINISH_REQUEST, function ($event) {
       $event->getResponse()->headers->set('X-Custom-Header', 'value');
   });
   

2. Override kernel bootstrapping

   public function boot()
   {
       parent::boot();
       // custom boot logic
   }
   

3. Modify request/response globally

   $dispatcher->addListener(KernelEvents::REQUEST, function ($event) {
       $event->setRequest($event->getRequest()->withHeader('X-Processed', 'true'));
   });
   

4. Handle exceptions

   $dispatcher->addListener(KernelEvents::EXCEPTION, function ($event) {
       if ($event->getThrowable() instanceof \Symfony\Component\HttpKernel\Exception\HttpExceptionInterface) {
           return;
       }
       $event->setResponse(new \Symfony\Component\HttpFoundation\Response('Custom error', 500));
   });
   

5. Sub-request caching

   $cache = new HttpCache($kernel, $cacheDir);
   $fragment = $cache->handle($subRequest, HttpKernelInterface::SUB_REQUEST);
   

   Keep cache-internal concerns isolated from application code; after v5.4.54 those headers are stripped from backend responses.