Sam Ecore User Manager Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require canaltp/sam-ecore-user-manager-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       CanalTP\SamEcoreUserManagerBundle\SamEcoreUserManagerBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default configuration:

   php bin/console sam-ecore-user-manager:install
   

   This generates config/packages/sam_ecore_user_manager.yaml with default settings.

3. First Use Case Register a new user via CLI:

   php bin/console sam-ecore-user-manager:create-user
   

   Follow prompts to input user details (name, email, password, roles).

Key Files to Review

• Configuration: config/packages/sam_ecore_user_manager.yaml
• Commands: src/Command/ (for CLI interactions)
• Services: src/Service/ (core logic)
• Entities: src/Entity/ (user models)

Implementation Patterns

User Management Workflows

1. User Creation Use the UserManager service to programmatically create users:

   $userManager = $this->container->get('sam_ecore_user_manager.user_manager');
   $user = $userManager->createUser([
       'username' => 'john.doe',
       'email' => '[email protected]',
       'password' => 'securePassword123',
       'roles' => ['ROLE_USER'],
   ]);
   

2. Authentication Integration Extend Symfony’s security system by configuring the bundle’s firewall:

   # config/packages/security.yaml
   firewalls:
       main:
           sam_ecore_user_manager:
               login_path: app_login
               check_path: app_check
   

3. Role-Based Access Control (RBAC) Assign roles dynamically:

   $userManager->addRoleToUser($user, 'ROLE_ADMIN');
   $userManager->removeRoleFromUser($user, 'ROLE_USER');
   

4. Event Listeners Subscribe to user lifecycle events (e.g., UserCreatedEvent):

   // src/EventListener/UserListener.php
   class UserListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               SamEcoreUserManagerEvents::USER_CREATED => 'onUserCreated',
           ];
       }
   
       public function onUserCreated(UserCreatedEvent $event)
       {
           // Send welcome email, log activity, etc.
       }
   }
   

Integration Tips

• Custom User Providers Override the default user provider by extending AbstractUserProvider:

   class CustomUserProvider extends AbstractUserProvider
   {
       public function loadUserByUsername($username)
       {
           // Custom logic (e.g., fetch from external API)
       }
   }
  

  Register it in services.yaml:

  services:
      App\Security\CustomUserProvider:
          tags: [security.user_provider]
  

• API Integration Use the bundle’s UserManager in API controllers:

   #[Route('/api/users', methods: ['POST'])]
   public function createUser(Request $request, UserManager $userManager)
   {
       $data = json_decode($request->getContent(), true);
       $user = $userManager->createUser($data);
       return new JsonResponse(['user' => $user->getId()]);
   }
  

• Database Migrations The bundle includes migrations for the User entity. Run:

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

Gotchas and Tips

Common Pitfalls

1. Configuration Overrides

   • The bundle merges configurations. Ensure your sam_ecore_user_manager.yaml does not conflict with defaults:

     # Avoid overriding required keys like `user_class`.
     sam_ecore_user_manager:
         user_class: App\Entity\User  # Must match your entity
     

2. Password Hashing

   • The bundle uses Symfony’s UserPasswordHasher. If you customize the hasher, ensure it’s registered as a service:

     services:
         App\Security\CustomPasswordHasher:
             tags: [security.password_hasher]
     

3. Event Dispatching

   • Events are dispatched asynchronously by default. To debug, temporarily disable async:

     sam_ecore_user_manager:
         async_events: false
     

4. Role Hierarchy

   • The bundle supports role hierarchies (e.g., ROLE_ADMIN inherits ROLE_USER). Define hierarchies in config:

     security:
         role_hierarchy:
             ROLE_ADMIN: [ROLE_USER, ROLE_SUPER_ADMIN]
     

Debugging Tips

1. Enable Verbose Logging Add to config/packages/monolog.yaml:

   handlers:
       sam_ecore:
           type: stream
           path: "%kernel.logs_dir%/sam_ecore.log"
           level: debug
   

2. Dump User Data Use Symfony’s var dumper in controllers:

   $user = $userManager->findUserBy(['email' => '[email protected]']);
   dump($user); // Inspect properties
   

3. Check Doctrine Events If users aren’t persisting, verify Doctrine events are fired:

   // src/EventListener/DebugListener.php
   class DebugListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               Events::prePersist,
               Events::preUpdate,
           ];
       }
   
       public function onPrePersist(LifecycleEventArgs $args)
       {
           dump($args->getObject());
       }
   }
   

Extension Points

1. Custom User Entity Extend the default User entity:

   // src/Entity/CustomUser.php
   class CustomUser extends User
   {
       /**
        * @ORM\Column(type="string", nullable=true)
        */
       private $customField;
   }
   

   Update user_class in config:

   sam_ecore_user_manager:
       user_class: App\Entity\CustomUser
   

2. Add Fields to Registration Form Override the registration template or use a custom form:

   // src/Form/RegistrationFormType.php
   class RegistrationFormType extends AbstractType
   {
       public function buildForm(FormBuilderInterface $builder, array $options)
       {
           $builder->add('customField', TextType::class);
       }
   }
   

3. API Tokens Integrate with lexik/jwt-authentication-bundle for token-based auth:

   sam_ecore_user_manager:
       jwt:
           enabled: true
           secret_key: '%env(JWT_SECRET)%'
   

4. Multi-Tenancy Add a tenant_id field to the user entity and filter queries:

   $userManager->setTenantId(1); // Contextual tenant
   $users = $userManager->findAll();