Symfony Mercure Component

https://github.com/symfony/mercure
Admin
A Symfony component implementing the publisher part of the Mercure protocol for pushing real-time...
Tokens:86,491
Snippets:587
Trust Score:9.5
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Basic publishing setup with LcobucciFactory

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Jwt/LcobucciFactory.md

Shows the README-style publishing setup: create a JWT factory with the Mercure hub secret, build a token provider with a publish grant, connect to the hub, and publish an update.

```php
use Symfony\Component\Mercure\Hub;
use Symfony\Component\Mercure\Jwt\FactoryTokenProvider;
use Symfony\Component\Mercure\Jwt\Grant;
use Symfony\Component\Mercure\Jwt\LcobucciFactory;
use Symfony\Component\Mercure\Update;

$jwtFactory = new LcobucciFactory('!ChangeThisMercureHubJWTSecretKey!');
$provider = new FactoryTokenProvider(
    $jwtFactory,
    [new Grant([Grant::ACTION_PUBLISH], ['*'])],
);
$hub = new Hub('https://demo.mercure.rocks/.well-known/mercure', $provider);

$hub->publish(new Update('https://example.com/books/1.jsonld', 'Hi from Symfony!'));
```

--------------------------------

### Examples

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Authorization.md

Usage examples for the Authorization class: setting a cookie, clearing a cookie, error handling, and manual cookie handling.

```APIDOC
## Examples

### Basic - Grant access to private topics

```php
use Symfony\Component\Mercure\Authorization;
use Symfony\Component\Mercure\Jwt\Grant;
use Symfony\Component\Mercure\Jwt\LcobucciFactory;
use Symfony\Component\Mercure\Jwt\FactoryTokenProvider;
use Symfony\Component\Mercure\Hub;
use Symfony\Component\Mercure\HubRegistry;
use Symfony\Component\HttpFoundation\Request;

$factory = new LcobucciFactory('secret');
$hub = new Hub('https://hub.example.com/.well-known/mercure', new FactoryTokenProvider($factory), jwtFactory: $factory);
$authorization = new Authorization(new HubRegistry($hub));

$request = Request::create('https://example.com/books/1');
$authorization->setCookie(
    $request,
    [new Grant([Grant::ACTION_SUBSCRIBE], ['https://example.com/books/{id}'], null)],
    additionalClaims: ['iss' => 'https://example.com', 'aud' => 'mercure', 'sub' => 'anonymous', 'client_id' => 'web'],
);

// $request->attributes->get('_mercure_authorization_cookies') now holds the Cookie;
// SetCookieSubscriber attaches it to the response on kernel.response.
```

### Logging out - Clear the cookie

```php
$authorization->clearCookie($request); // or createClearCookie() if you want to attach manually
```

### Error handling - Protocol-1.0 hub over plain HTTP

```php
use Symfony\Component\Mercure\Exception\InvalidArgumentException;

$httpHub = new Hub('http://hub.example.com/.well-known/mercure', $provider, jwtFactory: $factory);
$auth = new Authorization(new HubRegistry($httpHub));

try {
    $auth->setCookie($request, ['https://example.com/books/1']);
} catch (InvalidArgumentException $e) {
    // The "__Secure-mercure_access_token" cookie name requires a hub public URL
    // served over HTTPS; configure a prefix-less cookie name on the hub...
}
// Fix: pass cookieName: 'mercure_access_token' to the Hub constructor, or serve
// the hub public URL over HTTPS.
```

### Manual cookie handling with request-domain matching

```php
$cookie = $authorization->createCookie($request, ['https://example.com/topic'], hub: 'events');
$response->headers->setCookie($cookie);
```
```

--------------------------------

### TraceableHub Usage Examples

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Debug/TraceableHub.md

Code examples demonstrating the usage of the TraceableHub class, including publishing updates, inspecting trace data, resetting, and handling exceptions for unsupported methods.

```APIDOC
## TraceableHub::publish

### Description
Publishes an update through the decorated hub and records trace information (duration, memory) for the operation.

### Method
publish

### Parameters
- **update** (Update) - Required - The update to publish.

### Return Value
- **string** - The ID of the published update.

### Example
```php
$traceable->publish(new \Symfony\Component\Mercure\Update('/books/1', '{}'));
```
```

```APIDOC
## TraceableHub::count

### Description
Returns the number of operations (e.g., publish calls) that have been traced since the last reset.

### Method
count

### Parameters
None

### Return Value
- **int** - The number of traced operations.

### Example
```php
$count = $traceable->count(); // 1
```
```

```APIDOC
## TraceableHub::getDuration

### Description
Returns the total duration in milliseconds of all traced operations since the last reset.

### Method
getDuration

### Parameters
None

### Return Value
- **float** - The total duration in milliseconds.

### Example
```php
$duration = $traceable->getDuration(); // e.g. 34.2
```
```

```APIDOC
## TraceableHub::getMemory

### Description
Returns the total memory usage in bytes of all traced operations since the last reset.

### Method
getMemory

### Parameters
None

### Return Value
- **int** - The total memory usage in bytes.

### Example
```php
$memory = $traceable->getMemory(); // e.g. 12288
```
```

```APIDOC
## TraceableHub::getMessages

### Description
Returns an array of trace messages, each containing the published Update object, its duration, and memory usage.

### Method
getMessages

### Parameters
None

### Return Value
- **array** - An array of trace messages, each with keys 'object', 'duration', and 'memory'.

### Example
```php
$messages = $traceable->getMessages(); // [['object' => Update, 'duration' => ..., 'memory' => ...]]
```
```

