User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Since this is a fork of FOSUserBundle tailored for Kimai 2, it is not meant for standalone use. However, if you're working with Kimai 2 or need a lightweight FOSUser alternative, add it via Composer:

   composer require comunedifirenze/user-bundle
   

   (Note: Verify compatibility with your Symfony version—this bundle drops FOSUserBundle deprecations.)

2. Configuration Publish the default config (if needed):

   php bin/console fos:user:setup
   

   (Check config/packages/security.yaml and config/packages/user.yaml for required adjustments.)

3. First Use Case

   • User Registration: Extend the default registration flow by overriding templates in templates/FOSUserBundle/Registration/.
   • Password Reset: Use the built-in ForgotPassword controller (if not removed in future versions).

Implementation Patterns

Common Workflows

1. Custom User Model Extend the default User entity (likely App\Entity\User) by adding fields:

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

   Update the bundle’s UserProvider to recognize your model.

2. Authentication & Security

   • Use Symfony’s security system with the bundle’s fos_user firewall:

     # config/packages/security.yaml
     firewalls:
         main:
             form_login:
                 provider: fos_userbundle
     

   • Customize login/logout paths in security.yaml.

3. Event Listeners Hook into user lifecycle events (e.g., UserRegistered, PasswordReset):

   // src/EventListener/UserListener.php
   use ComuneDI\Bundle\UserBundle\Event\UserEvent;
   
   class UserListener
   {
       public function onUserRegistered(UserEvent $event)
       {
           $user = $event->getUser();
           // Custom logic (e.g., send welcome email via Symfony Mailer).
       }
   }
   

   Register in services.yaml:

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

4. API Integration For API-based auth (e.g., JWT), pair with lexik/jwt-authentication-bundle:

   # config/packages/security.yaml
   firewalls:
       api:
           pattern: ^/api
           stateless: true
           jwt: ~
   

Integration Tips

• Templates: Override FOSUser templates in templates/FOSUserBundle/ (e.g., registration.html.twig).
• Validation: Extend user validation via constraints:

  use Symfony\Component\Validator\Constraints as Assert;
  
  class User extends BaseUser
  {
      /**
       * @Assert\NotBlank
       */
      private $customField;
  }
  

• Migrations: Use Doctrine Migrations to add new fields:

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

Gotchas and Tips

Pitfalls

1. No Standalone Support

   • This bundle is Kimai 2-specific. Avoid using it outside Kimai unless you’re comfortable with potential BC breaks.
   • Future versions may remove unused controllers/mailers (check CHANGELOG).

2. Deprecated FOSUserBundle Features

   • Some FOSUserBundle features (e.g., UserManager) may be renamed or removed. Refer to the CHANGELOG for changes.

3. Mailer Dependency

   • The bundle plans to remove the mailer in future versions. If you rely on emails (e.g., password resets), migrate to Symfony Mailer now:

     use Symfony\Component\Mailer\MailerInterface;
     
     class UserListener
     {
         public function __construct(private MailerInterface $mailer) {}
     
         public function onPasswordReset(UserEvent $event)
         {
             $this->mailer->send(...);
         }
     }
     

4. Route Conflicts

   • Default routes (e.g., /register, /resetting) may clash with other bundles. Override them in config/routes.yaml:

     fos_user:
         resource: "@FOSUserBundle/Resources/config/routing/all.xml"
         prefix: /auth
     

Debugging Tips

• Enable Debug Mode: Add this to config/packages/dev/security.yaml to debug auth issues:

  security:
      debug: true
  

• Check Events: Use Symfony’s event dispatcher to log events:

  public function onUserRegistered(UserEvent $event)
  {
      error_log('User registered: ' . $event->getUser()->getEmail());
  }
  

• Database Dumps: For user data issues, dump the fos_user table:

  php bin/console doctrine:query:sql "SELECT * FROM fos_user"
  

Extension Points

1. Custom User Provider Override the default provider for complex logic:

   # config/packages/security.yaml
   providers:
       app_user_provider:
           id: App\Security\UserProvider
   

   // src/Security/UserProvider.php
   use ComuneDI\Bundle\UserBundle\Model\UserInterface;
   
   class UserProvider implements UserProviderInterface
   {
       public function loadUserByUsername(string $username): UserInterface
       {
           // Custom logic (e.g., LDAP integration).
       }
   }
   

2. API Tokens For token-based auth, integrate with api-platform or nelmio/api-doc-bundle:

   # config/packages/api_platform.yaml
   resources:
       App\Entity\User:
           properties:
               token: ['get']
   

3. Testing Use Symfony’s WebTestCase to test user flows:

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