Permission Middleware Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require danilovl/permission-middleware-bundle
   

   Ensure Danilovl\PermissionMiddlewareBundle\PermissionMiddlewareBundle::class is registered in config/bundles.php.

2. Basic Configuration: Add to config/packages/danilovl_permission_middleware.yaml:

   danilovl_permission_middleware:
       kernel_controller_priority: 2048  # Default: 2048 (high priority)
       kernel_response_priority: 0       # Default: 0 (low priority)
   

3. First Use Case: Annotate a controller method to restrict access:

   use Danilovl\PermissionMiddlewareBundle\Annotation\Permission;
   
   class AdminController extends AbstractController
   {
       #[Permission('ROLE_ADMIN')]
       public function dashboard(): Response
       {
           return $this->render('admin/dashboard.html.twig');
       }
   }
   

Implementation Patterns

1. Controller-Level Permissions

• Apply permissions to entire controllers:

  #[Permission('ROLE_SUPER_ADMIN')]
  class AdminController extends AbstractController
  {
      // All methods require ROLE_SUPER_ADMIN
  }
  

2. Method-Level Permissions

• Fine-grained control per method:

  class UserController extends AbstractController
  {
      #[Permission('ROLE_USER')]
      public function profile(): Response { ... }
  
      #[Permission('ROLE_EDITOR')]
      public function editProfile(): Response { ... }
  }
  

3. Dynamic Permissions

• Use closures for runtime checks:

  #[Permission(function (Request $request): bool {
      return $request->get('token') === 'secret';
  })]
  public function secureAction(): Response { ... }
  

4. Integration with Symfony Security

• Combine with Symfony’s security system:

  # config/packages/security.yaml
  access_control:
      - { path: ^/admin, roles: ROLE_ADMIN }
  

  Use the bundle for additional middleware checks (e.g., method-level overrides).

5. Custom Permission Providers

• Extend functionality by implementing PermissionProviderInterface:

  use Danilovl\PermissionMiddlewareBundle\Permission\PermissionProviderInterface;
  
  class CustomPermissionProvider implements PermissionProviderInterface
  {
      public function hasPermission(string $permission, Request $request): bool
      {
          // Custom logic (e.g., check database, API, etc.)
          return true;
      }
  }
  

  Register in services:

  services:
      Danilovl\PermissionMiddlewareBundle\Permission\PermissionProviderInterface:
          class: App\Service\CustomPermissionProvider
  

6. Priority Tuning

• Adjust middleware priority in config/packages/danilovl_permission_middleware.yaml:

  danilovl_permission_middleware:
      kernel_controller_priority: 1024  # Lower = earlier execution
      kernel_response_priority: 1024    # Higher = later execution
  

Gotchas and Tips

Pitfalls

1. Annotation Caching:

   • Clear Symfony’s cache (php bin/console cache:clear) after adding/removing annotations.
   • Use #[Permission] only on public methods—private/protected methods are ignored.

2. Priority Conflicts:

   • If permissions fail silently, check kernel_controller_priority vs. other middleware (e.g., Symfony’s SecurityMiddleware).
   • Default 2048 works for most cases, but adjust if using custom middleware.

3. Dynamic Permissions in Tests:

   • Mock PermissionProviderInterface in PHPUnit:

     $this->mockBuilder->setMethods(['hasPermission'])
         ->getMock()
         ->method('hasPermission')
         ->willReturn(true);
     

4. Symfony 8+ Compatibility:

   • Ensure autowire: true is enabled in config/services.yaml for dependency injection to work.

Debugging

• Enable Debug Mode:

  danilovl_permission_middleware:
      debug: true  # Logs denied permissions to Symfony's profiler
  

• Check Profiler: Look for PermissionMiddlewareBundle events in the Symfony profiler under "Middleware."

Extension Points

1. Custom Attributes:

   • Extend the Permission attribute to add metadata:

     #[Attribute]
     class CustomPermission extends Permission
     {
         public function __construct(public string $scope) {}
     }
     

   • Override the bundle’s PermissionReader to handle custom attributes.

2. Event Listeners:

   • Listen to permission.denied events:

     use Danilovl\PermissionMiddlewareBundle\Event\PermissionDeniedEvent;
     
     public function onPermissionDenied(PermissionDeniedEvent $event): void
     {
         $event->setResponse(new RedirectResponse('/unauthorized'));
     }
     

     Register in config/services.yaml:

     services:
         App\EventListener\PermissionListener:
             tags:
                 - { name: kernel.event_listener, event: permission.denied, method: onPermissionDenied }
     

3. Performance:

   • For high-traffic apps, cache permission checks:

     #[Permission(cache: true, ttl: 3600)]  // Cache for 1 hour
     public function cachedAction(): Response { ... }
     

Configuration Quirks

• YAML vs. PHP Config: Prefer PHP config (config/packages/overrides/danilovl_permission_middleware.php) for complex logic:

  return [
      'kernel_controller_priority' => getenv('PERMISSION_PRIORITY') ?: 2048,
  ];
  

• Environment-Specific Rules: Use %env() in YAML:

  danilovl_permission_middleware:
      debug: '%kernel.debug%'