```APIDOC
## TraceableHub::reset

### Description
Resets the trace data (count, duration, memory, messages) to zero, typically between profiler collections.

### Method
reset

### Parameters
None

### Return Value
- **void** - No return value.

### Example
```php
$traceable->reset();
echo $traceable->count(); // 0
```
```

```APIDOC
## TraceableHub::getUrl

### Description
Returns the URL of the hub. This method throws a RuntimeException if the decorated hub does not implement RemoteHubInterface.

### Method
getUrl

### Parameters
None

### Return Value
- **string** - The hub URL.

### Exceptions
- **RuntimeException** - Thrown when the decorated hub does not implement RemoteHubInterface.

### Example
```php
try {
    $traceable->getUrl();
} catch (\RuntimeException $e) {
    // The getUrl() method is not implemented by the decorated hub.
}
```
```

--------------------------------

### Example: Using CachedTokenProvider with a Hub

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Jwt/TokenProviderInterface.md

Shows how to instantiate a Hub with the CachedTokenProvider and publish an update. The provider is passed as the second argument to the Hub constructor.

```php
use Symfony\Component\Mercure\Hub;

$hub = new Hub('https://hub.example.com/.well-known/mercure', new CachedTokenProvider(...));
$hub->publish(new \Symfony\Component\Mercure\Update('/books/1', '{}'));
```

--------------------------------

### Typical wiring with Authorization and Discovery

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/HubRegistry.md

Typical wiring example showing how Authorization and Discovery resolve hubs through the registry, and how a ?hub= query parameter flows through getHub().

```php
$authorization = new Authorization($registry);          // see Authorization.md
$discovery     = new Discovery($registry);              // see Discovery.md
$hub = $registry->getHub($request->query->get('hub'));  // null → default
```

--------------------------------

### Install and publish an update to a Mercure hub

Source: https://github.com/symfony/mercure/blob/main/README.md

Install the Mercure component and the Lcobucci JWT library, then configure a hub with a JWT token provider and publish an update. Set the HUB_URL and JWT_SECRET constants to your Mercure hub's address and secret. Use StaticTokenProvider if you already have a JWT token instead of the FactoryTokenProvider with LcobucciFactory.

```bash
composer require symfony/mercure lcobucci/jwt
```

```php
const HUB_URL = 'https://demo.mercure.rocks/.well-known/mercure';
const JWT_SECRET = '!ChangeThisMercureHubJWTSecretKey!';

// Set up the JWT token provider
// Alternatively, you can use the \Symfony\Component\Mercure\Jwt\StaticTokenProvider if you already have a JWT token
$jwFactory = new \Symfony\Component\Mercure\Jwt\LcobucciFactory(JWT_SECRET);
$provider = new \Symfony\Component\Mercure\Jwt\FactoryTokenProvider($jwFactory, publish: ['*']);

$hub = new \Symfony\Component\Mercure\Hub(HUB_URL, $provider);
// Serialize the update, and dispatch it to the hub, that will broadcast it to the clients
$id = $hub->publish(new \Symfony\Component\Mercure\Update('https://example.com/books/1.jsonld', 'Hi from Symfony!'));
```

--------------------------------

### Basic HubRegistry usage

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/HubRegistry.md

Basic usage example showing how to create a HubRegistry with a default hub and a named hub, then retrieve hubs by name or default.

```php
use Symfony\Component\Mercure\Hub;
use Symfony\Component\Mercure\HubRegistry;

$default = new Hub('https://hub.example.com/.well-known/mercure', $provider);
$events  = new Hub('https://events.example.com/.well-known/mercure', $provider);

$registry = new HubRegistry($default, ['events' => $events]);

$registry->getHub();            // $default
$registry->getHub('events');    // $events
$registry->all();               // ['events' => $events]
```

--------------------------------

### Basic usage with Hub::publish()

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Jwt/FactoryTokenProvider.md

The README setup: creates a FactoryTokenProvider with a publish grant for all topics, then uses it with a Hub to publish an update. Requires the LcobucciFactory and a JWT secret.

```php
use Symfony\Component\Mercure\Hub;
use Symfony\Component\Mercure\Jwt\FactoryTokenProvider;
use Symfony\Component\Mercure\Jwt\Grant;
use Symfony\Component\Mercure\Jwt\LcobucciFactory;
use Symfony\Component\Mercure\Update;

const HUB_URL = 'https://demo.mercure.rocks/.well-known/mercure';
const JWT_SECRET = '!ChangeThisMercureHubJWTSecretKey!';

$jwtFactory = new LcobucciFactory(JWT_SECRET);
$provider = new FactoryTokenProvider($jwtFactory, [new Grant([Grant::ACTION_PUBLISH], ['*'])]);

$hub = new Hub(HUB_URL, $provider);
$hub->publish(new Update('https://example.com/books/1.jsonld', 'Hi from Symfony!'));
```

--------------------------------

### Multi-hub setup with a custom client and explicit cookie name

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Hub.md

Demonstrates creating multiple Hub instances with custom HTTP clients and protocol versions, and registering them in a HubRegistry.

