Common Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alexhenriet/common-bundle
   

   Ensure config/packages/alexhenriet_common.yaml exists before requiring the package to avoid errors:

   common:
       ldap_host: 'ldap-host.lan'
       login_prefix: 'DOMAIN'
   

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

   Alexhenriet\Bundle\CommonBundle\CommonBundle::class => ['all' => true],
   

3. First Use Case: Replace your default authenticator in config/packages/security.yaml:

   security:
       enable_authenticator_manager: true
       firewalls:
           main:
               custom_authenticators:
                   - Alexhenriet\Bundle\CommonBundle\Security\BypassableLdapLoginFormAuthenticator
   

Implementation Patterns

LDAP Authentication Workflow

1. Configuration: Extend alexhenriet_common.yaml with LDAP-specific settings:

   common:
       ldap_host: 'ldap.example.com'
       ldap_port: 389
       bypass_user_identifiers: ['admin', 'dev']
       bypass_environments: ['dev', 'test']
   

2. Login Form: Use _username and _password as input names in templates/security/login.html.twig:

   <form method="post">
       <input type="text" name="_username" />
       <input type="password" name="_password" />
       <button type="submit">Login</button>
   </form>
   

3. Bypass Logic: Users in bypass_user_identifiers or environments in bypass_environments skip LDAP checks.

Abstract Controller Usage

1. Extend Base Controller:

   use Alexhenriet\Bundle\CommonBundle\Controller\AbstractController;
   
   class UserController extends AbstractController {
       public function index(): Response {
           return $this->render('user/index.html.twig');
       }
   }
   

2. Service Injection: Add to config/services.yaml to resolve private controllers:

   App\Controller\:
       resource: '../src/Controller/'
       tags: ['controller.service_arguments']
   

3. Dependency Injection: Leverage Symfony’s built-in DI for services (e.g., Security, Twig).

Integration Tips

• Environment-Specific Configs: Override alexhenriet_common.yaml per environment (e.g., config/packages/dev/alexhenriet_common.yaml).
• Custom Auth Logic: Extend BypassableLdapLoginFormAuthenticator for additional validation:

   class CustomAuthenticator extends BypassableLdapLoginFormAuthenticator {
       protected function getUser($username, $password) {
           // Custom logic
       }
   }
  

• Twig Extensions: Use the bundle’s abstract controller to access helpers like $this->getUser().

Gotchas and Tips

Pitfalls

1. Configuration Order:

   • Error: ConfigException if alexhenriet_common.yaml is missing during composer require.
   • Fix: Create the file before installation.

2. LDAP Dependencies:

   • Error: Class 'LDAP' not found if ext-ldap is missing.
   • Fix: Enable PHP LDAP extension (sudo apt install php-ldap on Ubuntu).

3. Controller Visibility:

   • Error: Controller ... cannot be fetched from the container if services.yaml lacks the resource tag.
   • Fix: Add the App\Controller\ service configuration (see above).

4. Bypass Logic:

   • Gotcha: bypass_user_identifiers uses exact matches (case-sensitive).
   • Tip: Use lowercase usernames or normalize in config.

Debugging

• LDAP Connection Issues: Check logs (var/log/dev.log) for LDAP errors. Test connectivity with:

  ldapsearch -x -H ldap://ldap-host.lan -b "dc=example,dc=com"
  

• Authenticator Debugging: Enable Symfony’s debug toolbar to inspect authenticator events.

Extension Points

1. Custom Authenticators: Override BypassableLdapLoginFormAuthenticator to add:

   • Multi-factor auth.
   • Role-based bypass rules.

2. Abstract Controller: Extend AbstractController to add shared methods:

   class BaseController extends AbstractController {
       protected function requireRole(string $role): void {
           $this->denyAccessUnlessGranted($role, null);
       }
   }
   

3. Configuration: Add new keys to alexhenriet_common.yaml and extend the bundle’s CommonExtension class to load them.

Tips

• Environment Awareness: Use %kernel.environment% in configs to dynamically set bypass_environments.
• Testing: Mock LDAP calls in PHPUnit with LDAPMock or disable LDAP checks in tests:

  # config/packages/test/alexhenriet_common.yaml
  common:
      ldap_host: null  # Disable LDAP in tests