User Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require amorebietakoudala/user-bundle
   

   Publish the bundle’s assets and configuration:

   php bin/console amoreu:user:install
   

2. Configuration: Update config/packages/amoreu_user.yaml (auto-generated after installation). Key settings include:

   amoreu_user:
       ldap:
           host: 'your-ldap-server'
           base_dn: 'dc=example,dc=com'
           username_attribute: 'sAMAccountName'
           email_domain: 'example.com'  # For email-based auth
       passport:
           enabled: true  # Required for Symfony 6.3+
   

3. First Use Case:

   • LDAP Authentication: Test LDAP login via /login (uses LoginFormPassportAuthenticator).
   • User Management: Access CRUD via /admin/users (Twig-based UI). Enable pagination with query string params (e.g., ?page=2).

Implementation Patterns

Core Workflows

1. Authentication:

   • LDAP + Passport: Extend LoginFormPassportAuthenticator for custom logic. Override createToken() to inject LDAP-specific claims:

     use AMREU\UserBundle\Security\Passport\LoginFormPassportAuthenticator;
     
     class CustomAuthenticator extends LoginFormPassportAuthenticator {
         protected function createToken(Credentials $credentials, UserProviderInterface $userProvider, string $firewallName): Passport {
             return new Passport(
                 new UserCredentials($credentials->getUsername(), $credentials->getPassword()),
                 new RememberMeToken(), // Optional
                 [
                     new LdapUserAttribute('idNumber', $this->fetchLdapAttribute($credentials->getUsername()))
                 ]
             );
         }
     }
     

   • Email Auth: Configure internet_domain in YAML to allow user@example.com logins.

2. User Management:

   • CRUD: Use the bundled controller (AMREU\UserBundle\Controller\UserController). Extend with custom fields:

     // config/packages/doctrine.yaml
     orm:
         mappings:
             AMREUUserBundle: ~
             App\Entity:  # Add your custom user entity
                 type: attribute
                 dir: '%kernel.project_dir%/src/Entity'
                 prefix: 'App\Entity'
                 alias: App
     

   • Pagination: Leverage built-in logic. Override Twig template (templates/user/index.html.twig) to customize:

     {{ paginate(users, 'app_user_index') }}  {# Uses query string params #}
     

3. Integration with Laravel:

   • Service Providers: Bind the bundle’s services in config/services.yaml:

     services:
         AMREU\UserBundle\:
             resource: '../vendor/amorebietakoudala/user-bundle/src/'
             exclude: '../vendor/amorebietakoudala/user-bundle/src/{Entity,DependencyInjection,Tests}'
     

   • Event Listeners: Subscribe to AMREU\UserBundle\Event\UserEvents (e.g., USER_POST_CREATE) for post-save actions:

     use AMREU\UserBundle\Event\UserEvent;
     
     public function onUserCreated(UserEvent $event) {
         $user = $event->getUser();
         // Sync with Laravel models or external APIs
     }
     

Gotchas and Tips

Pitfalls

1. LDAP Connection Errors:

   • Symptom: Blank page or 500 on /login. Check var/log/dev.log for:

     [LDAP] Could not connect to server: ...
     

   • Fix: Verify host, base_dn, and firewall rules. Use php bin/console debug:config amoreu_user to validate config.

2. Passport Authenticator:

   • Issue: Symfony 6.3+ requires passport.enabled: true. Older versions may fail silently.
   • Debug: Clear cache after enabling:

     php bin/console cache:clear
     

3. Email Authentication:

   • Quirk: internet_domain must match LDAP’s mail attribute exactly (e.g., example.com vs example.com.).
   • Workaround: Use ldap_filter in config to customize:

     ldap:
         filter: '(|(mail=%s)(sAMAccountName=%s))'
     

4. CSRF Token:

   • Gotcha: Badges (e.g., /admin/users) validate CSRF by default. Disable in config/packages/security.yaml if needed:

     firewall:
         main:
             csrf_token_generator: security.csrf.token_manager
     

Debugging Tips

• LDAP Queries: Enable debug mode in amoreu_user.yaml:

  ldap:
      debug: true
  

  Logs queries to var/log/dev.log.

• Route Attributes: Since v2.1.0, routes use attributes (e.g., [Route('/users', name: 'app_user_index')]). Update custom routes accordingly.

• YAML Config: Always validate schema after changes:

  php bin/console debug:config amoreu_user
  

Extension Points

1. Custom User Fields:

   • Extend the User entity (e.g., App\Entity\User) and map to LDAP:

     #[ORM\Attribute]
     class User extends AMREU\UserBundle\Entity\User {
         #[ORM\Column]
         private string $customField;
     
         public function getCustomField(): string {
             return $this->customField;
         }
     }
     

   • Sync with LDAP via a custom UserProvider:

     use AMREU\UserBundle\Security\User\LdapUserProvider;
     
     class CustomLdapUserProvider extends LdapUserProvider {
         public function loadUserByIdentifier(string $identifier): UserInterface {
             $user = parent::loadUserByIdentifier($identifier);
             $user->setCustomField($this->fetchCustomAttribute($identifier));
             return $user;
         }
     }
     

2. Translation Overrides:

   • Override messages in translations/messages.en.yaml:

     'AMREU\UserBundle::user.invalid_credentials': 'Custom error message'
     

3. Badge Customization:

   • Extend the UserBadge class to add columns:

     use AMREU\UserBundle\Badge\UserBadge;
     
     class CustomUserBadge extends UserBadge {
         public function configureColumns(BadgeInterface $badge): void {
             parent::configureColumns($badge);
             $badge->addColumn('customField', 'Custom Field', 'text');
         }
     }
     

   • Register in config/packages/amoreu_user.yaml:

     badge:
         class: App\Badge\CustomUserBadge