```APIDOC
## Hub constructor and HubRegistry

### Description
Creates Hub instances with custom configuration and registers them in a HubRegistry for multi-hub support.

### Method
__construct (Hub) and HubRegistry::__construct

### Parameters
#### Hub::__construct
- **string $hubUrl** (string) - Required - The hub URL.
- **TokenProviderInterface $tokenProvider** (TokenProviderInterface) - Required - The token provider.
- **string $publicUrl** (string) - Optional - The public URL of the hub.
- **HttpClientInterface $httpClient** (HttpClientInterface) - Optional - The HTTP client to use.
- **string $protocolVersion** (string) - Optional - The protocol version (e.g., ProtocolVersion::V1 or ProtocolVersion::Legacy).

#### HubRegistry::__construct
- **Hub $defaultHub** (Hub) - Required - The default hub.
- **array $hubs** (array) - Optional - An associative array of named hubs.

### Request Example
```php
use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\Mercure\Hub;
use Symfony\Component\Mercure\HubRegistry;
use Symfony\Component\Mercure\Jwt\StaticTokenProvider;
use Symfony\Component\Mercure\ProtocolVersion;

$tokenProvider = new StaticTokenProvider('eyJ...');

$default = new Hub(
    'http://internal-mercure/.well-known/mercure',
    $tokenProvider,
    publicUrl: 'https://mercure.example.com/.well-known/mercure',
    httpClient: HttpClient::create(['timeout' => 2.0]),
    protocolVersion: ProtocolVersion::V1,
);
$legacy = new Hub('http://legacy-mercure/.well-known/mercure', $tokenProvider, protocolVersion: ProtocolVersion::Legacy);

$registry = new HubRegistry($default, ['legacy' => $legacy]);
```

### Response
No return value for constructors.
```

--------------------------------

### FactoryTokenProvider

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Jwt/FactoryTokenProvider.md

Documentation for the FactoryTokenProvider class, including its constructor, getJwt method, and usage examples.

```APIDOC
## FactoryTokenProvider

### Description
`FactoryTokenProvider` is a `TokenProviderInterface` that mints a fresh JWT on every `getJwt()` call by delegating to a `TokenFactoryInterface` with fixed grants and additional claims. This is the provider used in the README's "getting started" setup. Marked `@experimental`.

### Class Definition
```php
final class FactoryTokenProvider implements TokenProviderInterface
{
    /**
     * @param Grant[] $grants
     * @param mixed[] $additionalClaims an array of additional claims for the JWT, e.g. the "iss"/"aud"/"sub"/"client_id" claims required by RFC 9068 access tokens under the Mercure protocol 1.0
     */
    public function __construct(
        private readonly TokenFactoryInterface $factory,
        private readonly array $grants = [],
        private readonly array $additionalClaims = [],
    ) {
    }
}
```

### Constructor Parameters
- **$factory** (`TokenFactoryInterface`) - Required - The factory used to mint each token.
- **$grants** (`Grant[]`) - Optional (default `[]`) - Grants baked into every token.
- **$additionalClaims** (`array<string, mixed>`) - Optional (default `[]`) - Additional claims baked into every token (e.g. `iss`/`aud`/`sub`/`client_id`).

### Method: `getJwt(): string`

#### Description
Returns a freshly created JWT. Every call mints a new token, so `iat`/`jti`/`exp` change with each call.

#### Signature
```php
public function getJwt(): string
```

#### Returns
- **string** - A freshly created JWT.

#### Throws
- Whatever `TokenFactoryInterface::create()` throws (see `InvalidArgumentException` for minting failures).

### Example: Basic Usage
```php
use Symfony\Component\Mercure\Hub;
use Symfony\Component\Mercure\Jwt\FactoryTokenProvider;
use Symfony\Component\Mercure\Jwt\Grant;
use Symfony\Component\Mercure\Jwt\LcobucciFactory;
use Symfony\Component\Mercure\Update;

const HUB_URL = 'https://demo.mercure.rocks/.well-known/mercure';
const JWT_SECRET = '!ChangeThisMercureHubJWTSecretKey!';

$jwtFactory = new LcobucciFactory(JWT_SECRET);
$provider = new FactoryTokenProvider($jwtFactory, [new Grant([Grant::ACTION_PUBLISH], ['*'])]);

$hub = new Hub(HUB_URL, $provider);
$hub->publish(new Update('https://example.com/books/1.jsonld', 'Hi from Symfony!'));
```

### Example: With Fixed RFC 9068 Claims and Error Handling
```php
use Symfony\Component\Mercure\Exception\InvalidArgumentException;
use Symfony\Component\Mercure\Jwt\FactoryTokenProvider;
use Symfony\Component\Mercure\Jwt\Grant;
use Symfony\Component\Mercure\Jwt\LcobucciFactory;

$provider = new FactoryTokenProvider(
    new LcobucciFactory('secret'),
    [new Grant([Grant::ACTION_SUBSCRIBE], ['/books/*'])],
    ['iss' => 'https://example.com', 'aud' => 'https://example.com', 'sub' => 'w', 'client_id' => 'web'],
);

try {
    $jwt = $provider->getJwt();
} catch (InvalidArgumentException $e) {
    // e.g. a grant declared no actions → "A grant must declare at least one action."
}
```
```

--------------------------------

### Example usage with Authorization and controller

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/EventSubscriber/SetCookieSubscriber.md

Shows how to wire the subscriber and use the Authorization service in a controller to set a cookie for subscribe rights. The subscriber then copies the cookie to the response at kernel.response.

```php
// services wiring (YAML sketch)
//  App\EventListener / kernel listener:
//  - Symfony\Component\Mercure\EventSubscriber\SetCookieSubscriber

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Mercure\Authorization;

final class BookController
{
    public function __construct(private readonly Authorization $authorization)
    {
    }

    public function __invoke(\Symfony\Component\HttpFoundation\Request $request): Response
    {
        // grant subscribe rights for this browser session
        $this->authorization->setCookie($request, ['https://example.com/books/{id}']);

        // At kernel.response, SetCookieSubscriber copies the cookie from
        // $request->attributes->get('_mercure_authorization_cookies')
        // into the response headers.
        return new Response('<!doctype html>...');
    }
}
```

