Framework Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require symfony/framework-bundle
   

   This is typically included by default in new Symfony projects via symfony/symfony meta-package.

2. First Use Case:

   • Configuration: Modify config/packages/framework.yaml to adjust core framework behavior (e.g., session, router, HTTP cache).

     framework:
         router:
             default_uri: 'https://example.com'  # Base URL for generated links
         session:
             cookie_lifetime: 3600  # Session cookie lifetime in seconds
     

   • Routing: Define routes in config/routes.yaml or via annotations/attributes in controllers.

     app_home:
         path: /
         controller: App\Controller\HomeController::index
     

3. Key Entry Points:

   • Kernel: Extend AppKernel (Symfony 5+) or use Kernel class in config/bundles.php.
   • Console Commands: Run framework-related commands (e.g., cache management):

     php bin/console cache:clear
     

Implementation Patterns

Core Workflows

1. Dependency Injection (DI) Integration:

   • Service Registration: Use autowiring (default) or manually define services in config/services.yaml.

     services:
         App\Service\MyService:
             arguments:
                 $param: '%env(APP_PARAM)%'
     

   • Compiler Passes: Create custom passes to modify the container:

     use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
     use Symfony\Component\DependencyInjection\ContainerBuilder;
     
     class MyCompilerPass implements CompilerPassInterface {
         public function process(ContainerBuilder $container) {
             $container->getDefinition('my_service')->setArgument(0, 'custom_value');
         }
     }
     

     Register in src/Kernel.php:

     protected function build(ContainerBuilder $container): void {
         $container->addCompilerPass(new MyCompilerPass());
     }
     

2. Configuration Management:

   • Environment Variables: Use %env() placeholders in framework.yaml:

     framework:
         secret: '%env(APP_SECRET)%'
     

   • Parameter Bag: Access parameters via ParameterBagInterface:

     $this->container->getParameter('app.some_param');
     

3. Routing and Controllers:

   • Attribute Routing (Symfony 5.3+):

     #[Route('/profile', name: 'app_profile')]
     public function profile(): Response { ... }
     

   • Legacy Annotations: Enable in config/packages/framework.yaml:

     framework:
         router:
             annotation_directory: '%kernel.project_dir%/src/Controller'
     

4. Testing Patterns:

   • Kernel Tests: Use KernelTestCase for full-stack testing:

     use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
     
     class MyTest extends KernelTestCase {
         public function testSomething() {
             $client = static::createClient();
             $client->request('GET', '/');
             $this->assertResponseIsSuccessful();
         }
     }
     

   • Mocking Services: Override services in tests:

     $this->container->set('my_service', $mockService);
     

5. Event Listeners/Subscribers:

   • Register listeners in config/services.yaml:

     services:
         App\EventListener\MyListener:
             tags:
                 - { name: 'kernel.event_listener', event: 'kernel.request', method: 'onKernelRequest' }
     

Integration Tips

1. Bundles:

   • Enable third-party bundles in config/bundles.php:

     return [
         // ...
         Symfony\WebServerBundle\WsserverBundle::class => ['all' => true],
     ];
     

2. HTTP Cache:

   • Configure in framework.yaml:

     framework:
         http_cache:
             enabled: true
             lifetime: 3600
     

3. Error Handling:

   • Customize error pages in config/packages/twig.yaml and templates/bundles/framework/exceptions.html.twig.

4. Debugging:

   • Enable debug mode in .env:

     APP_ENV=dev
     APP_DEBUG=1
     

   • Use the profiler at /_profiler.

Gotchas and Tips

Common Pitfalls

1. Caching Issues:

   • Symptom: Changes to config/ or src/ not reflected.
   • Fix: Clear the cache:

     php bin/console cache:clear
     

   • Debug: Use cache:pool:prune to clean stale cache files.

2. Router Context:

   • Issue: router.request_context.base_url not updating with default_uri.
   • Fix: Ensure default_uri is set in framework.yaml and the cache is cleared.

3. Session Problems:

   • Symptom: Session cookie lifetime ignored in tests.
   • Fix: Use MockSessionStorage or ensure cookie_lifetime is set in framework.yaml:

     framework:
         session:
             cookie_lifetime: 3600
             storage_factory_id: session.storage.mock_file
     

4. KernelTestCase Quirks:

   • Issue: Stale container after reboot.
   • Fix: Override ensureKernelShutdown():

     protected function ensureKernelShutdown(): void {
         parent::ensureKernelShutdown();
         $this->container->get('kernel')->terminate($this->container, new Request());
     }
     

5. Attribute Routing:

   • Legacy Annotations: Ensure annotation_reader is enabled in framework.yaml for backward compatibility:

     framework:
         router:
             annotation_reader: 'annotation_reader'
     

6. Service Mocking:

   • Decorated Services: Use MockBuilder for decorated services:

     $mock = $this->createMock(DecoratedService::class);
     $this->container->set('decorated_service', $mock);
     

7. Config Reference:

   • Issue: debug:config fails with TypeError on scalars.
   • Fix: Update to the latest Symfony version or patch ConfigDebugCommand.

Debugging Tips

1. Debug Configuration:

   • Dump the full config:

     php bin/console debug:config framework
     

   • Check for typos or missing keys.

2. Event Dispatcher:

   • List all listeners:

     php bin/console debug:event-dispatcher
     

3. Container Dumping:

   • Generate a dump of services:

     php bin/console debug:container --parameters
     

4. Environment Variables:

   • Validate .env files:

     php bin/console debug:env
     

Extension Points

1. Custom Compiler Passes:

   • Extend the container build process (e.g., for dynamic service configuration).

2. Event Subscribers:

   • Hook into kernel events (e.g., kernel.request, kernel.response).

3. HttpKernel Interface:

   • Implement custom HttpKernelInterface for advanced request/response handling.

4. Routing Resolvers:

   • Create custom UrlGenerator or RouterInterface implementations.

5. Configuration Normalizers:

   • Extend ConfiguratorInterface for custom config validation/transformation.

Pro Tips

• Use ParamConfigurator: For dynamic parameter values in config:

  framework:
      secret: '%param("app.secret")%'
  

• Leverage KernelTestCase: For isolated, fast tests with a fresh container.
• Monitor Cache: Use cache:pool:prune to clean up stale cache files during development.
• Debug Profiler: Enable APP_DEBUG=1 and use /_profiler to inspect requests, events, and services.