Symfony User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require b4rb4ross4/symfony-user-bundle "@dev"
   

   Ensure your project uses Symfony 3.x, PHP 7.1+, and Doctrine ORM.

2. Enable the Bundle Register in config/bundles.php (Symfony 3.3+):

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

3. Configure Routes Add to config/routes.yaml:

   b4rb4ross4_user:
       resource: '@B4rb4ross4UserBundle/Controller/'
       type: annotation
   

4. Security Configuration Update config/packages/security.yaml:

   firewalls:
       main:
           form_login:
               check_path: b4rb4ross4_user_login
               login_path: b4rb4ross4_user_login
           logout:
               path: b4rb4ross4_user_logout
   

5. Twig Base Template Set in config/packages/twig.yaml:

   twig:
       globals:
           user_base_view: "%b4rb4ross4.user.base_view%"
   

   Define the parameter in config/packages/parameters.yaml:

   parameters:
       b4rb4ross4.user.base_view: 'backend/base.html.twig'
   

6. First Use Case Extend the User entity (located at src/Entity/User.php by default) to add custom fields:

   use B4rb4ross4\UserBundle\Entity\User as BaseUser;
   
   class User extends BaseUser {
       /**
        * @ORM\Column(type="string", length=255, nullable=true)
        */
       private $customField;
   }
   

Implementation Patterns

Core Workflows

1. Authentication Flow

   • Use the pre-configured login/logout routes (b4rb4ross4_user_login/b4rb4ross4_user_logout).
   • Customize the login form template by extending B4rb4ross4UserBundle:User:login.html.twig.

2. User Management

   • CRUD Operations: The bundle provides controllers for user management (e.g., UserController). Override methods in a custom controller to extend functionality.

     // src/Controller/CustomUserController.php
     use B4rb4ross4\UserBundle\Controller\UserController as BaseUserController;
     
     class CustomUserController extends BaseUserController {
         public function editAction(Request $request, User $user) {
             // Custom logic before/after parent edit
             return parent::editAction($request, $user);
         }
     }
     

   • Registration: Extend the registration form by overriding B4rb4ross4UserBundle:User:register.html.twig or the registerAction in a custom controller.

3. Role-Based Access Control (RBAC)

   • Assign roles via the User entity:

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

   • Protect routes in security.yaml:

     access_control:
         - { path: ^/admin, roles: ROLE_ADMIN }
     

4. Twig Integration

   • Access user data in templates:

     {{ app.user.fullName }}  {# Assuming a custom getter in User entity #}
     

   • Extend the base template (backend/base.html.twig) to include user-specific UI elements (e.g., dropdown menus).

5. Event Listeners

   • Listen to user events (e.g., user.registered, user.updated) by implementing UserEvents:

     use B4rb4ross4\UserBundle\Event\UserEvents;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     
     class UserEventSubscriber implements EventSubscriberInterface {
         public static function getSubscribedEvents() {
             return [
                 UserEvents::REGISTERED => 'onUserRegistered',
             ];
         }
     
         public function onUserRegistered(UserEvent $event) {
             // Send welcome email, etc.
         }
     }
     

Gotchas and Tips

Common Pitfalls

1. Entity Inheritance

   • If extending the User entity, ensure the parent class (B4rb4ross4\UserBundle\Entity\User) is properly referenced in your User class:

     use B4rb4ross4\UserBundle\Entity\User as BaseUser;
     class User extends BaseUser { ... }
     

   • Gotcha: Forgetting to call parent::__construct() in your custom User constructor can break serialization/deserialization.

2. Route Conflicts

   • The bundle’s routes (e.g., /login, /register) may conflict with existing routes. Use _prefix in routing.yml to namespace them:

     b4rb4ross4_user:
         resource: '@B4rb4ross4UserBundle/Controller/'
         type: annotation
         prefix: /auth
     

3. Security Configuration

   • Gotcha: Misconfiguring security.yaml (e.g., incorrect check_path or login_path) will break authentication. Always test login/logout flows after changes.
   • Ensure anonymous: ~ is set if you want public access to some routes while others require authentication.

4. Twig Variables

   • The bundle registers Twig globals (e.g., app.user). If these don’t appear, verify:
     • config.yml is imported (imports: [@B4rb4ross4UserBundle/Resources/config/config.yml]).
     • The user_base_view parameter is correctly set.

5. Doctrine Lifecycle Callbacks

   • If using @ORM\PrePersist/@ORM\PostUpdate in the User entity, ensure they don’t conflict with the bundle’s built-in logic. Test with a fresh user record.

Debugging Tips

1. Enable Debug Mode Set APP_DEBUG=true in .env to see detailed errors (e.g., missing routes, entity issues).

2. Check Event Dispatching If events (e.g., UserEvents::REGISTERED) aren’t firing, verify:

   • The subscriber is tagged correctly (if using Symfony’s autowiring).
   • The event name matches exactly (case-sensitive).

3. Database Schema After extending the User entity, run:

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

   to apply new fields.

Extension Points

1. Custom Controllers Override any controller method by extending the base class (e.g., UserController). Example:

   // src/Controller/UserController.php
   use B4rb4ross4\UserBundle\Controller\UserController as BaseController;
   
   class UserController extends BaseController {
       public function showAction(User $user) {
           // Custom logic
           return $this->render('custom/user_show.html.twig', ['user' => $user]);
       }
   }
   

2. Custom Forms Replace the default registration/login forms by:

   • Creating a new template (e.g., templates/user/register.html.twig).
   • Extending the base form type (B4rb4ross4\UserBundle\Form\UserType).

3. API Integration For API-based auth, replace the form login with a custom AuthenticationProvider:

   security:
       firewalls:
           api:
               stateless: true
               anonymous: ~
               provider: api_token
   

   Then create a custom TokenAuthenticator.

4. Email Services Extend the bundle’s email logic by overriding the UserMailer service or creating a decorator:

   services:
       b4rb4ross4.user.mailer.decorated:
           decorates: b4rb4ross4.user.mailer
           arguments: ['@b4rb4ross4.user.mailer.decorated.inner']