Getting Started

Minimal Setup

Installation Add the bundle to your composer.json:

composer require beloop/user-bundle

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

Database Migration Run migrations (if provided) or manually create tables based on the bundle’s schema (e.g., users, roles, permissions). Check the bundle’s migrations/ folder or schema.xml for structure.

First Use Case Use the bundle’s UserManager to create a user:

use Beloop\UserBundle\Entity\User;
use Beloop\UserBundle\Manager\UserManager;

$userManager = $this->get('beloop_user.manager.user');
$user = $userManager->createUser();
$user->setUsername('john_doe');
$user->setEmail('john@example.com');
$user->setPlainPassword('secure123');
$userManager->updateUser($user);

Key Classes to Explore
- UserManager: Core service for CRUD operations.
- UserInterface: Base interface for user entities.
- RoleHierarchy: For role-based permissions (if implemented).
- Event Listeners: Check for user_created, user_updated events.

Implementation Patterns

Common Workflows

Authentication & Authorization

Login Logic: Use Symfony’s security component with the bundle’s user provider:

# config/packages/security.yaml
security:
    providers:
        beloop_user_provider:
            entity: { class: Beloop\UserBundle\Entity\User, property: username }

Role-Based Access: Attach roles to users via UserManager:

$user->addRole('ROLE_ADMIN');
$userManager->updateUser($user);

Validate roles in controllers:

$this->denyAccessUnlessGranted('ROLE_ADMIN');

User Profile Management

Update Profile:

$user = $userManager->findUserBy(['username' => 'john_doe']);
$user->setFirstName('John');
$userManager->updateUser($user);

Avatar Handling: If the bundle supports file uploads, use Symfony’s FileUploader or a custom listener to handle avatars.

Event-Driven Extensions

Listen to user events (e.g., UserEvents::USER_CREATED):

// src/EventListener/UserListener.php
use Beloop\UserBundle\Event\UserEvent;

class UserListener {
    public function onUserCreated(UserEvent $event) {
        // Send welcome email, log activity, etc.
    }
}

services:
    App\EventListener\UserListener:
        tags:
            - { name: kernel.event_listener, event: beloop_user.user_created, method: onUserCreated }

API Integration

Serialize Users: Use Symfony’s Serializer with custom normalization:

use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;

$normalizer = new ObjectNormalizer();
$userData = $normalizer->normalize($user, null, [
    'groups' => ['api']
]);

Annotate your User entity with @Groups({"api"}) for fields to expose.

Integration Tips

Custom User Entity Extend the bundle’s User entity if needed:

use Beloop\UserBundle\Entity\User as BaseUser;

class AppUser extends BaseUser {
    // Add custom fields
    private $customField;
}

Update the bundle’s configuration to use your entity:

beloop_user:
    user_class: App\Entity\AppUser

Form Integration Use Symfony’s UserType for forms:

use Beloop\UserBundle\Form\UserType;

$form = $this->createForm(UserType::class, $user);

Testing Mock the UserManager in tests:

$userManager = $this->createMock(UserManager::class);
$userManager->method('findUserBy')->willReturn($user);
$this->container->set('beloop_user.manager.user', $userManager);

Gotchas and Tips

Pitfalls

Archived Status
- The package is read-only with no active maintenance. Expect no updates or issue resolutions.
- Fork the repository if you need modifications (e.g., Symfony 5+ compatibility).
Lack of Documentation
- Assume minimal docs; explore the src/ directory for undocumented features.
- Key classes: UserManager, UserProvider, RoleHierarchy.
Database Schema Assumptions
- The bundle may assume specific table/column names (e.g., users, roles). Override via Doctrine mappings if needed:
```
# config/packages/doctrine.yaml
orm:
    entity_managers:
        default:
            mappings:
                BeloopUserBundle: ~
```
Event System Quirks
- Events may not be fully documented. Check Event/UserEvents.php for available events.
- Example undocumented event: beloop_user.user_updated.
Symfony Version Mismatch
- The last release (2019) targets Symfony 4.x. For Symfony 5/6:
  - Replace use statements (e.g., Symfony\Component\HttpFoundation\Request → Psr\HttpMessage\RequestInterface).
  - Update dependency constraints in composer.json.

Debugging Tips

Enable Debugging Add this to config/packages/dev/monolog.yaml to log user events:

handlers:
    user_events:
        type: stream
        path: "%kernel.logs_dir%/user_events.log"
        level: debug
        channels: ["event"]

Check Entity States Use Doctrine’s EntityManager to inspect user data:

$user = $userManager->findUserBy(['id' => 1]);
$em->getUnitOfWork()->getOriginalEntityData($user); // Compare with current state

Common Issues
- Password Hashing: Ensure User implements UserInterface with getPassword()/setPassword().
- Role Hierarchy: If using roles, verify RoleHierarchy is configured in security.yaml:
```
role_hierarchy:
    ROLE_ADMIN: [ROLE_USER, ROLE_EDITOR]
```

Extension Points

Custom User Fields Add fields to the User entity and update the form type:

// src/Form/Extension/AppUserTypeExtension.php
use Beloop\UserBundle\Form\UserType;

class AppUserTypeExtension extends AbstractTypeExtension {
    public function buildForm(FormBuilderInterface $builder, array $options) {
        $builder->add('customField', TextType::class);
    }
}

Override Templates The bundle may include Twig templates (e.g., user/profile.html.twig). Override them in templates/beloop_user/:
```
{# templates/beloop_user/user/profile.html.twig #}
{% extends 'base.html.twig' %}
```

Add Validation Extend the User entity with custom constraints:

use Symfony\Component\Validator\Constraints as Assert;

class AppUser extends BaseUser {
    /**
     * @Assert\Length(min=5)
     */
    private $customField;
}

API Resources Create a custom UserResource for API Platform (if used):

use ApiPlatform\Core\Annotation\ApiResource;

#[ApiResource]
class AppUser extends BaseUser {}

User Bundle Laravel Package