Sonata User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require digitalmania/sonata-user-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       DigitalMania\SonataUserBundle\SonataUserBundle::class => ['extends' => 'FOSUserBundle'],
   ];
   

2. Database Setup: Run migrations (if using Doctrine):

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. First Use Case: Access the admin interface at /admin (ensure sonata_admin is installed) to manage users/groups via Sonata’s UI.

Where to Look First

• Admin Configuration: config/packages/sonata_user.yaml (or auto-generated).
• Templates: Override Sonata’s default templates in templates/SonataUserBundle/ (e.g., security/login.html.twig).
• Entities: Extend Sonata\UserBundle\Entity\User in src/Entity/User.php for custom fields.

Implementation Patterns

Core Workflows

1. User Management:

   • Use Sonata Admin (/admin/app/user) to CRUD users/groups via UI.
   • Customize fields via entity extensions (e.g., add phone to User):

     // src/Entity/User.php
     use Sonata\UserBundle\Entity\BaseUser as BaseUser;
     
     class User extends BaseUser {
         private $phone;
         // ... getters/setters
     }
     

2. Authentication:

   • Extend login logic by overriding SonataUserBundle:Security:login template.
   • Customize login form fields in config/packages/sonata_user.yaml:

     sonata_user:
         security:
             login:
                 form:
                     fields:
                         - username
                         - password
                         - _remember_me
     

3. Group Permissions:

   • Assign roles via Sonata Admin’s group editor.
   • Dynamically set roles in controllers:

     $user->addRole('ROLE_ADMIN');
     $manager->persist($user);
     $manager->flush();
     

4. Profile Management:

   • Extend user profiles with custom tabs (e.g., /profile/address):

     # config/packages/sonata_user.yaml
     sonata_user:
         profile:
             tabs:
                 - { label, route, template }
     

Integration Tips

• Symfony Security: Use sonata.user.secure voter for custom access checks.
• FOSUserBundle: Leverage existing FOS features (e.g., email verification) if extending it.
• Sonata Admin: Integrate with other Sonata bundles (e.g., SonataMediaBundle) for media-rich profiles.
• APIs: Use Symfony’s serializer to expose user data:

  use Symfony\Component\Serializer\Annotation\Groups;
  
  class User {
      /**
       * @Groups({"api"})
       */
      public $username;
  }
  

Gotchas and Tips

Pitfalls

1. Bundle Extension Conflict:

   • If extending FOSUserBundle, ensure no duplicate configurations (e.g., fos_user in config/packages/).
   • Fix: Remove FOSUserBundle from bundles.php if using Sonata’s version.

2. Template Overrides:

   • Sonata templates are nested (e.g., SonataUserBundle:Security:login extends base.html.twig).
   • Tip: Clear cache (php bin/console cache:clear) after template changes.

3. Entity Inheritance:

   • Extending BaseUser requires proper __construct() chaining:

     public function __construct() {
         parent::__construct();
         $this->addRole('ROLE_USER'); // Default role
     }
     

4. Admin Route Conflicts:

   • Sonata Admin routes may clash with custom routes (e.g., /admin vs. /app).
   • Fix: Use _sonata_admin prefix or customize routes in sonata_admin.yaml.

Debugging

1. Permission Denied:

   • Check roles with dd($this->getUser()->getRoles()) in controllers.
   • Ensure roles are flushed to the database.

2. Form Validation Errors:

   • Validate custom fields in User entity:

     use Symfony\Component\Validator\Constraints as Assert;
     
     /**
      * @Assert\NotBlank
      */
     private $phone;
     

3. Cache Issues:

   • Clear cache after:
     • Adding new fields to entities.
     • Changing Sonata configurations.

Extension Points

1. Custom Fields:

   • Add fields to User entity and update the form type:

     // src/Form/Type/UserType.php
     $builder->add('phone', TextType::class);
     

2. Event Listeners:

   • Subscribe to Sonata events (e.g., sonata.user.register):

     // src/EventListener/UserListener.php
     use Sonata\UserBundle\Event\SonataUserEvents;
     
     public function onRegister(UserEvent $event) {
         $user = $event->getUser();
         $user->addRole('ROLE_CUSTOM');
     }
     

     Register in services.yaml:

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

3. API Endpoints:

   • Create custom controllers for user data:

     #[Route('/api/user', name: 'api_user')]
     public function getUser(UserInterface $user): JsonResponse {
         return new JsonResponse($user->getRoles());
     }
     

4. Profile Tabs:

   • Dynamically add tabs via services:

     # config/services.yaml
     App\Sonata\UserBundle\ProfileTab:
         tags:
             - { name: sonata.user.profile.tab, label: 'Custom Tab', route: 'app_custom_tab' }