User Bundle Laravel Package

Getting Started

Minimal Setup for Laravel (Symfony Ecosystem)

Since this is a Symfony bundle, Laravel developers must use Symfony’s bridge packages (symfony/flex, symfony/console, etc.) or integrate it via Laravel’s Symfony integration (e.g., spatie/symfony-laravel). Start here:

1. Install via Composer (in a Laravel project with Symfony components):

   composer require friendsofsymfony/user-bundle
   

   Note: Requires symfony/security-bundle and doctrine/orm (or ODM).

2. Enable the Bundle (in config/bundles.php for Symfony/Laravel hybrid projects):

   return [
       // ...
       FriendsOfSymfony\UserBundle\FOSUserBundle::class => ['all' => true],
   ];
   

3. Configure Database & User Model (adapt to Laravel’s config/auth.php):

   # config/packages/fos_user.yaml
   fos_user:
       db_driver: orm       # or 'mongodb', 'couchdb'
       firewall_name: main
       user_class: App\Entity\User  # Extend FOSUserBundle’s base User class
   

4. Create a User Entity (extend BaseUser):

   // src/Entity/User.php
   namespace App\Entity;
   
   use FOS\UserBundle\Model\User as BaseUser;
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   class User extends BaseUser { /* ... */ }
   

5. Run Migrations:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

6. First Use Case: Registration Flow

   • Use FOS’s built-in controllers (RegistrationController) or override them.
   • Example route (Symfony-style, adapt to Laravel’s routing):

     fos_user_registration_register: /register
     fos_user_registration_check_email: /check-email
     

Implementation Patterns

1. Authentication Integration

FOSUserBundle provides a UserProvider for Symfony’s SecurityBundle. In Laravel:

• Use spatie/laravel-permission or Symfony’s UserChecker for role checks.
• Example: Extend Laravel’s AuthenticatesUsers trait to use FOS’s UserManager:

  use FOS\UserBundle\Model\UserManagerInterface;
  
  class LoginController extends Controller {
      public function __construct(private UserManagerInterface $userManager) {}
  
      public function login(Request $request) {
          $user = $this->userManager->findUserBy(['email' => $request->email]);
          // Custom auth logic...
      }
  }
  

2. Custom User Fields

Extend the User entity and update FOS’s form types:

// src/Entity/User.php
#[ORM\Column(type: 'string', length: 255)]
private $phoneNumber;

// src/Form/Type/RegistrationFormType.php
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\TextType;

class RegistrationFormType extends AbstractType {
    public function buildForm(FormBuilderInterface $builder, array $options) {
        $builder->add('phoneNumber', TextType::class);
    }
}

3. Password Reset Workflow

Leverage FOS’s built-in reset logic:

• Trigger Reset: Call UserManager::resetPassword().
• Customize Email: Override FOSUserEvents::RESET_PASSWORD_SUCCESS event listener.
• Laravel Adaptation:

  use FOS\UserBundle\Event\FilterUserResponseEvent;
  use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  
  class CustomResetSubscriber implements EventSubscriberInterface {
      public static function getSubscribedEvents() {
          return [
              FOSUserEvents::RESET_PASSWORD_SUCCESS => 'onResetSuccess',
          ];
      }
  
      public function onResetSuccess(FilterUserResponseEvent $event) {
          // Send Laravel Notifications or custom logic
      }
  }
  

4. API Integration

For Laravel APIs:

• Use FOS’s UserManager to validate tokens (e.g., JWT).
• Example: Authenticate via API token:

  $user = $this->userManager->findUserBy(['api_token' => $request->bearerToken()]);
  

5. Testing

• Use Symfony’s WebTestCase or Laravel’s HttpTests with FOS’s fixtures:

  public function testRegistration() {
      $client = static::createClient();
      $crawler = $client->request('GET', '/register');
      // Assert form fields...
  }
  

Gotchas and Tips

Pitfalls

1. Laravel-Symfony Mismatch:

   • FOSUserBundle expects Symfony’s EventDispatcher and Container. Use Laravel’s service container bridges:

     $this->container->get('fos_user.user_manager');
     

   • Fix: Bind Symfony services to Laravel’s container in AppServiceProvider:

     $this->app->bind('fos_user.user_manager', function ($app) {
         return $app->make('fos_user.user_manager.default');
     });
     

2. Doctrine vs. Eloquent:

   • FOSUserBundle is ORM-agnostic but defaults to Doctrine. For Eloquent:
     • Use illuminate/database + spatie/laravel-doctrine-orm (hybrid approach).
     • Tip: Override UserManager to use Eloquent’s Model instead of Doctrine’s EntityManager.

3. Event Dispatching:

   • Laravel’s Events and Symfony’s EventDispatcher are separate. Subscribe to FOS events via:

     $dispatcher = $this->container->get('event_dispatcher');
     $dispatcher->addListener(FOSUserEvents::REGISTRATION_SUCCESS, function ($event) {
         // Laravel logic (e.g., send welcome email)
     });
     

4. Password Hashing:

   • FOS uses Symfony’s PasswordHasherInterface. For Laravel’s Hash facade:

     use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;
     $hasher = $this->container->get('security.password_hasher');
     $hashed = $hasher->hashPassword($user, $plainPassword);
     

5. CSRF Protection:

   • FOS relies on Symfony’s csrf_token. In Laravel, use:

     {{ csrf_token() }}  // Laravel’s built-in CSRF
     

   • Or disable CSRF in FOS config if using Laravel’s middleware.

Debugging Tips

1. Enable FOS Debugging:

   fos_user:
       debug: true  # Logs events to Symfony’s profiler
   

2. Common Errors:

   • "User class not found": Ensure user_class in fos_user.yaml matches your App\Entity\User.
   • "No route found": FOS routes are Symfony-style (/register). Use Laravel’s route aliases:

     Route::get('/register', [RegistrationController::class, 'register'])->name('fos_user_registration_register');
     

3. Event Debugging:

   • Dump events in a subscriber:

     public function onRegistration(FormEvent $event) {
         dump($event->getForm()->getData());
     }
     

Extension Points

1. Custom User Interface:

   • Override FOS templates (Symfony-style) in templates/FOSUserBundle/.
   • For Laravel Blade: Use SymfonyBridge to render Symfony templates:

     use Symfony\Bridge\Twig\Extension\RoutingExtension;
     $router = $this->container->get('router');
     

2. Multi-Tenant Users:

   • Extend User entity with tenant_id and filter queries in UserManager:

     public function findUserBy(array $criteria) {
         $criteria['tenant_id'] = auth()->id();
         return parent::findUserBy($criteria);
     }
     

3. Social Logins:

   • Use FOS’s UserProvider with Laravel Socialite:

     $user = $this->userManager->createUser([
         'username' => $socialUser->getId(),
         'email' => $socialUser->getEmail(),
     ]);
     

4. Performance:

   • Cache UserManager in Laravel’s cache:

     $userManager = Cache::remember('fos_user_manager', 3600, function () {
         return $this->container->get('fos_user.user_manager');
     });