User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require beelab/user-bundle
   

   Add to config/bundles.php:

   BeeLab\UserBundle\BeeLabUserBundle::class => ['all' => true],
   

2. Database Migration: Run the bundle’s schema update (check Resources/doc/index.md for exact command) or manually create the user table:

   CREATE TABLE user (
       id INT AUTO_INCREMENT PRIMARY KEY,
       email VARCHAR(255) NOT NULL UNIQUE,
       password VARCHAR(255) NOT NULL,
       is_active BOOLEAN DEFAULT true,
       created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
       updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
   );
   

3. First Use Case:

   • Login: Use Symfony’s built-in security.yaml with BeeLab\UserBundle\Security\UserProvider as the user provider.
   • User Creation: Inject BeeLab\UserBundle\Entity\UserManager to create users:

     $user = $userManager->createUser('user@example.com', 'plainPassword');
     $userManager->saveUser($user);
     

Implementation Patterns

Core Workflows

1. Authentication:

   • Configure security.yaml to use the bundle’s user_provider:

     security:
         providers:
             app_user_provider:
                 id: BeeLab\UserBundle\Security\UserProvider
     

   • Extend BeeLab\UserBundle\Entity\User for custom fields if needed.

2. User Management:

   • CRUD: Use UserManager for all operations:

     // Find user
     $user = $userManager->findUserByEmail('user@example.com');
     
     // Update user
     $user->setActive(false);
     $userManager->saveUser($user);
     

   • Impersonation: Use the ImpersonateListener (if enabled) to switch users temporarily:

     $this->get('security.token_storage')->setToken(
         new UsernamePasswordToken($user, null, 'main', $user->getRoles())
     );
     

3. Password Changes:

   • Use UserManager::changePassword($user, 'newPassword') with Symfony’s PasswordHasher (injected automatically).

4. Event Listeners:

   • Subscribe to UserEvents (e.g., UserCreatedEvent) for post-save logic:

     $dispatcher->addListener(UserEvents::USER_CREATED, function (UserCreatedEvent $event) {
         // Send welcome email
     });
     

Integration Tips

• Custom Fields: Extend the User entity and override UserManager methods to handle new fields.
• Validation: Use Symfony’s Validator with constraints on the User entity (e.g., @Assert\Email).
• APIs: Serialize the User entity with ApiPlatform or JMSSerializer (exclude sensitive fields like password).

Gotchas and Tips

Pitfalls

1. No Registration Flow:

   • The bundle lacks built-in registration. Use UserManager::createUser() manually or integrate with BeeLabUserPasswordBundle for email validation.

2. Password Hashing:

   • Ensure your security.yaml hashes passwords with algorithm: auto:

     security:
         encoders:
             BeeLab\UserBundle\Entity\User:
                 algorithm: auto
     

3. Doctrine Only:

   • The bundle does not support Propel or ODM. Stick to Doctrine ORM.

4. Impersonation Quirks:

   • Impersonation requires STORAGE_TOKEN in security.yaml:

     security:
         firewalls:
             main:
                 anonymous: ~
                 form_login: ~
                 switch_user: { role: ROLE_ADMIN } # Enables impersonation
     

Debugging

• User Not Found: Verify the UserProvider is correctly configured in security.yaml and the user table exists.
• Password Mismatch: Check if the PasswordHasher is properly injected (Symfony 5+ auto-configures this).
• Events Not Triggered: Ensure the EventDispatcher is bound to the UserManager (check services.yaml for overrides).

Extension Points

1. Custom User Provider:

   • Extend BeeLab\UserBundle\Security\UserProvider to add logic (e.g., multi-table queries).

2. Override User Entity:

   • Create a custom User class extending BeeLab\UserBundle\Entity\User and update services.yaml:

     services:
         App\Entity\User:
             parent: BeeLab\UserBundle\Entity\User
             tags: ['beelab.user.user_class']
     

3. Add Fields:

   • Extend the User entity and update the UserManager to handle new fields in saveUser()/createUser().

4. Custom Roles:

   • Add a roles field to the User entity and update the UserProvider to load roles from the database.

Configuration Quirks

• Email Uniqueness: The bundle enforces uniqueness via Doctrine constraints. Override the User entity to customize validation.
• Active Flag: The is_active field controls login access. Set to false to disable users programmatically.