Skip to content

docs: explain how to publish Mercure updates from php-cli #2718

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
henderkes merged 1 commit into from
Oct 18, 2026
Merged

docs: explain how to publish Mercure updates from php-cli #2718

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions docs/mercure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,8 @@ php_server

Access tokens must carry the identifier of the `issuer` they were signed by in their `iss` claim.
`mercure_publish()` doesn't need any token: it publishes directly, in-process.
The `publisher` block enables the POST endpoint of the hub, required to publish from outside the server, such as from [CLI commands](#publishing-from-cli-commands).
Without it, the hub only accepts updates from `mercure_publish()`.

> [!TIP]
>
Expand Down Expand Up @@ -125,6 +127,19 @@ The returned string is the ID of the update, to be used as `Last-Event-ID` to re
A `TypeError` is thrown when `$topics` is an array holding a value that isn't a string.
A `RuntimeException` is thrown when no hub is configured, or when the hub fails to dispatch the update.

#### Publishing from CLI commands

`mercure_publish()` is only available in the web server and workers.
`frankenphp php-cli` doesn't run the hub, so the function doesn't exist there.
Commands, such as cron jobs or queue consumers, publish through the POST endpoint of the hub instead,
using [`file_get_contents()`](#using-file_get_contents) or [the Symfony Mercure Component](#using-symfony-mercure).

> [!WARNING]
>
> Be careful with feature detection: many frameworks, including Symfony and Laravel, run code in CLI to build the service container and warm up caches.
> A `function_exists('mercure_publish')` call evaluated there returns `false`, and the cached result then disables `mercure_publish()` in the web server too.
> Detect the function when publishing, not when building the container or the configuration.

### Using `file_get_contents()`

To dispatch an update to connected subscribers, send an authenticated POST request to the Mercure hub with the `topic` and `data` parameters:
Expand Down
Loading