Getting Started

Minimal Setup in Laravel

To integrate symfony/security-core into a Laravel project, start by installing the package:

composer require symfony/security-core

First Use Case: Basic Authentication Check

Leverage the AccessDecisionManager to check user permissions in controllers or services:

use Symfony\Component\Security\Core\Authorization\AccessDecisionManager;
use Symfony\Component\Security\Core\Authorization\Voter\RoleVoter;
use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken;
use Symfony\Component\Security\Core\Role\RoleHierarchy;

// Initialize components
$roleHierarchy = new RoleHierarchy(['ROLE_ADMIN' => ['ROLE_USER']]);
$accessDecisionManager = new AccessDecisionManager([
    new RoleVoter($roleHierarchy),
]);

// Simulate a logged-in user
$user = new \App\Models\User(['roles' => ['ROLE_ADMIN']]);
$token = new UsernamePasswordToken($user, 'main', $user->getRoles());

// Check if user has access
if (!$accessDecisionManager->decide($token, ['ROLE_ADMIN'])) {
    abort(403, 'Unauthorized');
}

Key Entry Points

Authentication: Use AuthenticationTrustResolver, TokenStorage, and UserChecker for user validation.
Authorization: Implement AccessDecisionManager with Voter classes (e.g., RoleVoter, AuthenticatedVoter).
User Providers: Extend UserProviderInterface for custom user loading logic.

Implementation Patterns

Workflow: Role-Based Access Control (RBAC)

Define Roles: Use RoleHierarchy to establish role inheritance (e.g., ROLE_ADMIN inherits ROLE_USER).

Create Voters: Extend Voter for custom authorization logic:

use Symfony\Component\Security\Core\Authorization\Voter\Voter;

class CustomVoter extends Voter {
    protected function supports(string $attribute, mixed $subject): bool {
        return $attribute === 'EDIT_POST';
    }

    protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token): bool {
        return $token->getUser()->canEditPost($subject);
    }
}

Integrate with AccessDecisionManager:

$accessDecisionManager = new AccessDecisionManager([
    new RoleVoter($roleHierarchy),
    new CustomVoter(),
]);

Workflow: Token-Based Authentication

Generate Tokens: Use UsernamePasswordToken or AnonymousToken for authentication:

$token = new UsernamePasswordToken($user, 'main', $user->getRoles(), [
    'firewall' => 'admin',
]);

Store Tokens: Use Laravel’s session or a custom TokenStorage implementation:

$tokenStorage = new SessionTokenStorage(new NativeSession());
$tokenStorage->setToken($token);

Check Authentication: Retrieve the token in middleware or services:

$token = $tokenStorage->getToken();
if (!$token || !$token->isAuthenticated()) {
    abort(401);
}

Integration with Laravel Middleware

Create a middleware to wrap Symfony’s security logic:

use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;

class AuthenticateMiddleware {
    public function __construct(private TokenStorageInterface $tokenStorage) {}

    public function handle($request, Closure $next) {
        $token = $this->tokenStorage->getToken();
        if (!$token || !$token->isAuthenticated()) {
            return redirect()->route('login');
        }
        return $next($request);
    }
}

Extending User Providers

Implement UserProviderInterface for custom user loading (e.g., from a database):

use Symfony\Component\Security\Core\User\UserProviderInterface;
use Symfony\Component\Security\Core\User\UserInterface;

class EloquentUserProvider implements UserProviderInterface {
    public function loadUserByIdentifier(string $identifier): UserInterface {
        return User::where('email', $identifier)->firstOrFail();
    }

    public function refreshUser(UserInterface $user): UserInterface {
        return $this->loadUserByIdentifier($user->getUserIdentifier());
    }

    public function supportsClass(string $class): bool {
        return User::class === $class;
    }
}

Gotchas and Tips

Pitfalls

Token Serialization:
- Avoid custom serialization logic for tokens. Use Symfony’s built-in __serialize()/__unserialize() methods.
- Fix: Extend AbstractToken instead of implementing from scratch:
```
class CustomToken extends AbstractToken { ... }
```
Role Hierarchy Caching:
- RoleHierarchy caches role mappings. Clear the cache if roles change dynamically:
```
$roleHierarchy->clearCache();
```
Impersonation Issues:
- Impersonation tokens may break on subsequent requests if not handled properly.
- Fix: Use ImpersonatingToken and ensure the original token is preserved:
```
$impersonatingToken = new ImpersonatingToken($originalToken, $impersonatedUser);
```
Voter Order Matters:
- Voters are evaluated in order. Place stricter checks (e.g., AuthenticatedVoter) before broader ones (e.g., RoleVoter).
- Tip: Use AccessDecisionManager::setDecisionStrategy() to customize the voting strategy (e.g., AffirmativeStrategy for majority approval).
Deprecated Methods:
- Avoid eraseCredentials() (deprecated in Symfony 7.3). Use UserInterface::getRoles() without sensitive data.
- Fix: Store hashed credentials separately if needed.

Debugging Tips

Enable Debugging:
- Set SYMFONY_DEBUG=1 to log voter decisions and token states.
- Example:
```
$accessDecisionManager->setLogger(new \Monolog\Logger('security'));
```
Inspect Tokens:
- Dump token attributes for debugging:
```
dd($token->getRoles(), $token->getAttributes());
```
Role Hierarchy Visualization:
- Use Symfony’s RoleHierarchy dumper to visualize role inheritance:
```
$roleHierarchy->dump();
```

Extension Points

Custom Voters:

Extend Voter for attribute-based authorization (e.g., IS_OWNER):

class OwnerVoter extends Voter {
    protected function supports(string $attribute, mixed $subject): bool {
        return $attribute === 'IS_OWNER';
    }

    protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token): bool {
        return $subject->getUserId() === $token->getUser()->id;
    }
}

Token Attributes:

Attach metadata to tokens for fine-grained access control:

$token = new UsernamePasswordToken($user, 'main', $user->getRoles(), [
    'department' => 'engineering',
]);

Access attributes in voters:

$department = $token->getAttribute('department');

Event Listeners:

Listen to SecurityEvents (e.g., INTERACTIVE_LOGIN) for post-authentication logic:

$dispatcher->addListener(SecurityEvents::INTERACTIVE_LOGIN, function (InteractiveLoginEvent $event) {
    // Log or notify on login
});

Remember-Me Cookies:

Customize RememberMeServices for persistent logins:

$rememberMeServices = new RememberMeServices(
    $tokenStorage,
    new PersistentTokenBasedRememberMeServices(
        $cookieName,
        $tokenStorage,
        new PersistentTokenRepository(),
        new PersistentToken($user->getUserIdentifier(), $secret),
        new \DateTime('+30 days'),
        true // Always remember
    )
);

Laravel-Specific Quirks

Session Integration:
- Symfony’s SessionTokenStorage works with Laravel’s session driver by default. Ensure session configuration matches:
```
'session' => [
    'driver' => 'file', // or 'database', 'redis', etc.
],
```

CSRF Protection:

Symfony’s CsrfTokenManager can conflict with Laravel’s built-in CSRF. Disable one or the other:

// Disable Laravel's CSRF middleware if using Symfony's
$middleware->remove(\App\Http\Middleware\VerifyCsrfToken::class);

User Model Mapping:

Ensure your User model implements UserInterface and maps to Symfony’s expected methods:

class User implements UserInterface {
    public function getRoles(): array { ... }
    public function getPassword(): string { ... }
    public function getUserIdentifier(): string { ... }
}

Security Core Laravel Package