Agency Auth Bundle Laravel Package

Getting Started

1. Verify Compatibility: Ensure your project meets the new requirements:
   • PHP 8.0+ (upgrade via php -v and composer require php:^8.0).
   • Symfony 6.x (check composer.json for symfony/* packages; update via composer update symfony/*).
2. Review Authentication Migration:
   • The package now uses Symfony’s new authentication system (e.g., Symfony\Component\Security\Core\User\UserInterface).
   • Update your user model to implement UserInterface (or extend Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface for password auth).
   • Example:

     use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
     
     class User extends Authenticatable implements PasswordAuthenticatedUserInterface
     {
         // ...
     }
     

3. First Use Case:
   • Test authentication flows (e.g., login, logout) with the updated Auth facade or Symfony’s Security component:

     use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
     use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
     
     // Example authenticator (if using Symfony’s security system)
     public function authenticate(Request $request): Passport
     {
         return new Passport(new UserBadge($request->email));
     }
     

Implementation Patterns

1. Symfony Security Integration:

   • Leverage Symfony’s authenticators, voters, and firewalls for granular control.
   • Example: Create a custom authenticator:

     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
     use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
     use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
     
     class ApiKeyAuthenticator extends AbstractAuthenticator
     {
         public function supports(Request $request): ?bool { /* ... */ }
         public function authenticate(Request $request): Passport { /* ... */ }
         public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewall): ?Response { /* ... */ }
     }
     

   • Register in config/packages/security.yaml:

     firewalls:
         main:
             authenticators: [App\Auth\ApiKeyAuthenticator]
     

2. Password Handling:

   • Use Symfony’s UserPasswordHasherInterface for hashing/verifying passwords:

     use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;
     
     $hasher = app(UserPasswordHasherInterface::class);
     $hashedPassword = $hasher->hashPassword($user, 'plainPassword');
     

3. Laravel Compatibility:

   • If using Laravel’s Auth facade, ensure it’s configured to work with Symfony’s security system (e.g., via Symfony\Bridge\Laravel\HttpFoundation\LaravelRequest).
   • Example middleware:

     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
     
     class AuthMiddleware
     {
         public function __construct(private TokenStorageInterface $tokenStorage) {}
         public function handle(Request $request, Closure $next) { /* ... */ }
     }
     

4. Migration Workflow:

   • Step 1: Update dependencies (composer update).
   • Step 2: Migrate user models to implement UserInterface.
   • Step 3: Replace old auth logic (e.g., Auth::attempt()) with Symfony’s AuthenticationUtils or custom authenticators.
   • Step 4: Test edge cases (e.g., session auth, API tokens).

Gotchas and Tips

1. Breaking Changes:

   • Symfony 6 Authentication: The package no longer uses Laravel’s Auth guard system directly. Custom guards must now implement Symfony’s AuthenticatorInterface or GuardInterface.
   • User Model: Failing to implement UserInterface will cause runtime errors when Symfony’s security system attempts to load the user.
   • Deprecated Classes: Check for removed classes (e.g., Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken → use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge instead).

2. Debugging Tips:

   • Authentication Failures: Enable Symfony’s debug toolbar (APP_DEBUG=true) and check the security.event.authentication_success/authentication_failure events.
   • Token Issues: Use dd($this->tokenStorage->getToken()) to inspect the current token in middleware.
   • Common Pitfalls:
     • Forgetting to call $authenticator->authenticate() in custom authenticators.
     • Not handling onAuthenticationFailure properly (returns a Response or throws an exception).

3. Extension Points:

   • Custom User Providers: Extend Symfony\Component\Security\Core\User\UserProviderInterface for non-database users (e.g., OAuth).
   • Event Listeners: Tap into Symfony’s security events (e.g., security.interactive_login):

     use Symfony\Component\Security\Http\Event\InteractiveLoginEvent;
     
     public function onInteractiveLogin(InteractiveLoginEvent $event) {
         // Log login or update user metadata
     }
     

   • Password Resets: Use Symfony’s PasswordResetTokenManagerInterface for token-based resets.

4. Performance:

   • Symfony’s security system is optimized for high traffic. Ensure your UserProvider uses efficient queries (e.g., where('email', $email)->first()).
   • Cache user lookups if using complex providers (e.g., LDAP).

5. Configuration Quirks:

   • Firewall Order: Symfony’s firewalls are evaluated in order. Place more specific firewalls (e.g., /admin) before generic ones (^/).
   • Anonymous Users: Use Symfony\Component\Security\Core\Authentication\AnonymousToken for unauthenticated requests in custom logic.