Login Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dayspring-tech/login-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Dayspring\LoginBundle\DayspringLoginBundle::class => ['all' => true],
   ];
   

2. Configure security.yml Copy the provided security.yml snippet into your config, replacing placeholders with your actual:

   • User provider class (e.g., App\Entity\User).
   • Target paths (e.g., default_target_path).
   • Adjust firewalls to match your routing.

3. First Use Case: Basic Login

   • Create a login form in Twig:

     {{ form_start(form) }}
         {{ form_widget(form._username) }}
         {{ form_widget(form._password) }}
         <button type="submit">Login</button>
     {{ form_end(form) }}
     

   • Route the form to _login_check (default path: /login_check).

4. Verify Routes Run:

   php bin/console debug:router | grep login
   

   Ensure _login, _login_check, _logout, and _forgot_password routes exist.

Implementation Patterns

Workflows

1. User Authentication Flow

   • Login: Submit form to _login_check (POST). Bundle handles validation and authentication.
   • Logout: Redirect to _logout (GET/POST). Bundle clears session and redirects to target.
   • Password Reset:
     • User submits email to _forgot_password (POST).
     • Bundle sends reset link via dayspring_login.mailer (customizable).
     • User clicks link, submits new password to _reset_password (POST).

2. Custom User Model Extend the default user provider by implementing Dayspring\LoginBundle\Provider\UserProviderInterface:

   // src/Service/CustomUserProvider.php
   class CustomUserProvider implements UserProviderInterface {
       public function loadUserByUsername($username) {
           return $this->entityManager->getRepository(User::class)->findOneBy(['email' => $username]);
       }
   }
   

   Register as a service in services.yaml:

   services:
       dayspring_login.user_provider:
           class: App\Service\CustomUserProvider
   

3. Password Change

   • Use the _change_password route (POST) with a form:

     {{ form_start(form) }}
         {{ form_widget(form.currentPassword) }}
         {{ form_widget(form.newPassword) }}
         {{ form_widget(form.confirmPassword) }}
     {{ form_end(form) }}
     

   • Bundle validates current password and updates the hash.

Integration Tips

• Twig Extensions: Use dayspring_login Twig functions for user checks:

  {% if app.user %}
      Welcome, {{ app.user.username }}!
  {% endif %}
  

• Event Listeners: Subscribe to dayspring_login.security.event for custom logic (e.g., post-login redirects):

  // src/EventListener/CustomLoginListener.php
  class CustomLoginListener {
      public function onLoginSuccess(LoginSuccessEvent $event) {
          if ($event->getUser()->isAdmin()) {
              $event->setTargetPath('/admin');
          }
      }
  }
  

  Register in services.yaml:

  services:
      App\EventListener\CustomLoginListener:
          tags:
              - { name: kernel.event_listener, event: dayspring_login.security.login_success, method: onLoginSuccess }
  

Gotchas and Tips

Pitfalls

1. Routing Conflicts

   • Ensure _login_check and _forgot_password routes don’t clash with existing routes. Use _ prefix to avoid conflicts with Symfony’s profiler routes.
   • Fix: Explicitly define routes in config/routes.yaml:

     _login:
         path: /login
         controller: Dayspring\LoginBundle\Controller\SecurityController::login
     

2. User Provider Mismatch

   • If loadUserByUsername returns null, the bundle throws a UsernameNotFoundException.
   • Debug: Verify your provider’s loadUserByUsername logic matches your user entity’s unique field (e.g., email vs. username).

3. Password Hashing

   • The bundle defaults to bcrypt with cost 12. For legacy systems, adjust password_hashers in security.yml:

     password_hashers:
         App\Entity\User:
             algorithm: auto  # Auto-detects existing hashes
     

4. Email Templates

   • Forgot/reset emails use Twig templates in templates/DayspringLoginBundle/Mail/. Override them by copying to templates/your_bundle/Mail/ and extending the base template:

     {# templates/App/Mail/reset_password.html.twig #}
     {% extends 'DayspringLoginBundle:Mail:reset_password.html.twig' %}
     {% block subject %}{{ 'Custom Reset Subject'|trans }}{% endblock %}
     

Debugging

• Enable Debug Mode: Add debug: true to security.yml to log authentication attempts:

  security:
      debug: true
  

• Check Events: Use bin/console debug:event-dispatcher to verify listeners are registered for:
  • dayspring_login.security.login_success
  • dayspring_login.security.login_failure
  • dayspring_login.mailer.reset_sent

Extension Points

1. Custom Mailer Override the default mailer service:

   services:
       dayspring_login.mailer:
           class: App\Service\CustomMailer
           arguments:
               $transport: '@mailer.transport.dsn'
   

   Implement Dayspring\LoginBundle\Mailer\MailerInterface.

2. User Checker Extend Dayspring\LoginBundle\Security\UserChecker to add custom checks (e.g., account expiration):

   class CustomUserChecker extends UserChecker {
       public function checkPreAuth(UserInterface $user) {
           if ($user->isSuspended()) {
               throw new AccountStatusException('Account suspended.');
           }
       }
   }
   

   Register in services.yaml:

   services:
       dayspring_login.user_checker:
           class: App\Security\CustomUserChecker
   

3. Form Customization Extend the default login form by overriding the template:

   {# templates/App/Security/login.html.twig #}
   {% extends 'DayspringLoginBundle:Security:login.html.twig' %}
   {% block form_fields %}
       {{ form_row(form.remember_me) }}
       {{ parent() }}
   {% endblock %}
   

4. Propel Inheritance For UserProfile models, ensure Propel schema is updated:

   <behavior name="propel">
       <parameter name="model" value="UserProfile" />
       <parameter name="parent" value="User" />
   </behavior>
   

   Regenerate models:

   php bin/console propel:build --all