Sonata User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require awaresoft/sonata-user-bundle
   

   (Note: Due to symlinking requirements, follow the README's local setup guide if modifying the bundle.)

2. Enable the Bundle: Add to config/bundles.php:

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

3. First Use Case: Extend the default SonataUserBundle functionality (e.g., custom user fields or workflows). Example:

   php bin/console sonata:user:create --role=ROLE_ADMIN
   

Key Files to Review

• Configuration: config/packages/sonata_user.yaml (if auto-generated).
• Entities: src/Entity/User.php (default user model).
• Templates: templates/SonataUserBundle/ (override defaults via config/packages/twig.yaml).

Implementation Patterns

Core Workflows

1. User Management:

   • CRUD: Use SonataAdmin (php bin/console sonata:admin:generate) for user management UI.
   • Custom Fields: Extend the User entity:

     // src/Entity/User.php
     use Awaresoft\SonataUserBundle\Model\UserInterface;
     
     class User extends BaseUser implements UserInterface {
         /**
          * @ORM\Column(type="string", length=255, nullable=true)
          */
         private $customField;
     }
     

2. Authentication:

   • Override login templates in templates/SonataUserBundle/security/login.html.twig.
   • Customize login logic via event listeners:

     // src/EventListener/LoginListener.php
     use Awaresoft\SonataUserBundle\Event\LoginEvent;
     
     class LoginListener {
         public function onLogin(LoginEvent $event) {
             $user = $event->getUser();
             // Custom logic (e.g., log activity)
         }
     }
     

     Register in services.yaml:

     services:
         App\EventListener\LoginListener:
             tags:
                 - { name: 'kernel.event_listener', event: 'sonata.user.login', method: 'onLogin' }
     

3. Roles & Permissions:

   • Define roles in security.yaml:

     role_hierarchy:
         ROLE_ADMIN:       [ROLE_USER, ROLE_SONATA_ADMIN]
     

   • Use Sonata’s built-in ACLs for granular access control.

Integration Tips

• Laravel-Specific:

  • Use Symfony’s HttpFoundation components (e.g., Request, Response) via Laravel’s bridge.
  • For Laravel’s Eloquent, map Sonata’s ORM entities to Eloquent models:

    // src/Models/User.php
    class User extends Model implements UserInterface {
         protected $fillable = ['email', 'username', 'customField'];
    }
    

  • Override Sonata’s services in config/packages/sonata_user.yaml to inject Laravel dependencies.

• APIs:

  • Expose user endpoints via API Platform or custom controllers:

    // src/Controller/UserController.php
    use Awaresoft\SonataUserBundle\Model\UserManagerInterface;
    
    class UserController extends AbstractController {
         public function __construct(private UserManagerInterface $userManager) {}
    
         public function getUser() {
             return $this->userManager->findUserBy(['id' => 1]);
         }
    }
    

Gotchas and Tips

Common Pitfalls

1. Symlinking Issues:

   • If modifying the bundle, ensure the symlink to /src/Awaresoft exists. Clear cache after changes:

     php bin/console cache:clear
     

   • Debug Tip: Check vendor/composer/autoload_psr4.php for duplicate entries.

2. Entity Mismatches:

   • SonataUserBundle expects a BaseUser entity. If extending, ensure:
     • The entity implements UserInterface.
     • Doctrine mappings are correct (e.g., @ORM\Table(name="users")).
   • Fix: Regenerate the entity if fields are missing:

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

3. Template Overrides:

   • Overrides in templates/SonataUserBundle/ must match the original template structure.
   • Debug Tip: Use {{ dump(app.request.attributes) }} in templates to inspect request data.

4. Event System:

   • Events like sonata.user.login or sonata.user.register may not fire if the bundle isn’t properly bootstrapped.
   • Fix: Verify the bundle is enabled in bundles.php and dependencies are loaded.

Debugging

• Logs: Enable Sonata’s debug mode in config/packages/dev/sonata_user.yaml:

  sonata_user:
      debug: true
  

• Database: Use doctrine:query to inspect queries:

  php bin/console doctrine:query:sql "SELECT * FROM users"
  

Extension Points

1. Custom Providers:

   • Implement UserProviderInterface for custom user lookups:

     class CustomUserProvider implements UserProviderInterface {
         public function loadUserByUsername($username) {
             // Custom logic
         }
     }
     

   • Register in services.yaml:

     services:
         App\Security\User\CustomUserProvider:
             tags: ['sonata.user.provider']
     

2. Workflow Extensions:

   • Extend the UserManager service to add pre/post hooks:

     // src/Service/CustomUserManager.php
     class CustomUserManager extends UserManager {
         public function createUser(array $data) {
             $user = parent::createUser($data);
             // Custom logic (e.g., send welcome email)
             return $user;
         }
     }
     

   • Override the service in config/packages/sonata_user.yaml:

     sonata_user:
         user_manager: App\Service\CustomUserManager
     

3. API Tokens:

   • For API use, integrate with lexik/jwt-authentication-bundle:

     # config/packages/security.yaml
     security:
         firewalls:
             api:
                 pattern: ^/api
                 stateless: true
                 jwt: ~