Permissions Manager Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require dabros-dkos/permissions-manager-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       DabrosDKOS\PermissionsManagerBundle\PermissionsManagerBundle::class => ['all' => true],
   ];
   

2. Database Migration Run the provided migration to create the required tables:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. First Use Case Define a permission in config/packages/permissions_manager.yaml:

   permissions:
       - name: 'user.view'
         label: 'View Users'
         description: 'Allows viewing user profiles'
   

   Assign a permission to a role (e.g., ROLE_ADMIN) in your security configuration:

   security:
       role_hierarchy:
           ROLE_ADMIN: [ROLE_USER, ROLE_PERMISSION_USER_VIEW]
   

Implementation Patterns

Role-Permission Integration

1. Dynamic Permission Assignment Use the PermissionManager service to assign permissions programmatically:

   $permissionManager = $this->container->get('permissions_manager');
   $permission = $permissionManager->findPermission('user.view');
   $role = $permissionManager->findRole('ROLE_ADMIN');
   $role->addPermission($permission);
   $permissionManager->persistRole($role);
   

2. API Endpoint Guarding Secure API routes with permission checks:

   use Symfony\Component\HttpFoundation\Response;
   use Symfony\Component\Security\Core\Exception\AccessDeniedException;
   
   #[Route('/api/users', methods: ['GET'])]
   public function listUsers(PermissionManagerInterface $permissionManager): Response
   {
       if (!$permissionManager->hasPermission('user.view')) {
           throw new AccessDeniedException('Missing permission: user.view');
       }
       // ...
   }
   

3. Bulk Permission Management Use YAML/JSON imports for initial setup:

   # config/packages/permissions_manager/bulk_permissions.yaml
   permissions:
       - { name: 'user.create', label: 'Create Users' }
       - { name: 'user.edit', label: 'Edit Users' }
   

   Load via console:

   php bin/console permissions:import bulk_permissions
   

4. Event-Driven Workflows Listen for permission-related events (e.g., PermissionAssignedEvent):

   // src/EventListener/PermissionListener.php
   public function onPermissionAssigned(PermissionAssignedEvent $event)
   {
       $this->logger->info(sprintf(
           'Permission %s assigned to %s',
           $event->getPermission()->getName(),
           $event->getRole()->getName()
       ));
   }
   

Gotchas and Tips

Debugging

1. Permission Cache Clear the cache after modifying permissions:

   php bin/console cache:clear
   

   Or manually clear the permissions_manager.cache tag:

   php bin/console cache:pool:clear permissions_manager.cache
   

2. Hierarchy Conflicts Ensure role hierarchies in security.yaml align with permission assignments:

   # Avoid this: ROLE_ADMIN inherits ROLE_USER but lacks explicit permission
   role_hierarchy:
       ROLE_ADMIN: ROLE_USER
   

   Fix: Explicitly assign permissions to parent roles.

3. Case Sensitivity Permission names are case-sensitive. Use constants or enums for consistency:

   final class UserPermissions {
       public const VIEW = 'user.view';
   }
   

Extension Points

1. Custom Permission Providers Implement PermissionProviderInterface for dynamic permission sources:

   class DatabasePermissionProvider implements PermissionProviderInterface
   {
       public function getPermissions(): array
       {
           return $this->entityManager->getRepository(Permission::class)->findAll();
       }
   }
   

   Register in services.yaml:

   services:
       App\Service\DatabasePermissionProvider:
           tags: ['permissions_manager.permission_provider']
   

2. Override Default Storage Replace the default Doctrine ORM storage with a custom adapter:

   # config/packages/permissions_manager.yaml
   permissions_manager:
       storage:
           class: App\Permissions\CustomStorage
           arguments: ['@doctrine.orm.entity_manager']
   

3. API Response Integration Attach permissions to API responses for client-side checks:

   return $this->json([
       'data' => $users,
       'meta' => [
           'permissions' => $permissionManager->getUserPermissions($this->getUser())
       ]
   ]);
   

Configuration Quirks

1. YAML Validation Ensure permissions_manager.yaml uses lists (-) for permissions, not maps:

   # Correct
   permissions:
       - name: 'user.view'
         label: 'View Users'
   

   # Incorrect (will fail)
   permissions:
       user.view:
           label: 'View Users'
   

2. Doctrine Lifecycle Events If using custom entities, ensure they implement PermissionsManagerBundle's interfaces (e.g., PermissionInterface).

3. Symfony Security Integration For API platforms, combine with security:vote listeners:

   #[IsGranted('user.view')]
   public function getUser(UserInterface $user): UserDto