Basic User Bundle Laravel Package

Getting Started

Minimal Setup for Authentication

1. Installation

   composer require code-colliders/basic-user-bundle
   

   Enable the bundle in config/bundles.php:

   CodeColliders\BasicUserBundle\CodeCollidersBasicUserBundle::class => ['all' => true],
   

2. Initialize the Bundle Run the command to generate configurations and a User entity:

   php bin/console basic-user:init -c User
   

   This creates:

   • A User entity with required fields (email, password, roles).
   • Basic security configurations (e.g., security.yaml, firewalls).

3. First Use Case: User Registration

   • Extend the generated User entity (e.g., add custom fields via make:entity).
   • Use the bundle’s UserRepository to interact with users:

     $user = $this->getDoctrine()->getRepository(User::class)->findOneBy(['email' => 'test@example.com']);
     

   • Secure routes with annotations (e.g., @IsGranted("ROLE_USER")).

Implementation Patterns

Workflows

1. Authentication Flow

   • Login: Use Symfony’s built-in security.yaml (configured by the bundle) with form login:

     firewalls:
         main:
             form_login:
                 login_path: login
                 check_path: login
     

   • Logout: Redirect to a custom route post-logout:

     logout:
         path: app_logout
         target: home
     

2. User Management

   • Create Users: Use the User entity’s setter methods:

     $user = new User();
     $user->setEmail('user@example.com')
          ->setPassword($passwordEncoder->encodePassword($user, 'rawPassword'))
          ->setRoles(['ROLE_USER']);
     $entityManager->persist($user);
     

   • Fetch Users: Query with Doctrine:

     $users = $userRepository->findBy(['role' => 'ROLE_ADMIN']);
     

3. Role-Based Access

   • Assign roles dynamically:

     $user->addRole('ROLE_EDITOR');
     $entityManager->flush();
     

   • Protect routes with annotations or voters:

     #[IsGranted('ROLE_ADMIN')]
     public function adminDashboard(): Response
     

Integration Tips

• Custom User Fields: Extend the User entity after initialization:

  php bin/console make:entity User
  

  Add fields like fullName or avatar, then update migrations.

• Password Reset: Integrate with Symfony’s PasswordResetToken or use a third-party bundle (e.g., symfonycasts/verify-email).

• API Authentication: Use api firewall with JWT or stateless token authentication:

  firewalls:
      api:
          pattern: ^/api
          stateless: true
          jwt: ~
  

Gotchas and Tips

Pitfalls

1. Outdated Bundle

   • Last release: 2020-05-11. Verify compatibility with your Symfony version (tested up to Symfony 4.4).
   • Mitigation: Fork the repo or use a modern alternative (e.g., symfony/security-bundle + custom User entity).

2. Missing Doctrine Migrations

   • The basic-user:init command creates the User entity but does not generate migrations.
   • Fix: Run:

     php bin/console make:migration
     php bin/console doctrine:migrations:migrate
     

3. Hardcoded Configurations

   • The bundle may override security.yaml or config/packages/security.yaml without warning.
   • Tip: Backup your config before running basic-user:init.

4. No Built-in Password Reset

   • The bundle lacks email verification or password reset features.
   • Workaround: Use symfonycasts/verify-email or implement manually with PasswordResetToken.

Debugging

• User Not Found Errors:

  • Ensure the User entity implements UserInterface and EquatableInterface from Symfony\Component\Security\Core\User.
  • Check the loadUserByUsername() method in your custom UserProvider (if overridden).

• Role Assignment Issues:

  • Roles must be arrays (e.g., ['ROLE_USER']), not strings.
  • Verify the ROLES property in the User entity is typed as array.

Extension Points

1. Custom User Provider Override the default provider in security.yaml:

   providers:
       app_users:
           entity:
               class: App\Entity\User
               property: email
   

2. Event Listeners Subscribe to security events (e.g., AuthenticationSuccess):

   // src/EventListener/LoginListener.php
   public function onAuthenticationSuccess(AuthenticationSuccessEvent $event)
   {
       $user = $event->getUser();
       // Custom logic (e.g., log activity)
   }
   

   Register in services.yaml:

   services:
       App\EventListener\LoginListener:
           tags:
               - { name: 'kernel.event_listener', event: 'security.authentication.success' }
   

3. API Tokens For API auth, pair with lexik/jwt-authentication-bundle:

   composer require lexik/jwt-authentication-bundle
   

   Configure in config/packages/security.yaml:

   firewalls:
       api:
           pattern: ^/api
           stateless: true
           jwt: ~