User Role Type Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require aldaflux/user-role-type-bundle:dev-master
   

   Ensure your project meets the requirements (PHP 7.1+, Symfony 4.0/5.0).

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

   return [
       // ...
       Aldaflux\UserRoleTypeBundle\AldafluxUserRoleTypeBundle::class => ['all' => true],
   ];
   

3. First Use Case: Add the form type to a Symfony form builder:

   use Aldaflux\UserRoleTypeBundle\Form\Type\UserRoleType;
   
   $builder->add('roles', UserRoleType::class);
   

   This renders a role selection dropdown with default configuration (display: standard, security_checked: true).

Implementation Patterns

Common Workflows

1. Basic Role Assignment: Use the default configuration for standard user role assignment:

   $builder->add('roles', UserRoleType::class, [
       'config' => 'default' // Uses config from `aldaflux_user_role_type.yaml`
   ]);
   

2. Custom Role Profiles: Define and use a custom profile (e.g., for admin-only roles):

   # config/packages/aldaflux_user_role_type.yaml
   aldaflux_user_role_type:
       profiles:
           admin_profile: [ROLE_ADMIN, ROLE_SUPER_ADMIN]
   

   $builder->add('roles', UserRoleType::class, [
       'config' => 'default',
       'profile' => 'admin_profile'
   ]);
   

3. Dynamic Role Filtering: Use display: minimum to show only roles shared by the current and edited user:

   $builder->add('roles', UserRoleType::class, [
       'config' => 'myconfigspecific' // From YAML: display: minimum
   ]);
   

4. Localized Labels: Configure translations for role labels:

   # config/packages/messages+intl-icu.en.yaml
   user:
       roles:
           role_user: "Standard User"
           role_admin: "Site Administrator"
   

   $builder->add('roles', UserRoleType::class, [
       'label' => [
           'display' => 'traduction',
           'translation_prefixe' => 'user.roles.'
       ]
   ]);
   

5. Bypassing Security Checks: Disable role validation (use cautiously):

   $builder->add('roles', UserRoleType::class, [
       'config' => 'myconfigsuper', // From YAML: security_checked: false
   ]);
   

Gotchas and Tips

Pitfalls

1. Profile vs. Config Confusion:

   • config loads settings from aldaflux_user_role_type.yaml.
   • profile overrides the role hierarchy but does not load config settings.
   • Example: profile: 'admin_profile' alone won’t apply display: minimum unless specified in the config.

2. Security Check Bypass: Setting security_checked: false allows users to assign roles they don’t possess. Avoid in production unless explicitly required (e.g., for super-admins).

3. Translation Overrides:

   • If display: traduction is set but translations are missing, roles will render as raw strings (e.g., ROLE_USER).
   • Ensure the translation domain (user.roles.) matches your YAML keys.

4. Hierarchy Dependencies:

   • The bundle assumes Symfony’s security role hierarchy (e.g., ROLE_ADMIN inherits from ROLE_USER).
   • Custom hierarchies may break role filtering (e.g., display: minimum).

5. Form Theme Conflicts:

   • The bundle doesn’t provide default Twig templates. If roles don’t render, check for missing templates or override the form theme:

     {# templates/AldafluxUserRoleTypeBundle/Form/fields.html.twig #}
     

Debugging Tips

1. Inspect Available Roles: Dump the role hierarchy to verify profiles/configs:

   use Symfony\Component\Security\Core\Role\RoleHierarchyInterface;
   $roleHierarchy = $this->container->get(RoleHierarchyInterface::class);
   dump($roleHierarchy->getReachableRoleNames(['ROLE_USER']));
   

2. Check Configuration: Validate YAML syntax and keys:

   symfony console debug:config aldaflux_user_role_type
   

3. Override Defaults: Extend the form type to add custom logic:

   use Aldaflux\UserRoleTypeBundle\Form\Type\UserRoleType as BaseUserRoleType;
   
   class CustomUserRoleType extends BaseUserRoleType {
       public function configureOptions(OptionsResolver $resolver) {
           $resolver->setDefaults([
               'security_checked' => false, // Override default
           ]);
       }
   }
   

4. Strict Mode: Enable security: strict in Symfony’s security config to enforce role validation:

   security:
       role_hierarchy:
           ROLE_ADMIN: ROLE_USER
       # ...
   

Extension Points

1. Custom Role Providers: Extend the bundle to fetch roles from a database or API:

   // src/Form/Type/CustomUserRoleType.php
   public function getParent() { return UserRoleType::class; }
   
   public function getRoles() {
       // Fetch roles from your service
       return $this->roleService->getAllRoles();
   }
   

2. Dynamic Profiles: Generate profiles programmatically:

   $builder->add('roles', UserRoleType::class, [
       'profile' => function (FormInterface $form) {
           return ['ROLE_' . $form->getData()->getType()];
       }
   ]);
   

3. Event Listeners: Modify role data before submission:

   // src/EventListener/RoleSubscriber.php
   public function onPreSubmit(FormEvent $event) {
       $data = $event->getData();
       $data['roles'] = array_map('strtoupper', $data['roles']);
       $event->setData($data);
   }
   

   Register in services.yaml:

   services:
       App\EventListener\RoleSubscriber:
           tags:
               - { name: kernel.event_subscriber }