Fos User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bkstg/fos-user-bundle
   

   Ensure friendsofsymfony/user-bundle and midnightluke/group-security-bundle are also installed (required dependencies).

2. Configuration: Add the bundle to config/bundles.php:

   return [
       // ...
       Backstage\FosUserBundle\BackstageFosUserBundle::class => ['all' => true],
   ];
   

3. Database Migrations: Run migrations to create the fos_user and fos_user_group tables:

   php artisan migrate
   

4. First Use Case: Register a new user via the built-in registration form (if enabled) or programmatically:

   use Backstage\FosUserBundle\Model\UserManager;
   use Symfony\Component\HttpFoundation\Request;
   
   $userManager = $this->get('fos_user.user_manager');
   $user = $userManager->createUser();
   $user->setUsername('testuser');
   $user->setPlainPassword('password');
   $user->setEmail('test@example.com');
   $userManager->updateUser($user);
   

Implementation Patterns

Core Workflows

1. User Management:

   • Create/Update Users: Use UserManager to handle user lifecycle:

     $userManager = $this->container->get('fos_user.user_manager');
     $user = $userManager->createUser();
     $user->setEnabled(true); // Enable/disable users
     $userManager->updateUser($user);
     

   • Password Resets: Leverage FOSUserBundle’s built-in reset system:

     $tokenGenerator = $this->container->get('fos_user.util.token_generator');
     $token = $tokenGenerator->generateToken();
     

2. Group Integration:

   • Assign users to groups (via GroupSecurityBundle):

     $groupManager = $this->container->get('midnightluke_group_security.group_manager');
     $group = $groupManager->findGroupBy(['name' => 'admin']);
     $user->addGroup($group);
     $userManager->updateUser($user);
     

3. Authentication:

   • Use Symfony’s security component with FOSUserBundle’s providers:

     # config/packages/security.yaml
     security:
         providers:
             fos_userbundle:
                 id: fos_user.user_provider.username_email
     

4. Custom User Fields: Extend the User entity (e.g., App\Entity\User) and update the UserManager:

   // src/Entity/User.php
   class User extends BaseUser
   {
       /**
        * @ORM\Column(type="string", length=255, nullable=true)
        */
       private $customField;
   }
   

5. Event Listeners: Subscribe to FOSUserBundle events (e.g., UserRegisteredEvent):

   // src/EventListener/UserListener.php
   class UserListener
   {
       public function onUserRegistered(UserRegisteredEvent $event)
       {
           $user = $event->getUser();
           // Custom logic (e.g., send welcome email)
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\UserListener:
           tags:
               - { name: kernel.event_listener, event: fos_user.user_registered, method: onUserRegistered }
   

Gotchas and Tips

Pitfalls

1. Missing Dependencies:

   • Forgetting to install friendsofsymfony/user-bundle or midnightluke/group-security-bundle will break the bundle. Verify composer.json includes:

     "require": {
         "friendsofsymfony/user-bundle": "^2.0",
         "midnightluke/group-security-bundle": "^1.0"
     }
     

2. Configuration Overrides:

   • The bundle relies on FOSUserBundle’s default configurations. Override them in config/packages/fos_user.yaml carefully:

     fos_user:
         db_driver: orm
         firewall_name: main
         user_class: App\Entity\User
     

3. Group Permissions:

   • GroupSecurityBundle requires explicit permission definitions. Define roles in security.yaml:

     security:
         role_hierarchy:
             ROLE_ADMIN: [ROLE_USER, ROLE_GROUP_ADMIN]
     

4. Token Expiry:

   • Password reset tokens expire by default. Customize in fos_user.yaml:

     fos_user:
         resetting:
             token_ttl: 86400 # 1 day in seconds
     

Debugging Tips

1. User Not Found:

   • Ensure user_class in fos_user.yaml matches your extended User entity.
   • Check database tables (fos_user, fos_user_group) for records.

2. Authentication Failures:

   • Verify the firewall_name in fos_user.yaml matches your security firewall.
   • Test with php bin/console debug:security to validate providers.

3. Event Listeners Not Triggering:

   • Confirm the event name matches exactly (e.g., fos_user.user_registered vs. fos_user.registered).
   • Use bin/console debug:event-dispatcher to list available events.

Extension Points

1. Custom User Provider: Extend the default provider for custom logic:

   // src/Security/UserProvider.php
   class CustomUserProvider implements UserProviderInterface
   {
       public function loadUserByUsername($username)
       {
           // Custom logic
       }
   }
   

   Register in security.yaml:

   security:
       providers:
           custom_provider:
               id: App\Security\UserProvider
   

2. Form Types: Override FOSUserBundle’s form types (e.g., RegistrationFormType) in config/packages/fos_user.yaml:

   fos_user:
       registration:
           form:
               type: App\Form\RegistrationFormType
   

3. Templates: Override default templates (e.g., registration.html.twig) in templates/FOSUserBundle/.