User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require core2pl/user-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+):

   return [
       // ...
       Core2pl\UserBundle\Core2plUserBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default configuration:

   php bin/console core2pl:user:install
   

   This creates a User entity (if not already present) and updates the database schema.

3. First Use Case Use the bundle’s built-in commands to manage users:

   # Create a new user
   php bin/console core2pl:user:create --username=test [email protected] --password=password
   
   # List users
   php bin/console core2pl:user:list
   

Implementation Patterns

Workflows

1. Authentication The bundle integrates with Symfony’s security system. Extend the User entity to add custom fields:

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

   Update the security configuration (config/packages/security.yaml):

   providers:
       app_user_provider:
           entity:
               class: App\Entity\User
               property: username
   

2. Role Management Assign roles via the CLI or programmatically:

   php bin/console core2pl:user:role --username=test --role=ROLE_ADMIN
   

   Or in code:

   $user = $this->getDoctrine()->getRepository(User::class)->findOneBy(['username' => 'test']);
   $user->addRole('ROLE_ADMIN');
   $this->getDoctrine()->getManager()->flush();
   

3. Event Listeners Subscribe to user events (e.g., UserEvents::POST_CREATE):

   // src/EventListener/UserListener.php
   namespace App\EventListener;
   
   use Core2pl\UserBundle\Event\UserEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class UserListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               UserEvent::POST_CREATE => 'onUserCreated',
           ];
       }
   
       public function onUserCreated(UserEvent $event)
       {
           // Custom logic (e.g., send welcome email)
       }
   }
   

4. API Integration Use the bundle’s serializers to expose user data in APIs:

   # config/packages/serializer.yaml
   attributes:
       Core2pl\UserBundle\Entity\User:
           attributes:
               password: false # Hide sensitive fields
   

Gotchas and Tips

Pitfalls

1. Database Schema Conflicts

   • If you extend the User entity, ensure the new fields are added before running migrations. The bundle’s install command may overwrite existing schema changes.
   • Fix: Manually merge migrations or use Doctrine’s diff-schema tool.

2. Security Misconfigurations

   • The bundle defaults to plain-text password storage if not configured. Always use Symfony’s UserPasswordHasher:

     // src/Entity/User.php
     use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
     use Symfony\Component\Security\Core\User\PasswordUpgraderInterface;
     
     class User extends BaseUser implements PasswordAuthenticatedUserInterface, PasswordUpgraderInterface
     {
         // ...
     }
     

   • Tip: Enable security.user_password_hasher in config/packages/security.yaml.

3. CLI Command Conflicts

   • The bundle’s commands (e.g., core2pl:user:create) may conflict with custom commands named similarly.
   • Fix: Use unique command names or override the bundle’s commands in your AppKernel.

4. Translation Issues

   • The bundle uses Symfony’s translation system. Ensure your translations/ directory includes the bundle’s messages:

     mkdir -p translations/core2pl.user.en.yaml
     

   • Tip: Extend translations in config/packages/translation.yaml:

     paths: ['%kernel.project_dir%/translations', '%kernel.project_dir%/vendor/core2pl/user-bundle/Resources/translations']
     

Debugging

1. Event Dispatching

   • Verify events are fired by enabling debug mode and checking logs:

     php bin/console debug:event-dispatcher
     

   • Tip: Use EventDispatcher::addListener() for debugging:

     $dispatcher->addListener(UserEvent::POST_CREATE, function ($event) {
         error_log('User created: ' . $event->getUser()->getUsername());
     });
     

2. Doctrine Queries

   • Log SQL queries to debug repository issues:

     # config/packages/dev/doctrine.yaml
     doctrine:
         dbal:
             logging: true
             profiling: true
     

Extension Points

1. Custom User Fields

   • Override the User entity and extend the UserType form:

     // src/Form/Extension/UserTypeExtension.php
     namespace App\Form\Extension;
     
     use Core2pl\UserBundle\Form\UserType;
     use Symfony\Component\Form\AbstractTypeExtension;
     use Symfony\Component\Form\FormBuilderInterface;
     
     class UserTypeExtension extends AbstractTypeExtension
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             $builder->add('customField');
         }
     
         public static function getExtendedType(): string
         {
             return UserType::class;
         }
     }
     

2. Authentication Providers

   • Replace the default provider with a custom one (e.g., OAuth):

     # config/packages/security.yaml
     security:
         providers:
             oauth_user_provider:
                 id: App\Security\OAuthUserProvider
     

3. API Resources

   • Extend the bundle’s API platform integration:

     // src/Entity/User.php
     use ApiPlatform\Core\Annotation\ApiResource;
     
     #[ApiResource]
     class User extends BaseUser { ... }