Framework Extra Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation (if not using Symfony 6.2+):

   composer require sensio/framework-extra-bundle
   

   Note: For new projects, prefer Symfony’s native attributes (since 6.2).

2. Enable the Bundle (in config/bundles.php):

   return [
       // ...
       Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle::class => ['all' => true],
   ];
   

3. First Use Case: Add a route annotation to a controller method:

   use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
   
   class ProductController extends AbstractController
   {
       /**
        * @Route("/products/{id}", name="product_show")
        */
       public function show($id)
       {
           return $this->render('product/show.html.twig', ['id' => $id]);
       }
   }
   

4. Key Files:

   • config/routes.yaml (for YAML-based routes, but annotations are still useful for dynamic logic).
   • src/Controller/ (where annotations are applied).

Implementation Patterns

Common Workflows

1. Route Configuration:

   /**
    * @Route("/api/v1/users", name="user_list", methods={"GET"}, defaults={"page"=1})
    */
   public function listUsers(Request $request)
   {
       // ...
   }
   

   • Dynamic Segments: {id} captures URL parameters.
   • Defaults: Set default values (e.g., page=1).
   • Methods: Restrict HTTP methods (GET, POST).

2. ParamConverter (for Doctrine entities):

   use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;
   
   /**
    * @ParamConverter("user", class="App\Entity\User")
    */
   public function editUser(User $user)
   {
       // $user is automatically fetched from DB
   }
   

3. Security Annotations:

   use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security;
   
   /**
    * @Security("is_granted('ROLE_ADMIN')")
    */
   public function adminDashboard()
   {
       // ...
   }
   

4. Template Rendering:

   use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;
   
   /**
    * @Template("product/show.html.twig")
    */
   public function showAction($id)
   {
       return ['id' => $id];
   }
   

5. Integration with Symfony’s Router: Dump routes to verify:

   php bin/console debug:router
   

Best Practices

• Group Annotations: Use @Route at the class level for shared prefixes:

  /**
   * @Route("/api/v1")
   */
  class ApiController extends AbstractController
  {
      /**
       * @Route("/users", name="api_user_list")
       */
      public function listUsers() { ... }
  }
  

• Avoid Overuse: Prefer YAML/XML routes for static paths; use annotations for dynamic logic (e.g., conditional routes).
• IDE Support: Enable PHP Annotations in your IDE (e.g., PHPStorm) for autocompletion.

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • The bundle is unmaintained. Migrate to Symfony’s native attributes (since 6.2):

     #[Route("/products/{id}", name: "product_show")]
     public function show($id) { ... }
     

   • For earlier versions, use symfony/property-info for partial compatibility.

2. Annotation Parsing Order:

   • Class-level annotations (e.g., @Route) are merged with method-level ones. Method-level annotations override class-level ones for the same key.

3. Caching Issues:

   • Clear the cache after adding/removing annotations:

     php bin/console cache:clear
     

4. ParamConverter Quirks:

   • Ensure the converted class (e.g., App\Entity\User) exists and is mapped by Doctrine.
   • For custom converters, implement Sensio\Bundle\FrameworkExtraBundle\Request\ParamConverter\ParamConverterInterface.

5. Security Annotations:

   • Requires Symfony’s Security component. Misconfigured annotations may throw AccessDeniedException.

Debugging Tips

• Route Debugging:

  php bin/console debug:router | grep "product_show"
  

• Annotation Validation: Use sensio/framework-extra-bundle's built-in validation (Symfony’s validator component) to catch syntax errors early.

Extension Points

1. Custom ParamConverters:

   namespace App\ParamConverter;
   
   use Sensio\Bundle\FrameworkExtraBundle\Request\ParamConverter\ParamConverterInterface;
   
   class CustomConverter implements ParamConverterInterface
   {
       public function supports(ParamConverter $configuration)
       {
           return $configuration->getClass() === 'App\Entity\CustomEntity';
       }
   
       public function convert(Request $request, ParamConverter $configuration)
       {
           // Custom logic
       }
   }
   

   Register in services.yaml:

   services:
       App\ParamConverter\CustomConverter:
           tags:
               - { name: 'sensio_framework_extra.param_converter' }
   

2. Event Listeners: Listen to kernel.request to modify annotations dynamically:

   use Symfony\Component\HttpKernel\Event\RequestEvent;
   
   public function onKernelRequest(RequestEvent $event)
   {
       $request = $event->getRequest();
       if ($request->attributes->get('_route') === 'dynamic_route') {
           // Modify annotations via reflection or service container
       }
   }
   

3. Configuration Overrides: Override bundle settings in config/packages/sensio_framework_extra.yaml:

   sensio_framework_extra:
       router:
           annotations: true  # Default; can be disabled
       view:
           annotations: true
   

Migration to Native Attributes

• Step-by-Step:

  1. Replace @Route with #[Route].
  2. Replace @ParamConverter with #[ParamConverter] (Symfony 6.2+).
  3. Update composer.json to remove sensio/framework-extra-bundle.
  4. Clear cache and test routes.

• Tools: Use symfony/flex or symfony/var-dumper to audit annotations before migration.