--------------------------------

### GET {jwksUri}

Source: https://github.com/symfony/mercure/blob/main/_autodocs/endpoints.md

Documentation for the JWKS fetch operation performed by the WebTokenFactory.

```APIDOC
## GET {jwksUri}

### Description
Fetches a JSON Web Key Set (JWKS) document from the specified URI to retrieve a signing key for JWT verification. The key is fetched once per factory instance and is not re-fetched on rotation.

### Method
GET

### Endpoint
{jwksUri}

### Parameters
#### Path Parameters
- **jwksUri** (string) - Required - The URI of the JWKS endpoint to fetch.

### Response
#### Success Response (200)
- **JWKSet** (object) - A JSON Web Key Set document, from which a key is selected using `selectKey('sig', $algorithm, ['kid' => $keyId] ?? [])`.

#### Error Responses
- **Transport/HTTP failure** - Throws `Exception\RuntimeException('Failed to fetch the JWK Set at "%s".')`.
- **No matching key** - Throws `Exception\InvalidArgumentException('No signing key matching algorithm "%s"... was found...')`.

### Notes
- The key is fetched once per factory instance; upstream rotation is not re-fetched.
```

--------------------------------

### Using StaticTokenProvider with Hub to publish update

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Jwt/TokenProviders.md

This example shows how to create a Hub with a StaticTokenProvider and publish an update. The catch block handles InvalidArgumentException thrown by Hub::publish() when the static token is malformed.

```php
use Symfony\Component\Mercure\Hub;
use Symfony\Component\Mercure\Jwt\StaticTokenProvider;
use Symfony\Component\Mercure\Update;

$hub = new Hub('https://hub.example.com/.well-known/mercure', new StaticTokenProvider('eyJhbGciOiJIUzI1NiJ9...'));

try {
    $hub->publish(new Update('https://example.com/books/1', '{}'));
} catch (\Symfony\Component\Mercure\Exception\InvalidArgumentException $e) {
    // thrown by Hub::publish() when the static token is malformed
}
```

--------------------------------

### Example: CachedTokenProvider implementation

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Jwt/TokenProviderInterface.md

Implements TokenProviderInterface to reuse a cached token until it approaches expiry. The token is minted via a closure and cached using the null coalescing assignment operator. The refresh policy is left to the user.

```php
use Symfony\Component\Mercure\Jwt\TokenProviderInterface;

final class CachedTokenProvider implements TokenProviderInterface
{
    private ?string $token = null;

    public function __construct(private readonly \Closure $mint)
    {
    }

    public function getJwt(): string
    {
        return $this->token ??= ($this->mint)(); // refresh policy is yours
    }
}
```

--------------------------------

### Symfony\Component\Mercure\HubInterface

Source: https://github.com/symfony/mercure/blob/main/_autodocs/types.md

Interface for a Mercure hub, defining methods to get the public URL, token factory, publish updates, and get protocol version and cookie name.

```APIDOC
## Interface: Symfony\Component\Mercure\HubInterface

### Description
Interface for a Mercure hub. It defines methods to get the public URL, token factory, publish updates, and get protocol version and cookie name.

### Methods
#### getPublicUrl(): string
Returns the public URL of the hub.

- **Returns**: string - The public URL.

#### getFactory(): ?TokenFactoryInterface
Returns the token factory used to create JWTs, or null if not available.

- **Returns**: ?TokenFactoryInterface - The token factory or null.

#### publish(Update $update): string
Publishes an update to the hub.

- **Parameters**:
  - **$update** (Update) - Required - The update to publish.
- **Returns**: string - The ID of the published update.

#### getProtocolVersion(): ProtocolVersion
Returns the protocol version used by the hub.

- **Returns**: ProtocolVersion - The protocol version.

#### getCookieName(): string
Returns the name of the cookie used for authentication.

- **Returns**: string - The cookie name.
```

--------------------------------

### Symfony\Component\Mercure\Jwt\TokenProviderInterface

Source: https://github.com/symfony/mercure/blob/main/_autodocs/types.md

Interface for a JWT token provider, defining a method to get the JWT.

```APIDOC
## Interface: Symfony\Component\Mercure\Jwt\TokenProviderInterface

### Description
Interface for a JWT token provider. It defines a method to get the JWT.

### Methods
#### getJwt(): string
Returns the JWT token.

- **Returns**: string - The JWT token.
```

--------------------------------

### Basic use - advertise the default hub

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Discovery.md

Shows how to instantiate Discovery and add a link to a request. The resulting _links attribute is rendered as a Link header.

```php
use Symfony\Component\Mercure\Discovery;
use Symfony\Component\HttpFoundation\Request;

$discovery = new Discovery($registry);

$request = Request::create('https://example.com/books/1');
$discovery->addLink($request);
// request attribute "_links" now holds a GenericLinkProvider;
// the framework renders it as:
// Link: <https://hub.example.com/.well-known/mercure>; rel="mercure"
```

--------------------------------

### Symfony\Component\Mercure\Jwt\Grant

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Jwt/Grant.md

Documentation for the Grant class, including constructor, constants, validation rules, and usage examples.

