User Role Type Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require coosos/user-role-type-bundle "^2.0"
   

   Ensure your project uses Symfony 3.4, 4.0, or 5.0 and PHP 7.1+.

2. Enable the Bundle: Add to config/bundles.php (Symfony 4/5) or AppKernel.php (Symfony 3):

   Coosos\UserRoleTypeBundle\CoososUserRoleTypeBundle::class => ['all' => true],
   

3. First Use Case: In a form builder (e.g., UserType), add the role field:

   use Coosos\UserRoleTypeBundle\Form\Type\UserRoleType;
   
   $builder->add('roles', UserRoleType::class, [
       'coosos_security_checked' => 'strict', // or 'loose'
   ]);
   

4. Template Integration: Use the default Twig template or override it (see Implementation Patterns).

Implementation Patterns

Core Workflows

1. Role Assignment in Forms:

   • Use UserRoleType for role selection in user creation/editing forms.
   • Example:

     $builder->add('roles', UserRoleType::class, [
         'multiple' => true, // Allow multi-role assignment
         'expanded' => true, // Checkbox layout (default: dropdown)
         'choices' => $roleManager->getRoles(), // Customize available roles
     ]);
     

2. Dynamic Role Sources:

   • Inject a RoleManager (e.g., from Symfony’s security.role_hierarchy) to fetch roles dynamically:

     $builder->add('roles', UserRoleType::class, [
         'role_manager' => $this->roleManager, // Service ID or instance
     ]);
     

3. Validation Integration:

   • Leverage Symfony’s validation constraints (e.g., @Assert\All, @Assert\Count) on the roles field:

     # config/validation.yaml
     App\Entity\User:
         properties:
             roles:
                 - All: { type: string }
                 - Count: { min: 1, max: 5 }
     

4. Twig Overrides:

   • Customize the role field rendering by overriding the Twig template:

     {# templates/CoososUserRoleTypeBundle/fields.html.twig #}
     <div class="custom-role-field">
         {% for role in roles %}
             <label>
                 <input type="checkbox" name="roles[]" value="{{ role }}">
                 {{ role }}
             </label>
         {% endfor %}
     </div>
     

5. Event Listeners:

   • Hook into role assignment logic via Symfony events (e.g., PRE_SET_DATA):

     $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
         $user = $event->getData();
         if ($user && $user->hasRole('ROLE_ADMIN')) {
             $event->getForm()->add('roles', UserRoleType::class, ['disabled' => true]);
         }
     });
     

Gotchas and Tips

Pitfalls

1. Strict vs. Loose Mode:

   • 'strict' enforces hierarchical roles (e.g., ROLE_ADMIN implies ROLE_USER). Use 'loose' for flat role sets.
   • Debugging Tip: Log the final role array post-submission to verify hierarchy:

     $form->handleRequest($request);
     if ($form->isSubmitted() && $form->isValid()) {
         dump($form->getData()->getRoles());
     }
     

2. Role Hierarchy Conflicts:

   • If roles are misconfigured in security.yaml, the bundle may render unexpected options. Validate with:

     php bin/console debug:security
     

3. Template Caching:

   • Overridden Twig templates must be cleared after changes:

     php bin/console cache:clear
     

4. Deprecated Symfony Features:

   • The bundle lacks Symfony 6+ support. For newer projects, consider alternatives like Stof\DoctrineExtensionsBundle or custom form types.

Tips

1. Performance:

   • Cache role data if fetched frequently:

     $builder->add('roles', UserRoleType::class, [
         'role_manager' => $cachedRoleManager, // Service with cached roles
     ]);
     

2. Localization:

   • Translate role labels in Twig:

     {{ role|trans({'domain': 'messages'}, 'roles.' ~ role) }}
     

3. Testing:

   • Mock the RoleManager in PHPUnit:

     $roleManager = $this->createMock(RoleManagerInterface::class);
     $roleManager->method('getRoles')->willReturn(['ROLE_USER', 'ROLE_ADMIN']);
     $form = $this->factory->create(UserType::class, null, [
         'role_manager' => $roleManager,
     ]);
     

4. Extension Points:

   • Extend the form type for custom logic:

     class CustomUserRoleType extends AbstractType {
         public function configureOptions(OptionsResolver $resolver) {
             $resolver->setDefaults([
                 'custom_option' => false,
             ]);
         }
     }
     

     Then use:

     $builder->add('roles', CustomUserRoleType::class);
     

5. Debugging:

   • Enable form type debugging in config/packages/dev/debug.yaml:

     framework:
         form: { enabled_types: [Coosos\UserRoleTypeBundle\Form\Type\UserRoleType] }