Platform Account Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require digitalstate/platform-account-bundle
   

   Add to config/app.php under ExtraBundles:

   DigitalState\PlatformAccountBundle\PlatformAccountBundle::class,
   

2. Publish Configuration

   php artisan vendor:publish --provider="DigitalState\PlatformAccountBundle\PlatformAccountBundle" --tag="config"
   

   This generates config/platform_account.php with default settings.

3. Run Migrations

   php artisan migrate
   

   The bundle includes migrations for core account tables (e.g., users, user_profiles, auth_tokens).

4. First Use Case: User Registration Use the provided controller (AccountController) or extend it:

   use DigitalState\PlatformAccountBundle\Controller\AccountController;
   
   Route::post('/register', [AccountController::class, 'register']);
   

Where to Look First

• Core Entities: src/Entity/User.php and src/Entity/UserProfile.php define the base models.
• Services: src/Service/UserService.php handles business logic (e.g., registration, profile updates).
• Events: src/Event/UserRegisteredEvent.php for extending workflows (e.g., email verification).
• Forms: src/Form/UserRegistrationType.php for customizing registration fields.

Implementation Patterns

Workflows

1. User Lifecycle

   • Registration: Extend UserRegistrationType to add fields or validation.

     $builder->add('custom_field', TextType::class, ['required' => true]);
     

   • Authentication: Use the built-in Authenticator service:

     $this->authenticator->login($credentials);
     

   • Profile Management: Update profiles via UserProfileService:

     $profile = $this->profileService->update($user, ['avatar' => $file]);
     

2. Integration with Existing Systems

   • Custom User Provider: Implement UserProviderInterface for non-standard auth:

     class CustomUserProvider implements UserProviderInterface {
         public function retrieveByCredentials(array $credentials) { ... }
     }
     

   • Event Listeners: Subscribe to UserRegisteredEvent or UserUpdatedEvent:

     // In a service provider
     $this->eventDispatcher->addListener(
         UserRegisteredEvent::class,
         [YourListener::class, 'handleRegistration']
     );
     

3. API-First Approach

   • Use the AccountApiController for REST endpoints:

     Route::apiResource('accounts', AccountApiController::class);
     

   • Customize serialization with src/Serializer/UserNormalizer.php.

Tips for Daily Use

• Dependency Injection: Prefer injecting UserService or Authenticator over direct EntityManager usage.
• Form Handling: Reuse UserRegistrationType or UserProfileType to avoid reinventing validation.
• Testing: Use the AccountBundleTestCase base class for unit/integration tests:

  use DigitalState\PlatformAccountBundle\Tests\AccountBundleTestCase;
  
  class MyTest extends AccountBundleTestCase { ... }
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If extending the users table, run php artisan migrate:status to avoid schema conflicts.
   • Fix: Use Schema::table() in custom migrations to add columns post-install.

2. Event Dispatching

   • Events like UserRegisteredEvent are dispatched after the user is saved. Override UserService::register() to add pre-save logic:

     public function register(array $data) {
         $this->dispatchEvent(new UserPreRegisteredEvent($data));
         // ... rest of logic
     }
     

3. Password Hashing

   • The bundle uses Symfony’s UserPasswordHasherInterface. For custom hashing, bind your implementation:

     # config/services.yaml
     DigitalState\PlatformAccountBundle\Service\UserService:
         arguments:
             $passwordHasher: '@your_custom_hasher'
     

Debugging

• Token Validation: Use php artisan platform-account:validate-token to debug auth tokens.
• Log Events: Enable event logging in config/platform_account.php:

  'debug' => [
      'log_events' => true,
  ],
  

  Check storage/logs/platform_account.log for event traces.

Extension Points

1. Custom Fields Add fields to UserProfile via a custom entity:

   /**
    * @ORM\Entity
    */
   class ExtendedUserProfile extends UserProfile {
       /**
        * @ORM\Column(type="string")
        */
       private $customField;
   }
   

   Update UserProfileType to include the new field.

2. Multi-Tenant Support Override UserService::findUserByEmail() to scope by tenant:

   public function findUserByEmail(string $email): ?User {
       return $this->userRepository->findOneBy([
           'email' => $email,
           'tenant_id' => $this->tenantService->getId(),
       ]);
   }
   

3. Third-Party Auth Integrate OAuth via Authenticator:

   $this->authenticator->loginWithOAuth(
       $providerName,
       $accessToken
   );
   

Configuration Quirks

• Email Verification: Disable in config/platform_account.php:

  'verification' => [
      'enabled' => false,
  ],
  

• Password Policies: Customize via:

  'password' => [
      'min_length' => 12,
      'require_uppercase' => true,
  ],