Kernel Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require baikal/kernel-bundle
   

   Register the bundle in config/bundles.php (Symfony context):

   return [
       // ...
       Baikal\KernelBundle\BaikalKernelBundle::class => ['all' => true],
   ];
   

2. First Use Case The bundle provides a kernel abstraction layer for Symfony applications, allowing seamless integration with Baïkal (a CalDAV/CardDAV server). Start by leveraging its event system or kernel extensions for custom logic.

   Example: Subscribe to kernel events in a service:

   use Baikal\KernelBundle\Event\KernelEvents;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class MyEventSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               KernelEvents::BOOT => 'onKernelBoot',
           ];
       }
   
       public function onKernelBoot()
       {
           // Custom logic here
       }
   }
   

3. Where to Look First

   • Events: Check src/Event/ for available events (e.g., KernelEvents::BOOT, KernelEvents::TERMINATE).
   • Extensions: Explore src/DependencyInjection/ for compiler passes or extensions.
   • Configuration: Review Resources/config/services.yaml for default services.

Implementation Patterns

Common Workflows

1. Event-Driven Logic Use the bundle’s events to hook into kernel lifecycle phases (e.g., BOOT, TERMINATE, REQUEST). Example:

   // Subscribe to TERMINATE for cleanup
   KernelEvents::TERMINATE => [$this, 'onKernelTerminate'],
   

2. Kernel Extensions Extend the kernel behavior via compiler passes or service overrides. Example:

   # config/packages/baikal_kernel.yaml
   baikal_kernel:
       extensions:
           - App\Extension\MyCustomExtension
   

3. Baïkal Integration If using Baïkal (CalDAV/CardDAV), leverage the bundle to:

   • Validate requests before forwarding to Baïkal.
   • Modify responses (e.g., headers, status codes).
   • Example middleware:

     use Baikal\KernelBundle\Middleware\BaikalRequestMiddleware;
     
     // Add to kernel middleware (Symfony 5.3+)
     $middleware->add(BaikalRequestMiddleware::class);
     

4. Configuration Overrides Override default Baïkal settings via bundle configuration:

   baikal_kernel:
       auth:
           enabled: true
           provider: "custom_auth_service"
   

Integration Tips

• Symfony Flex: If using Symfony Flex, autoloading is handled automatically.
• Testing: Mock kernel events in tests:

  $event = new KernelEvent($kernel);
  $this->dispatcher->dispatch(KernelEvents::BOOT, $event);
  

• Debugging: Enable debug mode in config/packages/dev/baikal_kernel.yaml:

  baikal_kernel:
       debug: true
  

Gotchas and Tips

Pitfalls

1. Event Dispatching Order

   • Events like BOOT fire before the request is processed. Use REQUEST for request-specific logic.
   • Example: Avoid modifying the Request object in BOOT if it hasn’t been initialized yet.

2. Baïkal Dependency

   • The bundle assumes Baïkal is installed. If Baïkal is missing, the bundle may throw RuntimeException. Validate dependencies early:

     if (!extension_loaded('baikal')) {
         throw new \RuntimeException('Baïkal extension not loaded.');
     }
     

3. Configuration Conflicts

   • Overriding baikal_kernel settings in multiple places (e.g., config/packages/ and config/bundles.php) may cause silent failures. Use environment-specific configs (e.g., dev/, prod/).

4. Middleware Stack

   • If using Symfony middleware, ensure BaikalRequestMiddleware is placed before other middleware that might alter the request early.

Debugging Tips

1. Enable Verbose Logging Add to config/packages/dev/monolog.yaml:

   handlers:
       baikal:
           type: stream
           path: "%kernel.logs_dir%/baikal.log"
           level: debug
           channels: ["baikal_kernel"]
   

2. Check Event Subscribers Use Symfony’s debug:event-dispatcher command to list subscribed events:

   php bin/console debug:event-dispatcher
   

3. Compiler Passes If extensions aren’t loading, verify compiler passes in src/DependencyInjection/ are registered in BaikalKernelBundle::build().

Extension Points

1. Custom Events Extend the bundle by dispatching your own events:

   $this->dispatcher->dispatch(new MyCustomEvent($data));
   

2. Kernel Listeners Implement Baikal\KernelBundle\EventListener\KernelListenerInterface for custom listeners:

   class MyListener implements KernelListenerInterface
   {
       public function handle(KernelEvent $event) { ... }
   }
   

3. Service Overrides Override services via autowiring or YAML:

   services:
       Baikal\KernelBundle\Service\DefaultService:
           class: App\Service\CustomService