Http Kernel Laravel Package

Getting Started

Minimal Steps to Leverage in Laravel

1. Installation: Laravel already includes symfony/http-kernel as a dependency (via symfony/http-foundation). No additional composer install is needed.

2. First Use Case: Custom Middleware:

   use Symfony\Component\HttpKernel\KernelEvents;
   use Symfony\Component\HttpKernel\Event\RequestEvent;
   use Symfony\Component\EventDispatcher\EventDispatcher;
   
   // In a service provider (e.g., AppServiceProvider)
   public function boot()
   {
       $dispatcher = app(EventDispatcher::class);
       $dispatcher->addListener(KernelEvents::REQUEST, function (RequestEvent $event) {
           // Modify request before it reaches the controller
           $event->getRequest()->attributes->set('custom_data', 'value');
       });
   }
   

3. Where to Look First:

   • Laravel’s HTTP Kernel: app/Http/Kernel.php (extends Symfony\Component\HttpKernel\HttpKernel).
   • Event Listeners: app/Listeners/ or app/Events/ for kernel events.
   • Annotations: Use #[Cache], #[Route], or #[MapRequestPayload] in controllers.

Implementation Patterns

1. Middleware Integration

Workflow:

• Use Symfony’s KernelEvents to tap into the request/response lifecycle.
• Example: Log request payloads before validation:

  use Symfony\Component\HttpKernel\Event\ViewEvent;
  
  $dispatcher->addListener(KernelEvents::VIEW, function (ViewEvent $event) {
      if ($event->getController() instanceof Closure) {
          $request = $event->getRequest();
          \Log::info('Request payload:', $request->request->all());
      }
  });
  

2. Custom Controller Argument Resolution

Pattern: Leverage Symfony’s #[MapRequestPayload] or #[MapUploadedFile] for complex argument binding.

use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;

class UserController extends Controller
{
    public function store(
        #[MapRequestPayload] array $payload,
        #[MapUploadedFile] $avatar
    ) {
        // $payload and $avatar are automatically resolved
    }
}

3. HTTP Caching

Integration:

• Annotation-based caching:

  use Symfony\Component\HttpKernel\Attribute\Cache;
  
  #[Cache(maxAge: 3600, public: true)]
  public function dashboard(): Response
  {
      return response()->view('dashboard');
  }
  

• Fragment caching (for partial views):

  use Symfony\Component\HttpKernel\HttpCache\Store;
  
  $cache = new Store($cachePool);
  $fragment = $cache->get($request, 'sidebar_fragment');
  

4. Event-Driven Workflows

Use Case: Trigger actions on KernelEvents::TERMINATE (e.g., analytics, cleanup).

$dispatcher->addListener(KernelEvents::TERMINATE, function (TerminateEvent $event) {
    $response = $event->getResponse();
    // Log response time or send telemetry
});

5. Sub-Request Handling

Pattern: Use HttpKernelInterface to dispatch sub-requests (e.g., for includes or microservices).

use Symfony\Component\HttpKernel\HttpKernelInterface;

public function includePartial(HttpKernelInterface $kernel)
{
    $subRequest = $kernel->getRequest()->duplicate(
        null,
        null,
        ['_route' => 'partial.route']
    );
    return $kernel->handle($subRequest, HttpKernelInterface::SUB_REQUEST);
}

Gotchas and Tips

Pitfalls

1. Locale Leaks:

   • Issue: Router locale may not reset after sub-requests (fixed in v8.0.8).
   • Fix: Explicitly reset locale in TerminateEvent:

     $event->getRequest()->getLocale() === 'en' ? 'en' : 'default';
     

2. Enum Validation:

   • Issue: Invalid enum values in MapRequestPayload may throw errors (fixed in v8.0.6).
   • Fix: Use #[Assert\Type] or handle gracefully:

     #[MapRequestPayload]
     #[Assert\Type(type: "App\Enum\UserRole::class")]
     public UserRole $role;
     

3. Cache Conflicts:

   • Issue: #[Cache] may ignore explicit Cache-Control headers (fixed in v8.0.1).
   • Fix: Use Cache::new() with public: true or merge directives:

     #[Cache(
         maxAge: 3600,
         public: true,
         vary: ['Accept-Language']
     )]
     

4. Sub-Request Service Reset:

   • Issue: Services may reset between fragment renders (fixed in v8.0.1).
   • Fix: Use HttpKernelInterface::SUB_REQUEST flag:

     $kernel->handle($subRequest, HttpKernelInterface::SUB_REQUEST);
     

5. JSON Coercion:

   • Issue: Ints in JSON may coerce to floats (fixed in v8.0.7).
   • Fix: Validate input types or use #[Assert\Type(type: "integer")].

Debugging Tips

1. Kernel Event Dumping: Enable Symfony’s event profiler in config/profiler.php:

   'enabled' => env('APP_DEBUG'),
   'collectors' => [
       Symfony\Component\HttpKernel\Profiler\EventCollector::class,
   ],
   

2. Request Dumping: Use dd($event->getRequest()) in listeners to inspect:

   • Headers: $request->headers.
   • Attributes: $request->attributes.
   • Payload: $request->request->all().

3. Cache Debugging: Check HttpCacheStore logs or use Cache::get() with debug: true:

   $cache = new Store($pool, [], true); // Enable debug mode
   

Extension Points

1. Custom Value Resolvers: Extend Symfony\Component\HttpKernel\Controller\ValueResolverInterface for custom argument binding:

   class CustomResolver implements ValueResolverInterface
   {
       public function resolve(Request $request, ResolutionEnvironment $environment)
       {
           return new CustomValue();
       }
   }
   

   Register via HttpKernelInterface::setControllerResolver().

2. Event Subscribers: Group related listeners into a subscriber:

   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class AnalyticsSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               KernelEvents::REQUEST => 'onRequest',
               KernelEvents::RESPONSE => 'onResponse',
           ];
       }
   }
   

3. Kernel Extensions: Override Laravel’s kernel by extending Illuminate\Foundation\Http\Kernel and injecting Symfony components:

   class CustomKernel extends HttpKernel
   {
       protected function build(Request $request)
       {
           $this->addListener(KernelEvents::REQUEST, [$this, 'customLogic']);
       }
   }
   

Laravel-Specific Quirks

1. Middleware Priority: Symfony’s middleware runs after Laravel’s. Use ->prepend() or ->append() in app/Http/Kernel.php to control order.

2. Route Annotations: Laravel’s #[Route] is a wrapper around Symfony’s Route. Ensure consistency with Symfony’s requirements and defaults.

3. Service Container: Symfony’s HttpKernelInterface is bound as illuminate.contracts.HttpKernel. Override via:

   $this->app->bind(HttpKernelInterface::class, function ($app) {
       return new CustomKernel($app);
   });