Le problème
Reprenons le service order d'une boutique en
ligne, exposé avec API Platform. Un client ne lit que ses
commandes, le service client les lit toutes. Le champ
internalNote, où le service client consigne ses
échanges, ne doit jamais atteindre le client.
Côté REST, une extension Doctrine ajoute
customer = :user à chaque requête d'un client,
et internalNote porte une règle de sécurité de
propriété :
// src/Entity/Order.php (extrait)
#[ORM\Entity]
#[ORM\Table(name: 'orders')]
#[ApiResource(mercure: true)] // la configuration la plus courte
class Order
{
#[ORM\ManyToOne]
#[ORM\JoinColumn(nullable: false)]
private Customer $customer;
#[ORM\Column(type: Types::TEXT, nullable: true)]
#[ApiProperty(security: "is_granted('ROLE_SUPPORT')")]
private ?string $internalNote = null;
// ...
}
Un client qui demande la commande d'un autre reçoit un 404,
et les siennes arrivent sans internalNote. Avec
mercure: true, un écouteur Doctrine d'API
Platform sérialise l'entité après chaque
flush() et la publie sur le hub. Ce chemin ne
passe ni par le provider Doctrine, ni par l'extension.
Trois fuites en découlent.
La mise à jour est publique par défaut.
L'option private vaut false quand
elle n'est pas fixée. Le hub livre alors la commande à tout
abonné dont l'abonnement couvre son topic, quel que soit son
jeton.
« Privé » ne veut pas dire « réservé au
propriétaire ».
Une mise à jour privée part vers chaque jeton qui autorise
l'un de ses topics. Si le jeton de tout client connecté
autorise https://example.com/orders/*, chaque
client reçoit les commandes des autres.
Le contenu dépend de l'auteur, pas du lecteur.
L'écouteur sérialise une seule fois, dans la requête qui a
modifié la commande. La règle de
internalNote est donc évaluée avec les droits
de l'agent du service client. La note part avec la mise à
jour, vers toute son audience.
Un brouillon, un motif d'annulation ou une remarque de modération fuient de la même façon.
Les options
Garder mercure: true, en mode privé
- Ce qu'elle règle : une option suffit, et le hub ne livre plus rien aux jetons qui ne couvrent aucun topic.
- Ce qu'elle coûte : le contenu reste calculé avec les droits de l'auteur, et les topics comme les jetons restent à écrire.
Des topics par client et le contenu complet
- Ce qu'elle règle : chaque client ne reçoit que ses commandes, grâce à un topic alternatif dans son espace.
- Ce qu'elle coûte : un seul contenu pour toutes les audiences. Chaque champ interne doit être retiré à la main, y compris ceux ajoutés plus tard.
Une publication par audience
- Ce qu'elle règle : chaque audience reçoit sa vue, sérialisée avec ses propres groupes, sur un topic qui lui est réservé.
- Ce qu'elle coûte : deux sérialisations et deux topics par modification, et la règle de droits recopiée dans le code de publication.
Un signal, puis une relecture REST
-
Ce qu'elle règle : la mise à jour ne
porte que l'IRI de la commande. Le front la relit par
GET, qui passe par l'extension et par la sécurité des propriétés. - Ce qu'elle coûte : une requête de plus par événement et par abonné, et un affichage en retard d'un aller-retour.
Notre recommandation
Des droits propres au canal temps réel : un signal privé, un topic par audience, un jeton limité à ce que l'utilisateur lit.
Les deux chemins mènent au même navigateur, mais seul le chemin REST passe par l'extension. Nous ne reproduisons pas l'extension dans le hub : nous limitons ce que le hub transporte.
Le topic porte l'audience
Le topic canonique
https://example.com/orders/{id} sert au service
client. Le topic alternatif
https://example.com/customers/{customerId}/orders/{id}
sert au client propriétaire. Le hub livre une mise à jour
privée à tout jeton qui couvre l'un de ses topics :
chaque topic ajouté élargit l'audience.
Le hub, les topics alternatifs et le cookie sont décrits dans notre article sur Mercure sans BFF. Ici, la question est l'autorisation : qui peut écouter quoi.
Le jeton reprend la règle de l'extension
Le jeton d'abonnement se calcule à partir de l'utilisateur, avec la règle de l'extension. Le client écoute son espace, le service client toutes les commandes. Ce calcul ne recopie jamais une liste de topics envoyée par le front, qui pourrait demander ceux d'un autre client.
L'extension et le jeton expriment ainsi la même règle, l'une en SQL, l'autre en motifs d'URL.
Le contenu ne dépend ni de l'auteur ni du lecteur
Une mise à jour est un seul message, livré tel quel à toute
l'audience de ses topics. Elle ne peut contenir que ce que
chacun de ses destinataires a le droit de lire. Le plus sûr
est de n'y mettre que l'IRI :
{"@id": "/orders/{id}"}.
Le front relit alors la commande par REST, avec l'extension, la sécurité des propriétés et les groupes du lecteur. Une commande devenue illisible répond 404, et le front la retire de l'écran.
404 ou 403 : un choix, appliqué partout
La RFC 9110 autorise un 404 à la place d'un 403 pour cacher l'existence d'une ressource interdite. Nous répondons 404 pour la commande d'un autre client : l'extension l'écarte de la requête, le provider ne trouve rien. Nous répondons 403 pour une opération réservée à un rôle, quelle que soit la commande.
L'ordre d'exécution d'API Platform explique ce partage. Une
expression security qui lit
object attend que le provider ait chargé la
commande. Sans extension,
object.getCustomer() == user répondrait 403
pour une commande existante et 404 sinon : la réponse
révélerait son existence.
Depuis API Platform 4.3, une expression qui n'utilise pas
object est évaluée avant la lecture.
is_granted('ROLE_SUPPORT') répond donc 403 sans
interroger la base, que la commande existe ou non.
securityPostDenormalize, évalué après la
désérialisation, contrôle ce qu'une requête écrit, pas ce
qui est diffusé.
Le canal temps réel suit le même choix. Un client abonné au
topic d'une commande d'autrui n'en reçoit aucune mise à jour
privée. Un endpoint qui délivrerait un jeton pour une
commande donnée répondrait 404, comme le GET.
Les compromis assumés
Une relecture par signal et par onglet.
Chaque signal déclenche un GET dans chaque
onglet qui affiche la commande. Si la charge devient
sensible, le front regroupe les signaux rapprochés d'une
même IRI.
Le signal révèle qu'une modification a eu lieu. Son audience est celle du jeton, qui reprend celle de la lecture REST. Un topic alternatif trop large, en revanche, révélerait l'activité des commandes des autres.
Deux règles à tenir alignées. L'extension et le jeton peuvent diverger après une évolution des droits. Un test de sécurité les vérifie ensemble, rôle par rôle.
La publication par audience reste possible. Quand la relecture coûte trop cher, nous publions la vue client et la vue du service client sur deux topics distincts. Les groupes de sérialisation sont alors fixés dans le code de publication, jamais hérités de la requête de l'auteur.
Mise en œuvre
Les exemples utilisent API Platform 5.0, Symfony 7.4,
Doctrine ORM 3, le hub Mercure 1.1 avec
symfony/mercure-bundle 0.6, et Vue 3. La
configuration du hub et du cookie reste celle de
l'article sur Mercure sans BFF.
1. La règle de lecture, dans l'extension
// src/Doctrine/OrderVisibilityExtension.php
namespace App\Doctrine;
use ApiPlatform\Doctrine\Orm\Extension\QueryCollectionExtensionInterface;
use ApiPlatform\Doctrine\Orm\Extension\QueryItemExtensionInterface;
use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
use ApiPlatform\Metadata\Operation;
use App\Entity\Customer;
use App\Entity\Order;
use Doctrine\ORM\QueryBuilder;
use Symfony\Bundle\SecurityBundle\Security;
final readonly class OrderVisibilityExtension implements QueryCollectionExtensionInterface, QueryItemExtensionInterface
{
public function __construct(private Security $security)
{
}
public function applyToCollection(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, ?Operation $operation = null, array $context = []): void
{
$this->restrict($queryBuilder, $queryNameGenerator, $resourceClass);
}
public function applyToItem(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, array $identifiers, ?Operation $operation = null, array $context = []): void
{
$this->restrict($queryBuilder, $queryNameGenerator, $resourceClass);
}
private function restrict(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass): void
{
if (Order::class !== $resourceClass || $this->security->isGranted('ROLE_SUPPORT')) {
return;
}
$customer = $this->security->getUser();
if (!$customer instanceof Customer) {
$queryBuilder->andWhere('1 = 0');
return;
}
$alias = $queryBuilder->getRootAliases()[0];
$parameter = $queryNameGenerator->generateParameterName('customer');
$queryBuilder
->andWhere(\sprintf('%s.customer = :%s', $alias, $parameter))
->setParameter($parameter, $customer);
}
}
L'extension filtre les collections et les éléments, en lecture comme en écriture. L'autoconfiguration de Symfony l'enregistre auprès d'API Platform.
2. Des opérations sans mercure: true
// src/Entity/Order.php (extrait)
#[ApiResource(operations: [
new Get(),
new GetCollection(),
// Sans `object` : évaluée avant la lecture, 403 que la commande existe ou non.
new Patch(security: "is_granted('ROLE_SUPPORT')"),
// Provider personnalisé, voir l'étape 6.
new Get(uriTemplate: '/orders/{id}/timeline', output: OrderTimeline::class, provider: OrderTimelineProvider::class),
])]
class Order
L'attribut mercure disparaît : la
publication devient explicite. Avec des
ressources DTO reliées par stateOptions, l'écouteur d'API Platform ne publie rien : l'entité
n'est pas une ressource.
3. Publier un signal, pas la commande
// src/Live/OrderLiveListener.php
namespace App\Live;
use App\Entity\Order;
use Doctrine\Bundle\DoctrineBundle\Attribute\AsDoctrineListener;
use Doctrine\Bundle\DoctrineBundle\Attribute\AsEntityListener;
use Doctrine\ORM\Events;
use Psr\Log\LoggerInterface;
use Symfony\Component\Mercure\Exception\RuntimeException;
use Symfony\Component\Mercure\HubInterface;
use Symfony\Component\Mercure\Update;
use Symfony\Contracts\Service\ResetInterface;
#[AsEntityListener(event: Events::postPersist, method: 'collect', entity: Order::class)]
#[AsEntityListener(event: Events::postUpdate, method: 'collect', entity: Order::class)]
#[AsDoctrineListener(event: Events::postFlush)]
final class OrderLiveListener implements ResetInterface
{
/** @var array<string, Order> */
private array $changed = [];
public function __construct(
private readonly HubInterface $hub,
private readonly LoggerInterface $logger,
) {
}
public function collect(Order $order): void
{
$this->changed[(string) $order->getId()] = $order;
}
public function postFlush(): void
{
$orders = $this->changed;
$this->reset();
foreach ($orders as $id => $order) {
$update = new Update(
[
// Canonique : l'audience du service client.
'https://example.com/orders/'.$id,
// Alternatif : l'audience du client propriétaire.
'https://example.com/customers/'.$order->getCustomer()->getId().'/orders/'.$id,
],
// Un signal, pas la commande : le front relit GET /orders/{id}.
json_encode(['@id' => '/orders/'.$id], \JSON_THROW_ON_ERROR),
private: true,
type: 'order.changed',
);
try {
$this->hub->publish($update);
} catch (RuntimeException $exception) {
$this->logger->warning('Mercure signal not published.', ['exception' => $exception]);
}
}
}
public function reset(): void
{
$this->changed = [];
}
}
Le jeton de publication du service doit couvrir les deux
topics. postFlush suit le commit, sauf dans une
transaction englobante : l'article sur Mercure sans BFF
traite ce cas.
4. Un jeton qui reprend la règle
// src/Live/LiveGrants.php
namespace App\Live;
use App\Entity\Customer;
use Symfony\Bundle\SecurityBundle\Security;
use Symfony\Component\Mercure\Jwt\Grant;
// Même règle que OrderVisibilityExtension, exprimée en motifs d'URL.
final readonly class LiveGrants
{
public function __construct(private Security $security)
{
}
/** @return list<Grant> */
public function forCurrentUser(): array
{
if ($this->security->isGranted('ROLE_SUPPORT')) {
return [new Grant([Grant::ACTION_SUBSCRIBE], ['urlpattern' => ['https://example.com/orders/:id']])];
}
$customer = $this->security->getUser();
if (!$customer instanceof Customer) {
return [];
}
$space = 'https://example.com/customers/'.$customer->getId();
return [new Grant([Grant::ACTION_SUBSCRIBE], ['urlpattern' => [$space.'/orders/:id']])];
}
}
Le contrôleur qui pose le cookie passe ces grants à
Authorization::setCookie(). Le motif
:id couvre un seul segment : un joker
* couvrirait aussi les topics qu'un autre
service publierait plus tard sous ce préfixe. L'article sur
Mercure sans BFF accorde tout l'espace du client
(/*) : c'est plus simple, mais chaque
nouveau topic y devient lisible d'office.
5. Relire par REST à chaque signal
// fronts/shop/src/composables/useLiveOrders.ts
import { onScopeDispose, ref } from 'vue';
import { fetchOrder, type OrderView } from '@/api/orders';
const HUB_URL = 'https://mercure.example.com/.well-known/mercure';
export function useLiveOrders(customerId: string) {
const orders = ref(new Map<string, OrderView>());
const url = new URL(HUB_URL);
url.searchParams.append(
'match_urlpattern',
`https://example.com/customers/${customerId}/orders/:id`,
);
const source = new EventSource(url, { withCredentials: true });
source.addEventListener('order.changed', async (event) => {
const { '@id': iri } = JSON.parse(event.data) as { '@id': string };
// La relecture passe par l'extension et par la sécurité des propriétés.
const order = await fetchOrder(iri); // null sur un 404
if (order === null) {
orders.value.delete(iri);
} else {
orders.value.set(iri, order);
}
});
onScopeDispose(() => source.close());
return { orders };
}
Avec TanStack Query, le signal invalide la clé de la commande, comme dans un composable par endpoint.
6. Un provider personnalisé passe par le provider Doctrine
Une extension ne s'applique qu'aux providers Doctrine d'API Platform. Un provider personnalisé qui lit avec le repository la contourne, comme l'écouteur Mercure. Il délègue donc la lecture au provider Doctrine :
// src/State/OrderTimelineProvider.php
namespace App\State;
use ApiPlatform\Doctrine\Orm\State\ItemProvider;
use ApiPlatform\Metadata\Operation;
use ApiPlatform\State\ProviderInterface;
use App\ApiResource\OrderTimeline;
use App\Entity\Order;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
/** @implements ProviderInterface<OrderTimeline> */
final readonly class OrderTimelineProvider implements ProviderInterface
{
public function __construct(
// Le provider Doctrine d'API Platform applique OrderVisibilityExtension.
#[Autowire(service: ItemProvider::class)]
private ProviderInterface $itemProvider,
) {
}
public function provide(Operation $operation, array $uriVariables = [], array $context = []): ?OrderTimeline
{
$order = $this->itemProvider->provide($operation, $uriVariables, $context);
// null : commande absente ou hors de portée, API Platform répond 404.
return $order instanceof Order ? new OrderTimeline($order->getId(), $order->getStatusChanges()) : null;
}
}
Checklist
-
Aucune ressource publiée sur Mercure sans
private: true. - Des topics alternatifs qui portent l'audience, un espace par client.
- Un jeton d'abonnement calculé à partir de l'utilisateur, avec la règle de l'extension.
-
Des motifs d'URL étroits (
:id), sans joker sur un préfixe partagé. - Un contenu réduit à l'IRI, ou une sérialisation par audience aux groupes fixés dans le code.
- Un test qui publie une modification du service client et vérifie qu'aucun champ interne n'en sort.
- Un front qui relit par REST à chaque signal et retire ce qui répond 404.
-
404 pour une ressource hors de portée, 403 pour une
opération réservée à un rôle, sans
object. - Des providers personnalisés qui délèguent au provider Doctrine.
Sources
-
API Platform,
Mercure : attribut
mercure, optionsprivate,topicsetnormalization_context. -
API Platform,
code de PublishMercureUpdatesListener : publication au
postFlush,privateàfalsepar défaut. - API Platform, code de AbstractItemNormalizer et de ResourceAccessChecker : sécurité des propriétés évaluée avec l'utilisateur courant.
- API Platform, Extensions : interfaces des extensions, providers personnalisés.
-
API Platform,
Security avec Symfony :
security,securityPostDenormalize, sécurité des propriétés. -
API Platform,
CHANGELOG, version 4.3.0 (13 mars 2026) :
securityévalué avant le provider quand l'expression n'utilise pasobject. - API Platform, notes de version 5.0.0 (17 septembre 2026).
-
Mercure,
Authorization : mises à jour privées, autorisation par
utilisateur,
anonymous. - Mercure, Topics and matchers : topics canoniques et alternatifs, URL Patterns.
- IETF, The Mercure Protocol (draft-dunglas-mercure-08, 11 août 2026) : audience d'une mise à jour privée.
- Mercure, notes de version 1.0.0 (16 septembre 2026) et 1.1.0 (8 octobre 2026).
-
Symfony, changelogs du
composant Mercure
(0.8, classe
Grant) et du MercureBundle (0.6). - IETF, RFC 9110, section 15.5.4 : un 404 pour cacher l'existence d'une ressource interdite.
- Lychen, pull request 255 : une mise en œuvre open source des droits de lecture et du contenu publié décrits ici, dans un monorepo moon.
- Lychen, pull request 242 : une mise en œuvre open source des jetons d'abonnement par motifs d'URL.
- Lychen, pull request 237 : une mise en œuvre open source d'un provider qui passe par l'extension Doctrine.