Actual User Bundle Laravel Package

Getting Started

Minimal Steps

1. Install the Bundle

   composer require 11ya/actual-user-bundle:dev-master
   

   Add to bundles.php (Symfony 4.4+):

   return [
       // ...
       Ilya\ActualUserBundle\IlyaActualUserBundle::class => ['all' => true],
   ];
   

2. Implement ActualUserInterface Extend your User entity (e.g., src/Security/User.php):

   use Ilya\ActualUserBundle\Model\ActualUserInterface;
   
   class User implements ActualUserInterface
   {
       // Your existing User logic
       public function getActualRoles(): array
       {
           return $this->roles; // Return fresh roles (e.g., from DB)
       }
   }
   

3. Update Security Configuration In config/packages/security.yaml:

   providers:
       app_user_provider:
           entity:
               class: App\Entity\User
               property: email
               role_property: actual_roles  # <-- Key change
   

4. First Use Case After updating a user’s roles (e.g., via admin panel), call:

   $user->setRoles(['ROLE_ADMIN', 'ROLE_USER']);
   $entityManager->flush();
   

   The bundle ensures the user’s session roles are refreshed without re-authentication.

Implementation Patterns

Workflows

1. Role Updates via API/Forms

   • Trigger role changes in a controller/service:

     $user->setRoles($newRoles);
     $em->flush();
     $this->get('security.token_storage')->getToken()->setUser($user);
     

   • The bundle’s ActualUserProvider intercepts and refreshes roles.

2. Event-Driven Updates Listen for UserUpdatedEvent (if extended) or use Symfony’s KernelEvents::TERMINATE:

   $eventDispatcher->addListener(KernelEvents::TERMINATE, function (TerminateEvent $event) {
       $user = $this->get('security.token_storage')->getToken()->getUser();
       if ($user instanceof ActualUserInterface) {
           $user->getActualRoles(); // Force refresh
       }
   });
   

3. Integration with Voters Ensure voters use getActualRoles() instead of getRoles():

   $roles = $user instanceof ActualUserInterface ? $user->getActualRoles() : $user->getRoles();
   

Tips

• Symfony 5+: Use security.yaml auto-configuration:

  security:
      providers:
          app_user_provider:
              entity:
                  class: App\Entity\User
                  property: email
                  role_property: actual_roles
  

• Doctrine Lifecycle: Override preUpdate() in your User entity to auto-refresh roles:

  public function preUpdate()
  {
      $this->getActualRoles(); // Force refresh
  }
  

Gotchas and Tips

Pitfalls

1. Session Locks

   • If roles change mid-request, the session may cache stale roles. Use:

     $token = $this->get('security.token_storage')->getToken();
     $token->setUser($user); // Force session update
     

2. Circular Dependencies

   • Avoid calling getActualRoles() in getRoles() (Symfony’s security layer may call both).

3. Provider Misconfiguration

   • Ensure role_property: actual_roles matches your ActualUserInterface method name.

4. Symfony 4.3+ Cache

   • Clear the security cache after updates:

     php bin/console cache:clear
     

Debugging

• Check Provider Logs Enable debug in security.yaml:

  debug: true
  

  Look for ActualUserProvider logs during role updates.

• Verify Token Refresh Dump the token after role changes:

  dump($this->get('security.token_storage')->getToken()->getUser()->getRoles());
  

Extension Points

1. Custom Role Refresh Logic Extend ActualUserProvider:

   class CustomActualUserProvider extends ActualUserProvider
   {
       protected function refreshRoles(UserInterface $user)
       {
           // Custom logic (e.g., API call)
           $user->setRoles($this->fetchFreshRoles());
       }
   }
   

   Register as a service in services.yaml:

   services:
       App\Security\CustomActualUserProvider:
           tags: [security.user_provider]
   

2. Event-Based Refresh Dispatch a custom event after role updates:

   $dispatcher->dispatch(new RolesRefreshedEvent($user));
   

   Listen in a subscriber to trigger refreshes.

3. Multi-Tenant Roles Override getActualRoles() to scope roles by tenant:

   public function getActualRoles(): array
   {
       return $this->tenant->getRolesForUser($this);
   }