In quasi ogni applicazione web arriva il momento in cui la domanda “questo utente è un amministratore?” non basta più. Bisogna rispondere a domande più precise: questo utente può modificare questo articolo? Può vedere una bozza scritta da un collega? Può cancellare un commento dopo che è stato pubblicato? In Symfony lo strumento pensato per questo tipo di decisioni sono i Voter.
In questo articolo vediamo perché i ruoli da soli non bastano, come funziona il sistema di voto, come scrivere e testare un voter, quali strategie di decisione sono disponibili e quali novità sono arrivate con Symfony 7.3, 7.4 e 8.1.
Ruoli e permessi: due livelli diversi
Il primo livello di controllo in Symfony sono i ruoli, stringhe come ROLE_USER o ROLE_ADMIN assegnate all’utente. Si possono usare nel file security.yaml per proteggere intere sezioni dell’applicazione:
# config/packages/security.yaml
security:
role_hierarchy:
ROLE_EDITOR: ROLE_USER
ROLE_ADMIN: ROLE_EDITOR
access_control:
- { path: ^/admin, roles: ROLE_ADMIN }
- { path: ^/redazione, roles: ROLE_EDITOR }
I ruoli rispondono bene a domande del tipo “chi può entrare in quest’area?”. Questo modello si chiama RBAC (Role-Based Access Control). Non sanno però nulla dell’oggetto su cui si sta lavorando. Due redattori hanno lo stesso ruolo, ma di solito ciascuno può modificare solo i propri articoli. Una regola del genere dipende dalla relazione tra utente e risorsa (l’autore, lo stato dell’articolo, la data di pubblicazione) e si avvicina al modello ABAC (Attribute-Based Access Control).
Mettere questi controlli direttamente nei controller funziona finché i casi sono pochi. Poi la stessa regola compare in un controller, in un template Twig, in un comando da console e in un’API, e prima o poi una delle copie viene aggiornata e le altre no. I voter servono a centralizzare queste regole in un unico punto.
Come funziona il sistema di voto
Ogni volta che si chiede a Symfony se un’azione è permessa (con isGranted(), denyAccessUnlessGranted(), l’attributo #[IsGranted] o la funzione Twig is_granted()), l’access decision manager interroga tutti i voter registrati. Ciascuno riceve tre informazioni:
- il token dell’utente autenticato;
- l’attributo, cioè l’azione richiesta (ad esempio
ARTICOLO_EDIT); - il soggetto, cioè l’oggetto su cui si vuole agire (ad esempio un’istanza di
Articolo), che può anche esserenull.
Ogni voter risponde con uno di tre valori, definiti come costanti in VoterInterface:
interface VoterInterface
{
public const ACCESS_GRANTED = 1; // il voter concede l'accesso
public const ACCESS_ABSTAIN = 0; // il voter non si esprime
public const ACCESS_DENIED = -1; // il voter nega l'accesso
public function vote(TokenInterface $token, mixed $subject, array $attributes, ?Vote $vote = null): int;
}
L’astensione è fondamentale: un voter che non sa nulla di articoli deve astenersi, non negare. Sarà poi la strategia di decisione a combinare i voti in un risultato finale.
La classe astratta Voter
Implementare VoterInterface da zero è possibile, ma nella pratica si estende la classe astratta Voter, che richiede solo due metodi:
abstract class Voter implements VoterInterface, CacheableVoterInterface
{
// restituisce false se il voter non deve occuparsi di questo attributo/soggetto
abstract protected function supports(string $attribute, mixed $subject): bool;
// chiamato solo se supports() ha restituito true: true concede, false nega
abstract protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token, ?Vote $vote = null): bool;
}
Il metodo vote() della classe base fa il resto: restituisce ACCESS_ABSTAIN se supports() è falso per tutti gli attributi, ACCESS_GRANTED non appena voteOnAttribute() restituisce true per uno di essi, e ACCESS_DENIED negli altri casi.
Una conseguenza da tenere presente: supports() non riceve il token e voteOnAttribute() restituisce un booleano, quindi un voter che estende Voter non può astenersi in base all’utente. Se serve questo comportamento bisogna implementare direttamente VoterInterface.
Un esempio completo: ArticoloVoter
Supponiamo di avere un’entità Articolo con un autore e uno stato (bozza o pubblicato). Le regole sono queste:
- chiunque può vedere un articolo pubblicato; una bozza la vede solo chi può modificarla;
- l’autore può modificare il proprio articolo; un
ROLE_ADMINpuò modificare qualsiasi articolo; - l’autore può cancellare il proprio articolo solo finché è in bozza; l’amministratore sempre.
Il voter si può generare con php bin/console make:voter (MakerBundle) oppure scrivere a mano:
// src/Security/Voter/ArticoloVoter.php
namespace App\Security\Voter;
use App\Entity\Articolo;
use App\Entity\Utente;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Authorization\AccessDecisionManagerInterface;
use Symfony\Component\Security\Core\Authorization\Voter\Vote;
use Symfony\Component\Security\Core\Authorization\Voter\Voter;
final class ArticoloVoter extends Voter
{
public const VIEW = 'ARTICOLO_VIEW';
public const EDIT = 'ARTICOLO_EDIT';
public const DELETE = 'ARTICOLO_DELETE';
public function __construct(
private readonly AccessDecisionManagerInterface $accessDecisionManager,
) {
}
protected function supports(string $attribute, mixed $subject): bool
{
return \in_array($attribute, [self::VIEW, self::EDIT, self::DELETE], true)
&& $subject instanceof Articolo;
}
protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token, ?Vote $vote = null): bool
{
/** @var Articolo $articolo */
$articolo = $subject;
// Un articolo pubblicato è visibile anche agli utenti anonimi
if (self::VIEW === $attribute && $articolo->isPubblicato()) {
return true;
}
$utente = $token->getUser();
if (!$utente instanceof Utente) {
$vote?->addReason('L\'utente non è autenticato.');
return false;
}
// Gli amministratori possono fare tutto
if ($this->accessDecisionManager->decide($token, ['ROLE_ADMIN'])) {
return true;
}
return match ($attribute) {
self::VIEW, self::EDIT => $this->isAutore($articolo, $utente, $vote),
self::DELETE => $this->puoCancellare($articolo, $utente, $vote),
default => throw new \LogicException('Attributo non gestito: '.$attribute),
};
}
private function isAutore(Articolo $articolo, Utente $utente, ?Vote $vote): bool
{
if ($articolo->getAutore() === $utente) {
return true;
}
$vote?->addReason(sprintf(
'L\'utente %s non è l\'autore dell\'articolo %d.',
$utente->getUserIdentifier(),
$articolo->getId(),
));
return false;
}
private function puoCancellare(Articolo $articolo, Utente $utente, ?Vote $vote): bool
{
if (!$this->isAutore($articolo, $utente, $vote)) {
return false;
}
if ($articolo->isPubblicato()) {
$vote?->addReason('Un articolo pubblicato può essere cancellato solo da un amministratore.');
return false;
}
return true;
}
}
Alcune scelte meritano un commento:
- Costanti per gli attributi. I nomi delle azioni sono stringhe arbitrarie, ma definirle come costanti evita refusi e permette all’IDE di trovare tutti i punti in cui vengono usate. Il prefisso (
ARTICOLO_) evita collisioni con i voter di altre entità. - Il voter nega per default. Ogni ramo che non concede esplicitamente restituisce
false. Ildefaultdelmatchlancia un’eccezione: se arriva un attributo chesupports()ha accettato ma che il voter non gestisce, è un bug da far emergere subito. - Ruoli tramite
AccessDecisionManagerInterface. Per controllare un ruolo dentro un voter la documentazione raccomanda di usare l’access decision manager con il token ricevuto, e nonSecurity::isGranted(). Quest’ultimo potrebbe usare un token diverso da quello su cui si sta votando. Con la configurazione standard diservices.yamlla dipendenza viene iniettata dall’autowiring.
Non serve altro: con l’autoconfigurazione attiva, ogni classe che estende Voter viene registrata automaticamente con il tag security.voter.
Usare il voter
Nei controller
Il modo più dichiarativo è l’attributo #[IsGranted], disponibile da Symfony 6.2. Il secondo argomento è il nome dell’argomento del controller da passare come soggetto:
use App\Entity\Articolo;
use App\Security\Voter\ArticoloVoter;
use Symfony\Component\Security\Http\Attribute\IsGranted;
final class ArticoloController extends AbstractController
{
#[Route('/articoli/{id}', name: 'articolo_show')]
#[IsGranted(ArticoloVoter::VIEW, 'articolo')]
public function show(Articolo $articolo): Response
{
// ...
}
#[Route('/articoli/{id}/modifica', name: 'articolo_edit')]
#[IsGranted(ArticoloVoter::EDIT, 'articolo')]
public function edit(Articolo $articolo): Response
{
// ...
}
}
Quando l’accesso viene negato viene lanciata una AccessDeniedException, che produce una risposta 403. Si possono personalizzare messaggio e codice: ad esempio, per non rivelare l’esistenza di una bozza, si può restituire un 404 con #[IsGranted(ArticoloVoter::VIEW, 'articolo', 'Articolo non trovato', 404)].
In alternativa, dentro il metodo:
$this->denyAccessUnlessGranted(ArticoloVoter::DELETE, $articolo);
Nei template Twig
La stessa regola guida l’interfaccia: il pulsante “Modifica” compare solo a chi può davvero modificare.
{% if is_granted('ARTICOLO_EDIT', articolo) %}
<a href="{{ path('articolo_edit', {id: articolo.id}) }}">Modifica</a>
{% endif %}
Nascondere un pulsante non è una misura di sicurezza: è una scelta di usabilità. Il controllo vero resta nel controller o nel servizio. Il vantaggio dei voter è che entrambi i livelli usano la stessa regola.
Nei servizi
Fuori dai controller si inietta il servizio Security (o AuthorizationCheckerInterface) e si chiama isGranted():
use Symfony\Bundle\SecurityBundle\Security;
final class PubblicazioneService
{
public function __construct(private readonly Security $security) {}
public function pubblica(Articolo $articolo): void
{
if (!$this->security->isGranted(ArticoloVoter::EDIT, $articolo)) {
throw new AccessDeniedException();
}
// ...
}
}
Le strategie di decisione
Quando più voter si esprimono sulla stessa richiesta, è la strategia configurata a combinare i voti. Symfony ne offre quattro:
- affirmative (default): l’accesso è concesso se almeno un voter concede;
- consensus: concesso se i voti favorevoli superano i contrari; in caso di parità decide
allow_if_equal_granted_denied(defaulttrue); - unanimous: concesso solo se nessun voter nega;
- priority: decide il primo voter che non si astiene, in ordine di priorità del servizio.
L’opzione allow_if_all_abstain (default false) stabilisce cosa succede quando tutti si astengono, e vale per ogni strategia. Il default è prudente: se nessuno sa decidere, l’accesso viene negato.
# config/packages/security.yaml
security:
access_decision_manager:
strategy: unanimous
allow_if_all_abstain: false
La scelta va fatta con consapevolezza. Con affirmative basta un voter troppo permissivo, magari aggiunto da un bundle di terze parti, per concedere un accesso che un altro voter negherebbe. unanimous è più restrittiva e si adatta bene ai contesti in cui un singolo “no” deve bloccare tutto (sospensioni, blocchi legali, restrizioni geografiche). Per esigenze particolari si può anche scrivere una strategia personalizzata implementando AccessDecisionStrategyInterface.
Prestazioni: CacheableVoterInterface
I voter vengono interrogati a ogni controllo di accesso. In una pagina con decine di chiamate a is_granted() e molti voter registrati, il costo si sente. La classe Voter implementa già CacheableVoterInterface, ma i suoi due metodi restituiscono sempre true, quindi il voter viene chiamato per qualsiasi attributo e soggetto. Sovrascrivendoli, Symfony può saltare a priori i voter che non c’entrano:
public function supportsAttribute(string $attribute): bool
{
return \in_array($attribute, [self::VIEW, self::EDIT, self::DELETE], true);
}
public function supportsType(string $subjectType): bool
{
// non usare Articolo::class === $subjectType: con Doctrine il tipo può essere un proxy
return is_a($subjectType, Articolo::class, true);
}
Vale anche la regola generale di non eseguire query pesanti dentro voteOnAttribute(): le informazioni necessarie dovrebbero essere già sull’oggetto o caricate in modo efficiente.
Le novità recenti
Symfony 7.3: i voter spiegano le proprie decisioni
Da Symfony 7.3 il metodo voteOnAttribute() riceve un quarto argomento opzionale, l’oggetto Vote. Con $vote?->addReason() il voter può motivare la decisione. Le motivazioni compaiono nei log e nella pagina di errore in sviluppo, e semplificano molto il debug di un “Access Denied” che sembra immotivato. Nell’esempio sopra le abbiamo già usate. L’operatore nullsafe ?-> serve perché l’argomento può essere null.
Symfony 7.4: metadati sui voti
Con Symfony 7.4 l’oggetto Vote ha anche una proprietà extraData, in cui il voter può salvare valori arbitrari. Una strategia personalizzata li può leggere, ad esempio per costruire un sistema a punteggio:
$vote->extraData['punteggio'] = 10;
Symfony 8.1: priorità con #[AsTaggedItem]
Con la strategia priority conta l’ordine in cui i voter vengono interrogati. Da Symfony 8.1 la priorità si può dichiarare direttamente sulla classe, senza ridefinire il tag del servizio:
use Symfony\Component\DependencyInjection\Attribute\AsTaggedItem;
#[AsTaggedItem(priority: 10)]
final class ArticoloVoter extends Voter
{
// ...
}
Testare un voter
Un voter è una normale classe PHP con poche dipendenze, quindi si testa bene con PHPUnit, senza avviare il kernel. Basta costruire un token e chiamare vote():
use PHPUnit\Framework\TestCase;
use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken;
use Symfony\Component\Security\Core\Authorization\AccessDecisionManagerInterface;
use Symfony\Component\Security\Core\Authorization\Voter\VoterInterface;
final class ArticoloVoterTest extends TestCase
{
public function testAutoreNonPuoCancellareArticoloPubblicato(): void
{
$autore = new Utente('mario');
$articolo = (new Articolo())->setAutore($autore)->setPubblicato(true);
$adm = $this->createMock(AccessDecisionManagerInterface::class);
$adm->method('decide')->willReturn(false); // non è admin
$voter = new ArticoloVoter($adm);
$token = new UsernamePasswordToken($autore, 'main', $autore->getRoles());
self::assertSame(
VoterInterface::ACCESS_DENIED,
$voter->vote($token, $articolo, [ArticoloVoter::DELETE]),
);
}
}
Conviene coprire almeno una combinazione per ogni regola: autore e non autore, bozza e pubblicato, utente anonimo, amministratore, e un attributo non supportato, che deve produrre ACCESS_ABSTAIN.
Buone pratiche
- Un voter per risorsa. Un
ArticoloVoter, unCommentoVotere così via. Un unico voter “universale” diventa presto ingestibile. - Astenersi su ciò che non si conosce.
supports()deve essere stretto: tipo di soggetto e attributi esatti. - Negare per default. Concedere solo nei casi esplicitamente previsti.
- Niente logica di presentazione. Il voter decide se un’azione è permessa, non come mostrarla.
- Motivare i dinieghi con
addReason(): chi farà debug tra sei mesi ringrazierà. - Scegliere la strategia in modo esplicito, soprattutto se l’applicazione usa bundle che registrano voter propri.
Conclusione
I voter spostano le regole di autorizzazione fuori dai controller e le raccolgono in classi piccole, testabili e riutilizzabili. Controller, template, servizi e API pongono la stessa domanda (isGranted(azione, oggetto)) e ricevono la stessa risposta. Le novità delle ultime versioni (motivazioni dei voti, metadati, priorità dichiarative) non cambiano il modello, ma lo rendono più facile da osservare e da controllare.
Documentazione ufficiale: How to Use Voters to Check User Permissions.