```APIDOC
## Grant Class

### Description
Represents a Mercure protocol 1.0 `authorization_details` entry: a named set of actions granted over a set of topics, with an optional payload. Grants are passed to `TokenFactoryInterface::create()` and, in normalized form, to `Authorization::createCookie()`/`setCookie()`.

### Constructor

```php
public function __construct(
    public readonly array $actions,
    public readonly array $topics,
    public readonly mixed $payload = null,
)
```

### Parameters
- **$actions** (string[]) - Required - One or more of `Grant::ACTION_*` (custom action strings are tolerated at construction; rejected by a hub).
- **$topics** (array<int, string>|array<string, string[]>) - Required - A flat list of topics (matched as `exact`), or a matcher-type map (`exact`, `urlpattern`, or a registered extension type) → list of patterns.
- **$payload** (mixed) - Optional - Default `null`. Optional payload stored by the hub per entry. Only meaningful when `subscribe` is among `$actions`; the hub resolves payloads only from entries whose actions include `subscribe`.

### Constants
- **Grant::ACTION_SUBSCRIBE** = 'subscribe' - Grants the right to subscribe to the grant's topics.
- **Grant::ACTION_PUBLISH** = 'publish' - Grants the right to publish to the grant's topics.

### Validation Rules
`Grant` itself performs no validation — `JwtClaims::buildAuthorizationDetails()` rejects invalid combinations at token-minting time:
- a grant must declare at least one action;
- no topics together with a non-null payload is rejected (`A grant "payload" requires at least one topic.`);
- a payload on a grant without `subscribe` is rejected;
- under the legacy protocol (`LcobucciFactory` with `ProtocolVersion::Legacy`), any payload and any non-`exact` matcher are rejected.

### Examples

Subscribe grant with a matcher pattern (protocol 1.0):

```php
use Symfony\Component\Mercure\Jwt\Grant;

$grant = new Grant(
    [Grant::ACTION_SUBSCRIBE],
    ['urlpattern' => ['https://example.com/books/{id}']],
);
```

Publish grant, flat topics:

```php
$publishGrant = new Grant([Grant::ACTION_PUBLISH], ['https://example.com/books/1']);
```

Grant with payload (protocol 1.0 private updates):

```php
$grant = new Grant(
    [Grant::ACTION_SUBSCRIBE, Grant::ACTION_PUBLISH],
    ['https://example.com/books/1'],
    ['role' => 'admin'], // mixed — any JSON-serializable value
);
```

Passing grants to a token factory:

```php
use Symfony\Component\Mercure\Jwt\LcobucciFactory;

$token = (new LcobucciFactory('secret'))->create([$grant], [
    'iss' => 'https://example.com',
    'aud' => 'https://example.com',
    'sub' => 'anonymous',
    'client_id' => 'web',
]);
```
```

--------------------------------

### Symfony\Component\Mercure\RemoteHubInterface

Source: https://github.com/symfony/mercure/blob/main/_autodocs/types.md

Interface for a remote Mercure hub, extending HubInterface with a method to get the hub URL.

```APIDOC
## Interface: Symfony\Component\Mercure\RemoteHubInterface

### Description
Interface for a remote Mercure hub. Extends HubInterface and adds a method to get the hub URL.

### Methods
#### getUrl(): string
Returns the URL of the remote hub.

- **Returns**: string - The hub URL.
```

--------------------------------

### Symfony\Component\Mercure\ProtocolVersion

Source: https://github.com/symfony/mercure/blob/main/_autodocs/types.md

Enum representing the supported Mercure protocol versions with a method to get the default cookie name.

```APIDOC
## Enum: Symfony\Component\Mercure\ProtocolVersion

### Description
Enum representing the supported Mercure protocol versions. It provides a method to get the default cookie name for each version.

### Cases
- **Legacy** (value: `'0.x'`) - The pre-1.0, "legacy" protocol: "topic" query parameter, bare "mercure" JWT claim, "mercureAuthorization" cookie.
- **V1** (value: `'1.0'`) - The Mercure 1.0 protocol: "match"/"match_<type>" query parameters, "authorization_details" JWT claim.

### Methods
#### getDefaultCookieName(): string
Returns the default cookie name for the protocol version.

- **Returns**: string - The default cookie name.
  - For `Legacy`: `mercureAuthorization`
  - For `V1`: `__Secure-mercure_access_token`
```

--------------------------------

### Basic publish with FrankenPhpHub

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/FrankenPhpHub.md

Creates a FrankenPhpHub instance and publishes an Update to a Mercure hub URL. Use this in a FrankenPHP server process where the mercure_publish() runtime function is available.

```php
use Symfony\Component\Mercure\FrankenPhpHub;
use Symfony\Component\Mercure\Update;

$hub = new FrankenPhpHub('https://example.com/.well-known/mercure');

$id = $hub->publish(new Update('https://example.com/books/1.jsonld', 'Hello in-process!'));
```

--------------------------------

### Get URL from TraceableHub

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Debug/TraceableHub.md

Returns the hub URL by delegating to the decorated hub when the getUrl method exists.

```php
public function getUrl(): string
{
    if (method_exists($this->hub, 'getUrl')) {
        return $this->hub->getUrl();
    }
}
```

--------------------------------

### Basic usage with an auto-minted token

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Hub.md

Demonstrates creating a Hub with a JWT factory token provider and publishing an update.

```APIDOC
## Hub::publish

### Description
Publishes an update to the Mercure hub using the configured token provider.

### Method
publish

### Parameters
- **Update $update** (Update) - Required - The update to publish.

### Request Example
```php
use Symfony\Component\Mercure\Hub;
use Symfony\Component\Mercure\Jwt\LcobucciFactory;
use Symfony\Component\Mercure\Jwt\FactoryTokenProvider;
use Symfony\Component\Mercure\Jwt\Grant;
use Symfony\Component\Mercure\Update;

