Framework Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require symfony/framework-bundle
   

   Typically pulled in automatically via symfony/symfony or symfony/flex.

   v8.1.8 note: FrameworkBundle now requires symfony/dependency-injection: ^8.1.8. If you pin DependencyInjection explicitly, bump both together: composer update symfony/framework-bundle symfony/dependency-injection --with-dependencies.

2. First Use Case:

   • Bootstrapping the Framework: The bundle is auto-registered in the kernel (config/bundles.php). No manual configuration needed for basic usage.
   • Dependency Injection: Autowire services from the container:

     use Symfony\Component\HttpKernel\KernelInterface;
     
     public function __construct(private KernelInterface $kernel) {}
     

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

     # config/routes.yaml
     app_homepage:
         path: /
         controller: App\Controller\HomeController::index
     

3. Where to Look First:

   • Docs: Symfony FrameworkBundle Docs
   • Configuration: config/packages/framework.yaml (generated by Flex).
   • Kernel / Bundles: config/bundles.php.
   • Changelog: https://github.com/symfony/framework-bundle/compare/v8.1.7...v8.1.8 (all patch-level; no BC breaks).

Implementation Patterns

Core Workflows

1. Service Configuration:

   • Configure core features (session, cache, HTTP cache) in framework.yaml:

     # config/packages/framework.yaml
     framework:
         session:
             handler_id: cache.app
         http_cache:
             invalidation:
                 enabled: true
     

   • Environment Overrides: config/packages/dev/framework.yaml, config/packages/prod/framework.yaml.

2. Dependency Injection:

   • Autowiring: Type-hint constructor args (RequestStack, RouterInterface, HttpClientInterface).
   • Tagging: Use attributes for event listeners:

     #[Tag('kernel.event_listener', ['event' => 'kernel.request'])]
     class MyListener {}
     

   • Env Closures as Arguments (fixed in 8.1.8): services whose arguments are env-var closures are now described correctly by debug:container. If you previously saw (closure) / errors while inspecting such services, re-run:

     php bin/console debug:container App\Service\MyService
     

3. Routing and Controllers:

   • Attribute Routing (the only supported style on Symfony 7/8 — annotations were removed):

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

   • Webhook Routing: The description of an empty webhook routing secret was clarified in 8.1.8 — the failure message now reflects that the secret is genuinely missing rather than malformed. Check framework.webhook.routing keys if you see it.

4. HTTP Client:

   • HTTP/2 push is disabled on the default client as of 8.1.8. Push-related curl options are no longer exercised, so do not build cache-priming/preload logic on top of http_client push:

     framework:
         http_client:
             default_options:
                 # HTTP/2 push no longer applies to the default client
     

5. Serialization:

   • Serializer metadata caching in debug mode (8.1.8): metadata coming from mapping files (YAML/XML) is now cached even with the debug container. Useful for perf, but it means edits to mapping files may not be picked up until the cache is cleared (see Gotchas).

6. Testing:

   • Kernel Tests:

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

   • Mocking Services: Reach into the test container; prefer static::getContainer() in modern versions.

7. Event Listeners / Subscribers:

   services:
       App\EventListener\MyListener:
           tags: ['kernel.event_listener']
       App\EventListener\MySubscriber:
           tags: ['kernel.event_subscriber']
   

8. Console Commands:

   #[AsCommand(name: 'app:greet')]
   class GreetCommand extends Command {}
   

   Register with tags: ['console.command'].

9. Configuration Reference:

   php bin/console config:dump-reference framework
   

Integration Tips

• Custom Bundles: Implement BundleInterface / extend AbstractBundle to wrap FrameworkBundle features.
• Env Vars: %env(APP_SECRET)% in config, values in .env / .env.local.
• Debugging: APP_DEBUG=1 + Web Profiler at /_profiler.
• Secrets: If you use DotenvVault, see the back-reference fix in Gotchas before rotating secrets.

Gotchas and Tips

Pitfalls

