Security Auth Form Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies Ensure dcs/security-core-bundle is installed first:

   composer require dcs/security-core-bundle "~1.0@dev"
   

   Then install the auth form bundle:

   composer require dcs/security-auth-form-bundle "~1.0@dev"
   

2. Enable the Bundle Add to app/AppKernel.php:

   new DCS\Security\Auth\FormBundle\DCSSecurityAuthFormBundle(),
   

3. Configure security.yml Add the dcs_form firewall to your existing security config:

   firewalls:
       dcs_form:
           pattern: ^/login
           form_login:
               provider: dcs_security.core.authentication.provider
               login_path: /login
               check_path: /login_check
               default_target_path: /
   

4. First Use Case Create a basic login template at templates/security/login.html.twig:

   {% extends 'base.html.twig' %}
   {% block body %}
       {{ form_start(form) }}
           {{ form_row(form._username) }}
           {{ form_row(form._password) }}
           <button type="submit">Login</button>
       {{ form_end(form) }}
   {% endblock %}
   

Implementation Patterns

Workflows

1. Login Flow

   • Route /login renders the form.
   • POST to /login_check triggers authentication via dcs_security.core.authentication.provider.
   • Redirects to default_target_path (e.g., /) on success.

2. Custom Authentication Logic Extend the provider by overriding the DCS\Security\Core\Authentication\Provider\AuthenticationProviderInterface service:

   # config/services.yml
   services:
       app.custom_auth_provider:
           class: AppBundle\Security\CustomAuthProvider
           arguments: ['@dcs_security.core.authentication.provider']
           tags:
               - { name: 'dcs_security.authentication.provider', priority: 100 }
   

3. Form Customization Override the default form theme or type:

   {% form_theme form _self %}
   

   Or extend the form class:

   // src/AppBundle/Form/LoginType.php
   namespace AppBundle\Form;
   use DCS\Security\Auth\Form\LoginType as BaseLoginType;
   
   class LoginType extends BaseLoginType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           parent::buildForm($builder, $options);
           $builder->add('remember_me', CheckboxType::class, ['required' => false]);
       }
   }
   

4. CSRF Protection Ensure the form includes the CSRF token (handled automatically by Symfony’s form_start).

Integration Tips

• Symfony 5+ Flex Compatibility If using Symfony Flex, manually register the bundle in config/bundles.php:

  return [
      // ...
      DCS\Security\Auth\FormBundle\DCSSecurityAuthFormBundle::class => ['all' => true],
  ];
  

• Event Listeners Listen to security.authentication.success to customize post-login behavior:

  // src/AppBundle/EventListener/LoginListener.php
  namespace AppBundle\EventListener;
  use Symfony\Component\Security\Http\Event\InteractiveLoginEvent;
  
  class LoginListener {
      public function onLogin(InteractiveLoginEvent $event) {
          // Custom logic (e.g., log activity, set flash messages)
      }
  }
  

  Register in services.yml:

  services:
      AppBundle\EventListener\LoginListener:
          tags:
              - { name: 'kernel.event_listener', event: 'security.authentication.success', method: 'onLogin' }
  

Gotchas and Tips

Pitfalls

1. Missing Core Bundle

   • Error: ServiceNotFoundException for dcs_security.core.authentication.provider.
   • Fix: Ensure dcs/security-core-bundle is installed and enabled.

2. Firewall Misconfiguration

   • Error: Login route (/login) not recognized.
   • Fix: Verify security.yml includes the dcs_form firewall with correct pattern and form_login settings.

3. Form Type Overrides

   • Error: Custom form fields not appearing.
   • Fix: Ensure the extended form type is properly tagged or autowired:

     tags:
         - { name: 'form.type', alias: 'app_login' }
     

4. CSRF Token Issues

   • Error: "CSRF token not found" on form submission.
   • Fix: Use form_start(form) in Twig (includes CSRF token automatically).

Debugging

• Check Authentication Provider Dump the provider service to verify it’s loaded:

  php bin/console debug:container dcs_security.core.authentication.provider
  

• Symfony Debug Toolbar Use the Security panel to inspect:

  • Authenticated user.
  • Firewall configuration.
  • Authentication attempts.

Extension Points

1. Custom Authentication Providers Implement AuthenticationProviderInterface and prioritize via YAML tags:

   tags:
       - { name: 'dcs_security.authentication.provider', priority: 200 }
   

2. Form Events Subscribe to DCS\Security\Auth\Form\Event\LoginFormEvent for pre-submission logic:

   use DCS\Security\Auth\Form\Event\LoginFormEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class LoginFormSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               LoginFormEvent::PRE_SUBMIT => 'onPreSubmit',
           ];
       }
       public function onPreSubmit(LoginFormEvent $event) {
           // Modify form data (e.g., sanitize input)
       }
   }
   

3. Template Overrides Override the default login template by placing a file at:

   templates/DCSecurityAuthForm/login.html.twig
   

Configuration Quirks

• Default Target Path If default_target_path is not set, users may loop back to /login after login. Fix: Explicitly define it in security.yml:

  default_target_path: /dashboard
  

• Remember-Me Feature Enable via remember_me in form_login:

  form_login:
      remember_me: true
  

  Ensure the security.firewalls.dcs_form.remember_me config is set in security.yml:

  remember_me:
      secret: '%kernel.secret%'  # Symfony 4.1+
      lifetime: 86400           # 1 day
      path: /                   # Path to check for remember-me cookie