Getting Started

Minimal Setup

Installation:
```
composer require ibexa/user
```
Ensure your config/packages/ibexa_user.yaml is properly configured (default config is auto-loaded).

First Use Case:

User Registration: Extend the default registration form by configuring allowed field definitions in config/packages/ibexa_user.yaml:

ibexa_user:
    user_registration:
        form:
            allowed_field_definitions_identifiers: ['email', 'full_name', 'custom_field']

Invitation Flow: Use the CLI to invite users:

php bin/console ibexa:user:invite --email=test@example.com --role=editor

Key Classes to Explore:
- Ibexa\User\API\Permission\PermissionResolver (for role-based access checks).
- Ibexa\User\API\Service\UserService (core user CRUD operations).
- Ibexa\User\API\Service\InvitationService (invitation workflows).
Twig Integration: Fetch the current user in templates:
```
{{ ibexa_user_current()|raw }}
```

Implementation Patterns

Common Workflows

1. Custom User Registration Forms

Extend the Form Type:

use Ibexa\User\API\Form\Type\UserRegistrationType;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;

class CustomUserRegistrationType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->add('custom_field', TextType::class);
    }

    public function getParent()
    {
        return UserRegistrationType::class;
    }
}

Override in Config:

ibexa_user:
    user_registration:
        form:
            type: App\Form\Type\CustomUserRegistrationType

2. Role-Based Access Control

Check Permissions:

use Ibexa\User\API\Permission\PermissionResolverInterface;

public function __construct(private PermissionResolverInterface $permissionResolver) {}

public function isAllowed(string $permission, string $userId): bool
{
    return $this->permissionResolver->hasPermission($permission, $userId);
}

Common Permissions:
- ibexa.user.update (edit user profile).
- ibexa.user.settings (access user settings).

3. Invitation Workflow

Send Invitations Programmatically:

use Ibexa\User\API\Service\InvitationServiceInterface;

public function inviteUser(InvitationServiceInterface $invitationService, string $email, string $role)
{
    $invitation = $invitationService->createInvitation($email, $role);
    $invitationService->sendInvitationEmail($invitation);
}

Refresh Expired Invitations:

php bin/console ibexa:user:invitation:refresh --id=123

4. User Profile Customization

Add Custom Fields to User Settings:

ibexa_user:
    user_settings:
        form:
            allowed_field_definitions_identifiers: ['email', 'full_name', 'custom_field']

Override Templates: Place custom templates in templates/ibexa_user/ (e.g., registration.html.twig).

5. Event-Driven Extensions

Listen to User Events:

use Ibexa\User\API\Event\UserEvents;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(event: UserEvents::USER_REGISTERED)]
public function onUserRegistered(UserRegisteredEvent $event)
{
    // Send welcome email or log the event
}

Integration Tips

Laravel-Specific Adaptations

Service Container Binding: Bind Ibexa services to Laravel’s container in AppServiceProvider:

public function register()
{
    $this->app->bind(
        Ibexa\User\API\Service\UserServiceInterface::class,
        Ibexa\User\API\Service\UserService::class
    );
}

Route Prefixing: Use Laravel’s route model binding for user routes:

Route::get('/users/{user}', [UserController::class, 'show'])
    ->name('users.show');

Authentication: Integrate with Laravel’s auth system by extending Ibexa\User\API\Service\UserService to return Laravel User models:

public function getUserById(string $userId): ?User
{
    $ibexaUser = parent::getUserById($userId);
    return $ibexaUser ? new LaravelUser($ibexaUser) : null;
}

Migrations: Ibexa’s user tables are auto-created. For custom fields, extend the ibexa_user table via Laravel migrations:
```
Schema::table('ibexa_user', function (Blueprint $table) {
    $table->string('custom_field')->nullable();
});
```

Gotchas and Tips

Pitfalls

Field Definition Configuration:
- Issue: Forgetting to configure allowed_field_definitions_identifiers in ibexa_user.yaml may hide all custom fields from forms.
- Fix: Explicitly list all required fields:
```
ibexa_user:
    user_registration:
        form:
            allowed_field_definitions_identifiers: ['email', 'full_name']
```
Permission Overrides:
- Issue: Custom permission checks may conflict with Ibexa’s built-in ACLs.
- Fix: Use PermissionResolver for consistency:
```
$this->permissionResolver->hasPermission('ibexa.user.update', $userId);
```
Invitation Expiry:
- Issue: Invitations expire after 7 days by default. No built-in way to extend this without code changes.
- Fix: Override the Invitation entity’s isExpired() method or adjust the TTL in config:
```
ibexa_user:
    invitation:
        ttl: 14400 # 4 hours in seconds
```
Template Overrides:
- Issue: Twig templates in templates/ibexa_user/ may not load if the ibexa_user namespace is missing.
- Fix: Ensure templates are named correctly (e.g., registration.html.twig) and the ibexa_user bundle is enabled.
Database Schema Changes:
- Issue: Ibexa’s migrations may conflict with Laravel’s schema updates.
- Fix: Run Ibexa migrations after Laravel’s:
```
php bin/console doctrine:migrations:migrate
php bin/console ibexa:install:upgrade
```

Debugging Tips

Enable Debug Mode: Set IBEXA_DEBUG=1 in your environment to log Ibexa-specific errors.
Check Event Dispatcher: Use Laravel’s event listener debugging:
```
php artisan event:list
```

Invitation Debugging: Dump invitation data to verify expiry or sending status:

$invitation = $invitationService->findInvitationById($id);
dump($invitation->isExpired(), $invitation->getEmail());

Permission Issues: Log permission checks for troubleshooting:

try {
    $this->permissionResolver->hasPermission('ibexa.user.update', $userId);
} catch (\Ibexa\Core\Base\Exceptions\UnauthorizedException $e) {
    \Log::error('Permission denied: ' . $e->getMessage());
}

Extension Points

Custom User Providers: Implement Ibexa\User\API\Service\UserProviderInterface for alternative user sources (e.g., LDAP).
Email Templates: Override Twig templates for emails in templates/ibexa_user/email/ (e.g., registration.html.twig).
CLI Commands: Extend Ibexa’s commands by creating custom commands that use InvitationService or UserService.
Field Types: Add custom field types for user profiles by implementing Ibexa\Core\FieldType\FieldType and registering them in Ibexa’s field type registry.

Notifications: Extend the UserRegister and UserPasswordReset notifications by creating custom event subscribers:

#[AsEventListener(UserEvents::USER_REGISTERED)]
public function onUserRegistered(UserRegisteredEvent $event)
{
    // Send custom notification
}

Configuration Quirks

Symfony Mailer: Ibex

User Laravel Package