User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require akuma/user-bundle
   

   Ensure akuma/core-bundle (≥1.0.4) is also installed (dependency).

2. Enable the Bundle Add to config/bundles.php:

   Akuma\UserBundle\AkumaUserBundle::class => ['all' => true],
   

3. First Use Case: User Registration

   • Extend the provided AkumaUserBundle base entity (if needed) by overriding User model in src/User/User.php:

     namespace App\User;
     
     use Akuma\UserBundle\Entity\User as BaseUser;
     
     class User extends BaseUser { /* Custom fields/methods */ }
     

   • Configure routes in config/routes.yaml:

     akuma_user:
         resource: "@AkumaUserBundle/Resources/config/routing.yml"
         prefix: /user
     

   • Run migrations (if using Doctrine):

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

Implementation Patterns

Core Workflows

1. Authentication

   • Use Symfony’s built-in security system with fos_user integration:

     # config/packages/security.yaml
     security:
         providers:
             fos_userbundle:
                 id: fos_user.user_provider.username_email
         firewalls:
             main:
                 form_login:
                     provider: fos_userbundle
                     csrf_token_generator: security.csrf.token_manager
     

   • Customize login/logout paths in routing.yml or override templates in templates/AkumaUserBundle/.

2. User Roles & Permissions

   • Leverage fos_user roles (e.g., ROLE_ADMIN) or extend with Akuma’s core bundle:

     // src/User/User.php
     public function getRoles(): array
     {
         $roles = $this->roles;
         $roles[] = 'ROLE_USER'; // Default role
         return array_unique($roles);
     }
     

3. Profile Management

   • Extend the User entity to add fields (e.g., avatar, bio):

     // src/User/User.php
     /**
      * @ORM\Column(type="string", length=255, nullable=true)
      */
     private $avatar;
     

   • Create a form type (src/Form/UserType.php) and controller to handle updates:

     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
     
     class UserType extends AbstractType {
         public function buildForm(FormBuilderInterface $builder, array $options) {
             $builder->add('avatar', FileType::class);
             $builder->add('bio', TextType::class);
         }
     }
     

4. API Integration

   • Use Symfony’s serializers to expose user data:

     # config/packages/serializer.yaml
     framework:
         serializer:
             mapping:
                 paths: ['%kernel.project_dir%/config/serializer']
     

     Create config/serializer/Akuma.UserBundle.yaml:

     Akuma\UserBundle\Entity\User:
         attributes:
             id: ~
             email: ~
             roles: ~
     

Integration Tips

• Akuma Core Bundle: Use shared services (e.g., Akuma\CoreBundle\Service\Logger) for logging user actions.
• Event Listeners: Subscribe to fos_user.user_registered or fos_user.user_updated events:

  // src/EventListener/UserListener.php
  namespace App\EventListener;
  
  use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  use FOS\UserBundle\FOSUserEvents;
  use FOS\UserBundle\Event\FilterUserResponseEvent;
  
  class UserListener implements EventSubscriberInterface {
      public static function getSubscribedEvents() {
          return [
              FOSUserEvents::REGISTRATION_COMPLETED => 'onRegistration',
          ];
      }
  
      public function onRegistration(FilterUserResponseEvent $event) {
          // Send welcome email, etc.
      }
  }
  

• Custom Templates: Override default templates by copying from: vendor/akuma/user-bundle/Resources/views/ to templates/AkumaUserBundle/.

Gotchas and Tips

Pitfalls

1. Dependency Conflicts

   • fos_user-bundle (≥1.3) is a hard dependency. Ensure compatibility with your Symfony version (tested on Symfony 3.x/4.x).
   • If using Symfony 5+, check for breaking changes in fos_user (e.g., deprecated UserManager methods).

2. Migration Issues

   • The bundle assumes a User entity with fos_user fields (username, email, password). Custom migrations may break if fields are renamed.
   • Fix: Use Doctrine’s SchemaTool to compare schemas:

     php bin/console doctrine:schema:update --dump-sql
     

3. Template Overrides

   • Overriding templates requires strict naming (e.g., registration.html.twig must match the original path).
   • Tip: Use {% extends 'AkumaUserBundle:Registration:registration.html.twig' %} in custom templates.

4. CSRF Token Errors

   • If login fails with CSRF errors, ensure csrf_token_generator is configured in security.yaml (as shown above).

Debugging

• Enable Debug Mode: Add to config/packages/dev/security.yaml:

  security:
      debug: true
  

• Log User Events: Use Monolog to track user actions:

  // src/EventListener/UserLogger.php
  use Psr\Log\LoggerInterface;
  
  class UserLogger {
      public function __construct(private LoggerInterface $logger) {}
  
      public function logAction(User $user, string $action) {
          $this->logger->info("User {$user->getEmail()} performed {$action}");
      }
  }
  

Extension Points

1. Custom User Provider

   • Extend fos_user.user_provider.username_email to support custom logic:

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

   • Implement UserProviderInterface in src/Security/UserProvider.php.

2. Two-Factor Authentication (2FA)

   • Integrate with symfony/security or lexik/jwt-authentication-bundle:

     composer require lexik/jwt-authentication-bundle
     

   • Override User entity to add twoFactorSecret.

3. Social Logins

   • Use hwi/oauth-bundle and link to fos_user:

     composer require hwi/oauth-bundle
     

   • Configure in config/packages/hwi_oauth.yaml to connect to fos_user provider.

Configuration Quirks

• Email Verification
  • Disable by setting fos_user.registration.confirmation.enabled to false in config/packages/fos_user.yaml.
• Password Reset
  • Customize the reset token TTL in fos_user.resetting.token_ttl (default: 86400 seconds).
• Profile Picture Uploads
  • Configure file uploads in config/packages/vich_uploader.yaml if using VichUploaderBundle:

    vich_uploader:
        db_driver: orm
        mappings:
            user_avatar:
                uri_prefix: /uploads/avatars
                upload_destination: '%kernel.project_dir%/public/uploads/avatars'