User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sonata-project/user-bundle
   

   Add to config/bundles.php:

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

2. Database Migration: Run the default schema migration:

   php bin/console doctrine:schema:update --force
   

   (Or customize via sonata_user.doctrine.orm.entity_manager config.)

3. First Use Case: Register a new user via the built-in admin interface (accessible at /admin after enabling SonataAdminBundle):

   php bin/console sonata:easy-extends:generate SonataUserBundle
   

Where to Look First

• Configuration: config/packages/sonata_user.yaml (auto-generated).
• Admin Dashboard: /admin (for CRUD operations).
• Documentation: SonataUserBundle Docs (check the 5.x branch for Laravel/Symfony 6+ compatibility).
• Templates: Override in templates/SonataUserBundle/ (e.g., registration.html.twig).

Implementation Patterns

Core Workflows

1. User Registration:

   • Extend the registration form by overriding SonataUserBundle:Registration:register.html.twig.
   • Add custom fields via sonata_user.registration.form.type config:

     sonata_user:
         registration:
             form:
                 type: App\Form\RegistrationType
     

2. Authentication:

   • Use Symfony’s security system (Laravel’s auth facade) with Sonata’s user provider:

     // config/packages/security.yaml
     providers:
         sonata_user:
             entity:
                 class: App\Entity\User
                 property: email
     

3. Admin Integration:

   • Enable SonataAdminBundle for user management:

     composer require sonata-project/admin-bundle
     php bin/console sonata:easy-extends:generate SonataUserBundle
     

   • Customize admin classes (e.g., src/Entity/UserAdmin.php).

4. API Integration:

   • Use Symfony’s Serializer with Sonata’s user entity:

     // src/Serializer/UserNormalizer.php
     use Sonata\UserBundle\Model\UserInterface;
     class UserNormalizer implements NormalizerInterface { ... }
     

Integration Tips

• Laravel-Specific:

  • Use php artisan make:auth for basic auth, then extend Sonata’s templates.
  • For API tokens, integrate with lexik/jwt-auth-bundle:

    sonata_user:
         security:
             encoder:
                 algorithm: auto
                 options:
                     jwt: true
    

• Custom User Fields: Add fields to the User entity (e.g., phoneNumber) and update the form type:

  // src/Form/RegistrationType.php
  public function buildForm(FormBuilderInterface $builder, array $options) {
      $builder->add('phoneNumber');
  }
  

• Event Listeners: Listen to user events (e.g., post-registration):

  // src/EventListener/UserListener.php
  public function onUserRegistered(UserEvent $event) {
      $user = $event->getUser();
      // Send welcome email, etc.
  }
  

  Register in services.yaml:

  services:
      App\EventListener\UserListener:
          tags:
              - { name: 'kernel.event_listener', event: 'sonata.user.register', method: 'onUserRegistered' }
  

Gotchas and Tips

Pitfalls

1. Doctrine Migrations:

   • Avoid manual schema changes to sonata_user tables (e.g., user, group). Use Sonata’s migration tools:

     php bin/console sonata:user:manager:create
     

2. Security:

   • CSRF Tokens: Sonata uses Symfony’s CSRF system. Ensure your forms include {{ csrf_token() }}.
   • Password Hashing: Sonata defaults to auto encoder. For Laravel, configure in security.yaml:

     security:
         encoders:
             App\Entity\User:
                 algorithm: argon2id
     

3. Template Overrides:

   • Clear cache after overriding templates:

     php bin/console cache:clear
     

4. Admin Route Conflicts:

   • SonataAdmin routes may conflict with Laravel’s default routes. Use _route in Twig:

     {{ path('_sonata_admin_dashboard') }}
     

Debugging

1. Common Issues:

   • 404 on /admin: Ensure SonataAdminBundle is installed and routes are dumped:

     php bin/console debug:router | grep sonata_admin
     

   • Blank Registration Page: Check sonata_user.registration.form.type config and template paths.

2. Logging: Enable Sonata’s debug mode in config/packages/sonata_user.yaml:

   sonata_user:
       debug: true
   

Extension Points

1. Custom User Model: Extend Sonata\UserBundle\Model\UserInterface:

   // src/Entity/User.php
   class User extends BaseUser implements UserInterface { ... }
   

   Update sonata_user.class.user in config.

2. Dynamic Groups: Use sonata.user.group.loader to load groups dynamically:

   sonata_user:
       group:
           loader: App\Loader\GroupLoader
   

3. API Resources: Create custom API resources for Sonata’s entities:

   // src/ApiResource/UserResource.php
   class UserResource extends JsonResource { ... }
   

4. Email Templates: Override email templates in templates/SonataUserBundle/Email/ (e.g., registration.html.twig).

Laravel-Specific Quirks

• Service Container: Sonata uses Symfony’s DI. For Laravel, bind Sonata services in config/services.php:

  'sonata.user.manager' => \Sonata\UserBundle\Model\UserManagerInterface::class,
  

• Blade vs. Twig: Sonata templates use Twig. For Blade, create a Twig loader or use symfony/twig-bridge:

  composer require symfony/twig-bridge
  

• Artisan Commands: Sonata commands (e.g., sonata:user:create) may not work out-of-the-box. Alias them in console/commands.php:

  $commands[] = \Sonata\UserBundle\Command\UserCommand::class;