const HUB_URL = 'https://demo.mercure.rocks/.well-known/mercure';
const JWT_SECRET = '!ChangeThisMercureHubJWTSecretKey!';

$jwtFactory = new LcobucciFactory(JWT_SECRET);
$provider = new FactoryTokenProvider($jwtFactory, [new Grant([Grant::ACTION_PUBLISH], ['*'])]);
// Alternative: factory with grants:
// $provider = new FactoryTokenProvider($jwtFactory, grants: [new Grant([Grant::ACTION_PUBLISH], ['*'])]);

$hub = new Hub(HUB_URL, $provider);
$id = $hub->publish(new Update('https://example.com/books/1.jsonld', 'Hi from Symfony!'));
```

### Response
Returns the update ID as a string.
```

--------------------------------

### GET {hubUrl}

Source: https://github.com/symfony/mercure/blob/main/_autodocs/endpoints.md

Generates a subscriber connection URL. This is a URL-building operation, not an actual HTTP request made by the library.

```APIDOC
## GET {hubUrl}

### Description
Generates a subscriber connection URL. This endpoint is used by `Twig\MercureExtension::mercure()` and `Hub::getPublicUrl()` to build the URL for subscribers to connect to the hub.

### Method
GET

### Endpoint
{hubUrl} - The hub URL configured on the `Hub`.

### Parameters
No parameters are documented for this endpoint.

### Response
Returns the public hub URL as a string, used for subscriber connections.
```

--------------------------------

### FrankenPhpHub::__construct

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/FrankenPhpHub.md

Creates a new FrankenPhpHub instance with the given hub URL and optional JWT factory.

```APIDOC
## FrankenPhpHub::__construct

### Description
Creates a new FrankenPhpHub instance. The hub URL is required; a JWT factory can be provided for generating authorization cookies.

### Method
Constructor

### Parameters
- **$hubUrl** (string) - Required - The URL of the Mercure hub (e.g., 'https://example.com/.well-known/mercure').
- **$jwtFactory** (JwtFactoryInterface) - Optional - A JWT factory for generating authorization cookies (e.g., LcobucciFactory).

### Example
```php
$hub = new FrankenPhpHub('https://example.com/.well-known/mercure');
```
```

--------------------------------

### Reset between profiler collections

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Debug/TraceableHub.md

Resets the traceable hub's collected data, so subsequent counts start from zero.

```php
$traceable->reset();
echo $traceable->count(); // 0
```

--------------------------------

### all() method signature

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/HubRegistry.md

Method all() that returns the array of named hubs. Does not include the default hub unless it was also passed in the hubs array.

```php
public function all(): array
```

--------------------------------

### Error handling for unknown hub name

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/HubRegistry.md

Error handling example showing how to catch InvalidArgumentException when an unknown hub name is requested.

```php
use Symfony\Component\Mercure\Exception\InvalidArgumentException;

try {
    $registry->getHub('nope');
} catch (InvalidArgumentException $e) {
    // Invalid hub name provided.
}
```

--------------------------------

### ProtocolVersion enum definition

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/ProtocolVersion.md

Defines the ProtocolVersion enum with Legacy and V1 cases, and a method to get the default cookie name for each version.

```php
enum ProtocolVersion: string
{
    /** The pre-1.0, "legacy" protocol: "topic" query parameter, bare "mercure" JWT claim, "mercureAuthorization" cookie. */
    case Legacy = '0.x';

    /** The Mercure 1.0 protocol: "match"/"match_<type>" query parameters, "authorization_details" JWT claim. */
    case V1 = '1.0';

    public function getDefaultCookieName(): string
    {
        return match ($this) {
            self::Legacy => 'mercureAuthorization',
            self::V1 => '__Secure-mercure_access_token',
        };
    }
}
```

--------------------------------

### Basic usage: wrap hub, publish, inspect traces

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Debug/TraceableHub.md

Wraps a Hub with TraceableHub and Stopwatch, publishes an update, then retrieves trace metrics: count, duration, memory, and messages.

```php
use Symfony\Component\Mercure\Debug\TraceableHub;
use Symfony\Component\Stopwatch\Stopwatch;

$hub = new \Symfony\Component\Mercure\Hub($url, $provider);
$traceable = new TraceableHub($hub, new Stopwatch());

$traceable->publish(new \Symfony\Component\Mercure\Update('/books/1', '{}'));

$traceable->count();        // 1
$traceable->getDuration();  // e.g. 34.2 (ms)
$traceable->getMemory();    // e.g. 12288 (bytes)
$traceable->getMessages();  // [['object' => Update, 'duration' => ..., 'memory' => ...]]
```

--------------------------------

### Publish grant with flat topics

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Jwt/Grant.md

Creates a Grant with the publish action and a flat list of topics, matched as exact.

```php
$publishGrant = new Grant([Grant::ACTION_PUBLISH], ['https://example.com/books/1']);
```

--------------------------------

### GET {jwksUri}

Source: https://github.com/symfony/mercure/blob/main/_autodocs/endpoints.md

Fetches a JSON Web Key Set from the given URI. This is an outbound request made by the library to retrieve public keys.

```APIDOC
## GET {jwksUri}

### Description
Fetches a JSON Web Key Set (JWKS) from the specified URI. This endpoint is used by `WebTokenFactory::fromJwksUri()` to retrieve public keys for JWT verification.

### Method
GET

### Endpoint
{jwksUri} - The URI of the JSON Web Key Set.

### Parameters
No parameters are documented for this endpoint.

### Response
Returns the JSON Web Key Set as a JSON object.
```

--------------------------------

### Basic Update creation with single topic

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Update.md