1. Composer / Version Constraints (new in 8.1.8):

   • symfony/framework-bundle 8.1.8 requires symfony/dependency-injection ^8.1.8. A partial upgrade (composer update symfony/framework-bundle) without updating DependencyInjection will fail resolution. Use --with-dependencies, or bump both entries in composer.json together.

2. HTTP/2 Push Silently Ignored (new in 8.1.8):

   • Push is disabled on the default HTTP client. Config that previously enabled push won't error — it just does nothing. Remove it from your config rather than debugging why assets aren't pushed.
   • Push was already deprecated in browsers; this is a cleanup, not a regression.

3. Serializer Metadata Cache in Debug Mode (new in 8.1.8):

   • Mapping-file metadata is now cached even when debug is on. If you edit a serializer mapping and the change doesn't appear:

     php bin/console cache:clear
     

     Don't waste time debugging the serializer config itself — it's the cache.

4. DotenvVault Back-References (new in 8.1.8):

   • A fix prevents vault values containing back-references (e.g. $OTHER_VAR inside a sealed value) from being corrupted on decrypt. If you sealed such values with an older 8.1.x, re-verify them and re-seal if the decrypted value looks mangled:

     php bin/console secrets:list
     

5. Caching Quirks:

   • Cache Warmup: php bin/console cache:warmup after config changes.
   • Stale Containers in Tests: Don't reuse a kernel across tests; KernelTestCase handles shutdown.

6. Routing Issues:

   • Attribute routing is the default and only style on 8.x — annotations are gone. Old docs referencing use_attribute_as_key are historical; that's a YAML loader option, not a router toggle.
   • Route conflicts: explicit YAML routes and attribute routes are merged; check priority with debug:router.

7. Dependency Injection:

   • Circular Dependencies: Break with autowire: false + explicit bindings, or a lazy service.
   • Service Not Found: Confirm registration/tag in services.yaml and that the class is in the autodiscovery path.

8. Session Handling:

   • Mock Sessions in Tests:

     $session = new Session();
     $session->setStorage(new MockSessionStorage());
     static::getContainer()->set('session', $session);
     

   • Cookie Lifetime: Set cookie_lifetime explicitly for session cookies.

9. Configuration Merging:

   • Symfony merges configs left-to-right; override defaults in config/packages/overrides.yaml.
   • Use config:dump-reference to check the real shape before guessing.

10. Testing Gotchas:

    • self::ensureKernelShutdown() when testing HTTP cache.
    • Mock decorated services explicitly by their decorator ID.

11. Console Commands:

    • symfony/console must be installed; the command data collector only exists when it is.

Debugging Tips

php bin/console debug:container            # now handles env-closure args (8.1.8 fix)
php bin/console debug:container App\MyService
php bin/console debug:router
php bin/console debug:env
php bin/console debug:config framework
php bin/console debug:event-dispatcher
php bin/console debug:serializer           # check mapping/attribute metadata

Extension Points

1. Custom Configurators: implement ConfiguratorInterface for config validation/normalisation.
2. Event Subscribers: EventSubscriberInterface for kernel.request, kernel.response, etc.
3. HttpKernel Extensions: override HttpKernelInterface for cross-cutting request/response handling.
4. Compiler Passes: modify the container at compile time (PassConfig).
5. Routing Loaders: custom LoaderInterface for dynamic routes.

Performance Tips

• Cache Pools: cache.app for session storage to offload the DB.
• Serializer Metadata: with 8.1.8, mapping-file metadata is cached even in debug — expect faster dev boots for heavily-mapped apps, but be aware of the staleness trade-off.
• HTTP Cache: enable framework.http_cache for shared caching of anonymous responses.
• OPcache: enable bytecode caching in every environment.

Security Tips

• CSRF: framework.csrf_protection.enabled: true.
• HSTS:

  framework:
      http_client:
          headers:
              Strict-Transport-Security: "max-age=31536000; includeSubDomains"
  

• Webhook Secrets: an empty routing secret is now reported as empty (8.1.8) — treat it as a config error and set one per webhook parser.
• CORS: use nelmio/cors-bundle.