Getting Started

Minimal Setup

Installation Add the package via Composer:
```
composer require black/user
```
Check the releases page for a stable version (e.g., "black/user": "1.2.0").

Symfony Bundle Integration Register the bundle in config/bundles.php:

return [
    // ...
    Black\Bundle\UserBundle\BlackUserBundle::class => ['all' => true],
];

Basic Configuration Define your custom User entity (e.g., src/Account/Domain/Entity/User.php) and configure the bundle in config/packages/black_user.yaml:
```
black_user:
    db_driver: orm       # or 'doctrine' if using Doctrine ORM
    user_class: Account\Domain\Entity\User
```
First Use Case Create a simple User entity extending the base class (example placeholder—check the package’s src/Entity/User.php for details):
```
namespace Account\Domain\Entity;

use Black\User\Entity\User as BaseUser;

class User extends BaseUser
{
    // Add custom fields/methods here
}
```
Run migrations (php bin/console doctrine:migrations:diff + php bin/console doctrine:migrations:migrate).

Implementation Patterns

Core Workflows

User Creation Use the bundle’s command or service to create users:

use Black\User\Command\CreateUserCommand;
use Black\User\CommandHandler\CreateUserCommandHandler;

$command = new CreateUserCommand(
    'john.doe@example.com',
    'securepassword123',
    ['role' => 'ROLE_USER']
);
$handler = new CreateUserCommandHandler($entityManager);
$user = $handler->handle($command);

Authentication Integrate with Symfony’s security system by configuring a UserProvider:

# config/packages/security.yaml
security:
    providers:
        black_user_provider:
            id: Black\User\Security\UserProvider

Domain-Driven Design (DDD) Patterns

Commands/Queries: Leverage the CQRS structure for user operations (e.g., UpdateUserCommand, GetUserQuery).

Events: Subscribe to user lifecycle events (e.g., UserRegisteredEvent) for side effects:

use Black\User\Event\UserRegisteredEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class UserRegistrationSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            UserRegisteredEvent::class => 'onUserRegistered',
        ];
    }

    public function onUserRegistered(UserRegisteredEvent $event): void
    {
        // Send welcome email, log activity, etc.
    }
}

API Integration Use Symfony’s serializer to expose user data:

use Black\User\Entity\User;
use Symfony\Component\Serializer\Annotation\Groups;

class User
{
    #[Groups(['user:read'])]
    public string $email;

    #[Groups(['user:write'])]
    public string $password;
}

Integration Tips

Doctrine ORM: Ensure your User entity uses Doctrine annotations/attributes for mappings (e.g., @ORM\Entity).
Validation: Extend the base User class to add custom validation constraints (e.g., Symfony’s Assert).
Testing: Mock the CommandHandler or use the bundle’s test utilities for unit/integration tests.

Gotchas and Tips

Pitfalls

Version Mismatches
- The @stable Composer constraint may pull unstable versions. Pin to a specific release (e.g., "1.2.0").
- Check the changelog for breaking changes.
Entity Inheritance
- Override the base User class carefully. Avoid breaking method signatures or required fields.
- Example: If the base class uses protected properties, ensure your subclass initializes them in the constructor.
Configuration Overrides
- The db_driver must match your setup (orm for Doctrine, doctrine for Doctrine ORM). Misconfiguration may cause:
```
[RuntimeException] Driver "xyz" is not supported.
```
Event Dispatching
- Events like UserRegisteredEvent are not auto-dispatched. Subscribe explicitly in your services.yaml:
```
services:
    App\EventSubscriber\UserRegistrationSubscriber:
        tags: ['kernel.event_subscriber']
```

Debugging

Command Failures: Check the CommandHandler for exceptions. Enable debug mode (APP_DEBUG=1) for stack traces.
Entity Not Found: Verify the user_class in black_user.yaml matches your custom entity’s fully qualified name.
Database Issues: Run php bin/console doctrine:schema:validate to check schema compatibility.

Extension Points

Custom Commands Extend the base commands (e.g., CreateUserCommand) or create new ones by implementing CommandInterface:

namespace App\Command;

use Black\User\Command\CommandInterface;

class CustomUserCommand implements CommandInterface
{
    // Implement handle() and validate() methods
}

Event Customization Create custom events by extending UserEvent:

namespace App\Event;

use Black\User\Event\UserEvent;

class UserProfileUpdatedEvent extends UserEvent
{
    public function __construct(User $user, array $changes)
    {
        parent::__construct($user);
        $this->changes = $changes;
    }
}

Security Integration Override the UserProvider to add custom logic (e.g., multi-factor auth):

use Black\User\Security\UserProvider as BaseUserProvider;

class CustomUserProvider extends BaseUserProvider
{
    public function loadUserByIdentifier(string $identifier): UserInterface
    {
        // Custom logic here
        return parent::loadUserByIdentifier($identifier);
    }
}

API Resources Use Symfony’s Resource component to shape API responses:

use Symfony\Component\Serializer\Annotation\Context;

#[Context(['groups' => ['user:read']])]
class UserResource
{
    public function __construct(private User $user) {}

    public function getData(): array
    {
        return [
            'id' => $this->user->getId(),
            'email' => $this->user->getEmail(),
        ];
    }
}

Pro Tips

Leverage Traits: The base User class may use traits (e.g., UserTrait). Reuse them in your entity to avoid duplication.
Doctrine Lifecycle Callbacks: Add @ORM\PrePersist/@ORM\PostLoad to the User entity for automatic actions (e.g., password hashing).

Symfony UX: Integrate with Symfony UX for reactive forms or Turbo links:

use Symfony\UX\LiveComponent\Attribute\AsLiveComponent;

#[AsLiveComponent('user_form')]
class UserFormComponent extends Component
{
    // Handle user updates in real-time
}

User Laravel Package