Basic usage with a single topic and JSON payload. Shows how to create an Update and access its topics and data.

```php
use Symfony\Component\Mercure\Update;

$update = new Update(
    'https://example.com/books/1.jsonld',
    json_encode(['status' => 'published'], \JSON_THROW_ON_ERROR),
);
echo $update->getTopics()[0]; // https://example.com/books/1.jsonld
echo $update->getData();      // {"status":"published"}
```

--------------------------------

### Clear authorization cookie on logout

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Authorization.md

Logging out example that clears the authorization cookie. Use clearCookie() to clear automatically, or createClearCookie() to attach the cookie manually.

```php
$authorization->clearCookie($request); // or createClearCookie() if you want to attach manually
```

--------------------------------

### StaticTokenProvider

Source: https://github.com/symfony/mercure/blob/main/_autodocs/configuration.md

Constructor for StaticTokenProvider.

```APIDOC
## StaticTokenProvider

### Description
Provides a fixed publish JWT.

### Constructor
`__construct(string $token)`

### Parameters
- **$token** (string) - Required - Fixed publish JWT.
```

--------------------------------

### FrankenPhpHub::publish()

Source: https://github.com/symfony/mercure/blob/main/_autodocs/errors.md

Publishes an update using the FrankenPHP hub. Throws exceptions on runtime errors.

```APIDOC
## [PHP] FrankenPhpHub::publish()

### Description
Publishes an update using the FrankenPHP hub. Throws exceptions on runtime errors.

### Method
PHP method (FrankenPhpHub object)

### Parameters
- **update** (Update) - Required - The update to publish.

### Exceptions
- `Exception\RuntimeException`

### Usage Example
```php
$hub->publish($update);
```

```

--------------------------------

### HubInterface definition

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/HubInterface.md

Defines the contract for a Mercure hub, including methods for getting the public URL, token factory, publishing updates, protocol version, and cookie name.

```php
/**
 * Publishes updates to a Mercure hub.
 */
interface HubInterface
{
    /**
     * Returns the Hub public URL.
     *
     * If the public URL is not configured and the hub also implements the {@see RemoteHubInterface}, this method MUST return
     * the internal URL {@see RemoteHubInterface::getUrl()}.
     */
    public function getPublicUrl(): string;

    /**
     * Return the token factory associated with this Hub.
     */
    public function getFactory(): ?TokenFactoryInterface;

    /**
     * Publish an update to this Hub.
     */
    public function publish(Update $update): string;

    /**
     * Returns the version of the Mercure protocol spoken by this Hub.
     */
    public function getProtocolVersion(): ProtocolVersion;

    /**
     * Returns the name of the subscriber authorization cookie for this Hub.
     */
    public function getCookieName(): string;
}
```

--------------------------------

### FactoryTokenProvider

Source: https://github.com/symfony/mercure/blob/main/_autodocs/configuration.md

Constructor options for the FactoryTokenProvider.

```APIDOC
## FactoryTokenProvider

### Description
Provides JWT tokens by delegating to a token factory. Allows baking grants and additional claims into every token.

### Constructor
`__construct(TokenFactoryInterface $factory, array $grants = [], array $additionalClaims = [])`

### Parameters
- **$factory** (TokenFactoryInterface) - Required - Minting factory.
- **$grants** (Grant[]) - Optional - Grants baked into every token. Default: `[]`.
- **$additionalClaims** (array<string, mixed>) - Optional - Claims baked into every token. Default: `[]`.
```

--------------------------------

### Twig: Basic mercure() usage with various arguments

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Twig/MercureExtension.md

Shows how to call `mercure()` with no arguments, a single topic, an array of topics, and a URL pattern. The comments show the generated hub URLs.

```twig
{{ mercure() }}
{# https://hub.example.com/.well-known/mercure #}

{{ mercure('https://example.com/books/1') }}
{# V1 hub: https://hub.example.com/.well-known/mercure?match=https%3A%2F%2Fexample.com%2Fbooks%2F1 #}

{{ mercure(['https://example.com/books/1', 'https://example.com/authors/1']) }}
{# ?match=...&match=... #}

{{ mercure({'urlpattern': ['https://example.com/books/{id}']}) }}
{# ?match_urlpattern=https%3A%2F%2Fexample.com%2Fbooks%2F%7Bid%7D #}
```

--------------------------------

### Legacy usage of TraceablePublisher

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Debug/TraceablePublisher.md

Legacy usage example: creates a TraceablePublisher wrapping a Publisher and Stopwatch, publishes an Update, then outputs the count and duration. Deprecated since Mercure 0.5.

```php
use Symfony\Component\Mercure\Debug\TraceablePublisher;
use Symfony\Component\Mercure\Publisher;
use Symfony\Component\Stopwatch\Stopwatch;

$traceable = new TraceablePublisher(
    new Publisher($hubUrl, $tokenProvider),
    new Stopwatch(),
);

$traceable(new \Symfony\Component\Mercure\Update('/books/1', '{}'));

echo $traceable->count();       // 1
echo $traceable->getDuration(); // e.g. 24.8
```

--------------------------------

### Modern equivalent — replace Publisher with Hub

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Publisher.md

Modern equivalent of the legacy usage. Replace `Publisher` with `Hub` and call `publish()`.

```php
use Symfony\Component\Mercure\Hub;

$hub = new Hub($hubUrl, $provider);
$id = $hub->publish(new Update('https://example.com/books/1.jsonld', 'Hi!'));
```

--------------------------------

### MockHub Constructor

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/MockHub.md

