User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require bannister/user-bundle
   

   Publish the bundle’s assets and configuration:

   php bin/console bannister:install
   

2. First Use Case: User Registration

   • Extend the provided User entity (located in src/Entity/User.php by default) to add custom fields.
   • Configure routes in config/routes.yaml (or via annotations):

     bannister_user:
         resource: "@BannisterUserBundle/Resources/config/routing.yaml"
     

   • Test registration by visiting /register (or your custom route).

3. Key Configuration Review config/packages/bannister_user.yaml for:

   • Activation email settings (e.g., activation.enabled).
   • Password reset policies (e.g., reset.token_ttl).
   • Default roles (e.g., default_role).

Implementation Patterns

Workflows

1. Custom User Fields

   • Extend the User entity (e.g., src/Entity/CustomUser extends User).
   • Add fields (e.g., phoneNumber, preferences) and update the database schema:

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

   • Override the registration form (RegistrationType) to include new fields.

2. Authentication Logic

   • Customize login logic by overriding the AuthenticationSuccessHandler or AuthenticationFailureHandler services.
   • Example: Redirect users based on roles:

     # config/packages/security.yaml
     firewalls:
         main:
             form_login:
                 default_target_path: bannister_user_dashboard
                 always_use_default_target_path: false
     

3. Email Templates

   • Override default email templates (e.g., activation, reset) in:

     templates/bannister_user/email/
     

   • Use Twig variables like {{ user.email }} or {{ resetToken }}.

4. API Integration

   • Use the bundle’s API endpoints (e.g., /api/register, /api/reset-password) with JSON payloads.
   • Example registration payload:

     {
         "email": "user@example.com",
         "password": "securePassword123",
         "customField": "value"
     }
     

5. Event Listeners

   • Subscribe to events (e.g., UserRegisteredEvent, PasswordResetEvent) in services.yaml:

     services:
         App\EventListener\CustomUserListener:
             tags:
                 - { name: kernel.event_listener, event: bannister.user.registered, method: onUserRegistered }
     

Gotchas and Tips

Pitfalls

1. Database Schema Mismatches

   • If extending the User entity, always run migrations after adding fields to avoid ColumnNotFoundException.
   • Verify the User class’s @ORM\Entity and @ORM\Table annotations match your database.

2. Email Configuration

   • Ensure mailer_transport is set in .env (e.g., MAILER_DSN=smtp://user:pass@smtp.example.com).
   • Test emails locally with a service like Mailtrap to avoid production issues.

3. Password Hashing

   • The bundle uses Symfony’s UserPasswordHasherInterface. If customizing, ensure the hasher is properly configured in security.yaml:

     security:
         password_hashers:
             App\Entity\User: 'auto'
     

4. Route Conflicts

   • The bundle’s routes (e.g., /login, /register) may conflict with existing routes. Use _prefix in routing.yaml:

     bannister_user:
         resource: "@BannisterUserBundle/Resources/config/routing.yaml"
         prefix: "/auth"
     

5. Activation Tokens

   • Activation tokens expire after activation.token_ttl (default: 24 hours). Clear old tokens periodically:

     php bin/console bannister:user:cleanup-tokens
     

Debugging Tips

1. Enable Debug Mode Set APP_ENV=dev in .env to see detailed error messages and Twig debug output.

2. Log Events Enable event logging in config/packages/monolog.yaml:

   handlers:
       main:
           type: stream
           level: debug
           channels: ["!event"]
       event:
           type: stream
           level: debug
           channels: ["event"]
   

3. Check the User Provider If authentication fails, verify the user_provider in security.yaml points to your extended User entity:

   providers:
       app_user_provider:
           entity:
               class: App\Entity\CustomUser
               property: email
   

Extension Points

1. Custom Validation Override the RegistrationType form class to add validation rules:

   // src/Form/RegistrationType.php
   public function buildForm(FormBuilderInterface $builder, array $options)
   {
       $builder->add('phoneNumber', TextType::class, [
           'constraints' => [new NotBlank(), new Length(['min' => 10])]
       ]);
   }
   

2. Custom Roles Add roles dynamically in the User entity’s getRoles() method:

   public function getRoles(): array
   {
       $roles = ['ROLE_USER'];
       if ($this->isAdmin()) {
           $roles[] = 'ROLE_ADMIN';
       }
       return array_unique($roles);
   }
   

3. API Authentication Extend the TokenAuthenticator for custom API token logic:

   // src/Security/TokenAuthenticator.php
   public function supports(Request $request)
   {
       return $request->headers->has('X-AUTH-TOKEN');
   }