User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require apiboxsym/user-bundle
   

   Add to config/bundles.php:

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

2. Database Migrations Run migrations to create required tables:

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

3. First Use Case: User Registration Expose the User resource via API Platform:

   # config/api_platform/resources.yaml
   resources:
       ApiBoxSym\UserBundle\Entity\User:
           collectionOperations:
               post: { method: 'POST', path: '/register' }
   

   Test with:

   curl -X POST http://your-app/register -d '{"email":"test@example.com","password":"secret"}'
   

Key Configuration

Check config/packages/apiboxsym_user.yaml for:

• Default roles (default_roles)
• Password hashing (password_hash_algorithm)
• Email verification settings (email_verification)

Implementation Patterns

Core Workflows

1. Role-Based Access Control (RBAC)

• Assign Roles to Users:

  $user = $userRepository->find($id);
  $user->addRole('ROLE_ADMIN'); // Uses Symfony's Role hierarchy
  $entityManager->flush();
  

• Check Permissions:

  $this->denyAccessUnlessGranted('ROLE_EDITOR', $user);
  // Or via custom permission:
  $this->denyAccessUnlessGranted('user:edit:own', $user);
  

2. Group Management

• Create Groups:

  $group = new Group();
  $group->setName('Developers');
  $group->addRole('ROLE_DEVELOPER');
  $entityManager->persist($group);
  

• Assign Users to Groups:

  $user->addGroup($group);
  

3. API Operations

• Admin Operations (protected by IS_AUTHENTICATED_FULLY):

  # config/api_platform/resources.yaml
  ApiBoxSym\UserBundle\Entity\User:
      itemOperations:
          put: { method: 'PUT', security: 'is_granted("ROLE_ADMIN")' }
  

• Aggregated Permissions: Use the PermissionChecker service to fetch all permissions for a user:

  $permissions = $permissionChecker->getPermissionsForUser($user);
  

4. Event Listeners

• Password Reset:

  // src/EventListener/UserPasswordResetListener.php
  public function onPasswordReset(UserPasswordResetEvent $event) {
      $this->mailer->send(new ResetPasswordEmail($event->getUser()));
  }
  

  Register in services.yaml:

  services:
      App\EventListener\UserPasswordResetListener:
          tags:
              - { name: 'kernel.event_listener', event: 'user.password_reset' }
  

Integration Tips

With Symfony Security

• Custom User Provider: Extend ApiBoxSym\UserBundle\Security\UserProvider to add custom logic:

  class CustomUserProvider extends UserProvider {
      public function loadUserByIdentifier($identifier) {
          // Custom logic
      }
  }
  

  Register in security.yaml:

  providers:
      app_user_provider:
          id: App\Security\CustomUserProvider
  

With API Platform

• Custom Serialization: Override User serialization via ApiPlatform\Metadata\Operation:

  #[ApiResource(
      operations: [
          new Get(
              normalizationContext: ['groups' => ['user:read']]
          )
      ]
  )]
  

With Doctrine

• Custom Repositories: Extend ApiBoxSym\UserBundle\Repository\UserRepository:

  class CustomUserRepository extends UserRepository {
      public function findByRole(string $role) {
          return $this->createQueryBuilder('u')
              ->where('u.roles LIKE :role')
              ->setParameter('role', '%'.$role.'%')
              ->getQuery()
              ->getResult();
      }
  }
  

Gotchas and Tips

Pitfalls

1. Role Hierarchy Conflicts

   • If using Symfony’s role hierarchy (e.g., ROLE_ADMIN implies ROLE_USER), ensure your custom roles don’t conflict.
   • Fix: Test with php bin/console debug:role to validate hierarchy.

2. Permission Caching

   • The PermissionChecker caches permissions. Clear cache after role changes:

     php bin/console cache:clear
     

   • Tip: Use permission_checker.clear_cache() in post-update listeners.

3. Email Verification Tokens

   • Tokens expire after 24 hours by default. Customize in config/apiboxsym_user.yaml:

     email_verification:
         token_ttl: 86400 # 1 day in seconds
     

4. API Platform Security

   • Ensure IS_AUTHENTICATED_FULLY is used for sensitive operations to avoid bypassing RBAC.
   • Example:

     security: "is_granted('ROLE_ADMIN') or object == user"
     

5. Doctrine Lifecycle Callbacks

   • Avoid infinite loops by disabling callbacks during bulk operations:

     $entityManager->getConnection()->beginTransaction();
     $entityManager->getConnection()->getConfiguration()->setSQLLogger(null);
     // Bulk operations here
     $entityManager->getConnection()->commit();
     

Debugging Tips

1. Enable SQL Logging

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

2. Check Events Enable event dispatching logs:

   bin/console debug:event-dispatcher
   

3. Permission Debugging Dump user permissions:

   dump($permissionChecker->getPermissionsForUser($user));
   

Extension Points

1. Custom User Entity Extend ApiBoxSym\UserBundle\Entity\User:

   class CustomUser extends User {
       #[ORM\Column]
       private ?string $customField = null;
   
       // Add getters/setters
   }
   

   Update config/apiboxsym_user.yaml:

   user_entity: App\Entity\CustomUser
   

2. Custom Group/Role Entities Override default entities by configuring:

   group_entity: App\Entity\CustomGroup
   role_entity: App\Entity\CustomRole
   

3. Custom Permission Voter Create a voter and tag it:

   #[AsVoter]
   class CustomPermissionVoter implements VoterInterface {
       public function supports(string $attribute, $subject): bool {
           return $attribute === 'user:custom_action';
       }
   }
   

4. Custom Serializers Override User serialization groups:

   #[Groups(['user:public'])]
   public function getPublicName(): string {
       return $this->name;
   }
   

5. Custom Migrations Extend migrations by creating a post-install command:

   #[AsCommand(name: 'apiboxsym:user:post-install')]
   class PostInstallCommand extends Command {
       protected function execute(InputInterface $input, OutputInterface $output): int {
           // Custom logic (e.g., seed default roles)
       }
   }