Creates a new MockHub instance with the given URL, JWT provider, publisher callable, and optional configuration parameters.

```APIDOC
## MockHub Constructor

### Description
Creates a new MockHub instance with the given URL, JWT provider, publisher callable, and optional configuration parameters.

### Method
Constructor

### Endpoint
`new MockHub(...)`

### Parameters
- **$url** (string) - Required - The hub URL (returned by `getUrl()`; also used as public URL unless `$publicUrl` is set).
- **$jwtProvider** (TokenProviderInterface) - Required - The JWT provider (kept for interface parity; not consumed by `publish()`).
- **$publisher** (callable(Update): string) - Required - Invoked by `publish()` in place of a network call.
- **$jwtFactory** (?TokenFactoryInterface) - Optional - Default: `null` - Optional token factory, exposed via `getFactory()`.
- **$publicUrl** (?string) - Optional - Default: `null` - Public URL; falls back to `$url`.
- **$cookieName** (?string) - Optional - Default: `null` - Subscriber cookie name; defaults per protocol version.
- **$protocolVersion** (ProtocolVersion) - Optional - Default: `ProtocolVersion::V1` - Protocol version exposed by `getProtocolVersion()`.

### Example
```php
$hub = new MockHub(
    url: 'https://example.com/.well-known/mercure',
    jwtProvider: $jwtProvider,
    publisher: function (Update $update): string {
        // custom publishing logic
        return 'published';
    }
);
```
```

--------------------------------

### GET {hubUrl}?query

Source: https://github.com/symfony/mercure/blob/main/_autodocs/endpoints.md

Subscriber connection URL generation for the Mercure hub. The URL is built by Twig\MercureExtension::mercure() and supports both Protocol 1.0 and Legacy protocol query parameters.

```APIDOC
## GET {hubUrl}?query

### Description
Generates the URL a browser subscribes to via EventSource. The component does not open the SSE connection itself; it builds the subscription URL.

### Method
GET

### Endpoint
{hubUrl}?query

### Parameters
#### Query Parameters
- **match** (string) - Required - One per exact topic; value is urlencode(pattern).
- **match_<matcherType>** (string) - Optional - One per pattern of a non-exact matcher; <matcherType> is rawurlencoded (e.g. match_urlpattern).
- **lastEventID** (string) - Optional - Resume-from-ID (legacy compat, kept for pre-0.14 hubs).
- **Last-Event-ID** (string) - Optional - Same value duplicated.

### Request Example
https://hub.example.com/.well-known/mercure?match=https%3A%2F%2Fexample.com%2Fbooks%2F1&match_urlpattern=https%3A%2F%2Fexample.com%2Fbooks%2F%7Bid%7D

### Response
#### Success Response (200)
- **body** (string) - The SSE stream (not documented in source).

#### Response Example
(Not provided in source.)
```

--------------------------------

### MockHub class definition with constructor

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/MockHub.md

Defines the MockHub class implementing HubInterface. The constructor accepts a URL, JWT provider, publisher callable, and optional JWT factory, public URL, cookie name, and protocol version. The publisher callable receives an Update and must return a string; it is wrapped in a closure and the cookie name defaults to the protocol version's default.

```php
final class MockHub implements HubInterface
{
    private readonly \(\Closure) $publisher;

    private readonly string $cookieName;

    /**
     * @param (callable(Update): string) $publisher
     */
    public function __construct(
        private readonly string $url,
        private readonly TokenProviderInterface $jwtProvider,
        callable $publisher,
        private readonly ?TokenFactoryInterface $jwtFactory = null,
        private readonly ?string $publicUrl = null,
        ?string $cookieName = null,
        private readonly ProtocolVersion $protocolVersion = ProtocolVersion::V1,
    ) {
        $this->publisher = $publisher(...);
        $this->cookieName = $cookieName ?? $protocolVersion->getDefaultCookieName();
    }
}
```

--------------------------------

### Migrate to TraceableHub

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Debug/TraceablePublisher.md

Modern equivalent using TraceableHub and Hub instead of the deprecated TraceablePublisher. Shows the migration path.

```php
use Symfony\Component\Mercure\Debug\TraceableHub;
use Symfony\Component\Mercure\Hub;

$traceableHub = new TraceableHub(new Hub($url, $provider), new Stopwatch());
$traceableHub->publish(new \Symfony\Component\Mercure\Update('/books/1', '{}'));
```

--------------------------------

### addLink method implementation

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Discovery.md

The addLink method adds a Link header to the request. It skips CORS preflight requests and uses the HubRegistry to get the hub's public URL.

```php
public function addLink(Request $request, ?string $hub = null): void
{
    // Prevent issues with NelmioCorsBundle
    if ($this->isPreflightRequest($request)) {
        return;
    }

    $hubInstance = $this->registry->getHub($hub);
    $link = new Link('mercure', $hubInstance->getPublicUrl());
    if (null === $linkProvider = $request->attributes->get('_links')) {
        $request->attributes->set('_links', new GenericLinkProvider([$link]));

        return;
    }

    $request->attributes->set('_links', $linkProvider->withLink($link));
}
```

--------------------------------

### Subscribe grant with matcher pattern

Source: https://github.com/symfony/mercure/blob/main/_autodocs/api-reference/Jwt/Grant.md

Creates a Grant with the subscribe action and a urlpattern matcher for a topic pattern. This is for protocol 1.0.

```php
use Symfony\Component\Mercure\Jwt\Grant;

$grant = new Grant(
    [Grant::ACTION_SUBSCRIBE],
    ['urlpattern' => ['https://example.com/books/{id}']],
);
```
Tokens:
Raw