FCM topics
Two different things, often confused:
- Publishing one message to a topic or to a condition (a combination of topics): one request to FCM, FCM fans it out.
- Managing subscriptions: subscribing and unsubscribing a specific installation to a topic.
| Enable | nothing to enable: both are part of the FCM driver. Outside production they need live.allow_topics on the connection (see safe mode) |
| Migrations | none. The package keeps no local record of who is subscribed to which topic: the subscription lives at Google |
| Provider | FCM only. APNs has no topics; for a fan-out on iOS use broadcast channels (live activities) or a campaign |
Related pages: sending, messages, safe mode, outcomes, credentials for FCM, commands.
What was not verified: nothing here has run against real FCM. The subscription client follows Google’s Discovery document (revision 20261112) and is tested against a mock server. Whether the 2048-byte payload rule counts exactly as the package counts it is unverified (below).
Publishing to a topic or a condition
use Padosoft\MobilePush\Core\Message\PushMessage;
use Padosoft\MobilePush\Laravel\Facades\MobilePush;
$report = MobilePush::toTopic('breaking-news')
->send(PushMessage::make('Breaking', 'Something happened'));
MobilePush::toCondition("'sports' in topics && 'it' in topics")
->send(PushMessage::make('Derby tonight', 'Kick-off at 21:00'))
->counts();
$fake->assertSentToTopic('breaking-news');
toTopic($name)builds anFcmTopic: 1 to 900 characters of[a-zA-Z0-9-_.~%]; a leading/topics/is removed for you.toCondition($expression)builds anFcmCondition: it must containin topicsand be at most 2048 characters. An FCM condition combines at most 5 topics (the compiler countsin topicsoccurrences and refuses more, before the network).- The destination is typed. A string is never guessed to be a topic or a token:
to('news')throws. - The connection is the FCM route of your configuration (
mobile-push.routes/default), or name one with->connection('android').
What you get back
One result for the whole publication, not one per recipient. Accepted means FCM accepted the publication request; it says nothing about how many phones received it, whether any did, or when. There are no per-recipient results, no counts of recipients, no receipts (no marker is issued for topics) and no notification fallback (a topic is an unknown audience).
What does not apply to a topic or a condition: the per-person frequency cap, the device registry’s eligibility check, the badge counter (there is no owner), quarantine and invalidation (a topic is not an installation). Your MobilePush::eligibleUsing() callback does see the typed destination (so you can allow or deny topics by name).
In a campaign, a topic or condition audience entry counts as one delivery per publication, and the campaign progress says that the number of recipients is not known.
Limits
| Limit | Value | Status |
|---|---|---|
| Payload for a topic or condition message | 2048 bytes (4096 for a token message) | Google publishes the numbers. The counting rule (sum of strlen(key) + strlen(value) over notification, data, the Android data maps and the title/body/image of the Android notification; no JSON punctuation, no envelope; the receipt marker and deep_link count) is the package’s own conservative rule and is unverified against Google’s behaviour |
| Topics in a condition | 5 | enforced by the compiler |
| iOS-only message capabilities | dropped (lenient mode) or refused | an FCM message has no equivalent for them; see messages |
A message over the limit is refused before the network with a PayloadTooLargeException, unless you opted in to ->truncate(), which only shortens the title and body.
Managing subscriptions
The package uses the FCM topic subscriptions resource (projects.registrations.topicSubscriptions), not the legacy Instance ID batch API. The consequences are real:
- One installation per call. There is no bulk operation. The
*Many()helpers multiplex single calls inside one transport send and return one result per input, in the same order, without exceptions. - The registration is an FCM registration token or an FID (
FcmToken/FcmFid). - Calls are authenticated with the connection’s OAuth credential; a 401 refreshes the token once and retries once.
- Errors never copy Google’s
error.message(it can echo the registration token): only enum-likeerror.statusanddetails[].errorCodeare read, and mapped to reason codes (DestinationUnregistered,DestinationMismatch,QuotaExceeded,AuthForbidden, …).
Idempotency
| Operation | Method | Idempotent how |
|---|---|---|
| subscribe | subscribe($installation, $topic) |
“already exists” (HTTP 409 / ALREADY_EXISTS) is success; TopicSubscription::$alreadyExisted tells you which |
| unsubscribe | unsubscribe($installation, $topic) |
always sent with allowMissing=true, so “already unsubscribed” is success; the server cannot say which case it was |
| upsert | patch($installation, $topic, $allowMissing = true) |
returns the existing subscription or creates it |
| read one | get($installation, $topic) |
a missing subscription is HTTP 404: TopicApiException::isNotFound() |
| list | list($installation, ?$pageSize) |
a generator over pages (default 1000, maximum 2000 per page); the next request is sent only when you advance it |
| many | subscribeMany($installations, $topic), unsubscribeMany(...) |
list<TopicBatchResult> (ok, alreadyInState, HTTP status, reason; never the registration id) |
Single calls throw TopicApiException (with reason, status, isNotFound()); the batch helpers do not.
From the command line
php artisan mobile-push:fcm:topic-subscription subscribe breaking-news --token=TOKEN1 --token=TOKEN2
php artisan mobile-push:fcm:topic-subscription unsubscribe breaking-news --fid=FID1
php artisan mobile-push:fcm:topic-subscription list --token=TOKEN1 --json
printf '%s\n' TOKEN1 'fid=FID2' | php artisan mobile-push:fcm:topic-subscription subscribe breaking-news --stdin
Arguments and options: {action} (subscribe, unsubscribe, list), {topic?} (required except for list), --connection= (default: the only FCM connection), --token=* and --fid=* (repeatable), --stdin (one installation per line, a token, or fid=<id>), --scope=, --json. The table shows masked installations; an invalid value is reported without being repeated. The command is a thin layer over MobilePush::topicSubscriptions() (below), so it goes through the same connection choice and the same safe-mode gate. Exit code 1 when any installation failed, 0 otherwise; in simulation mode it prints that nothing was sent.
From code
MobilePush::topicSubscriptions(?string $connection = null, ?string $scope = null) returns a TopicSubscriptionClient (the same one the command uses). It is built with the connection’s OAuth credential, the package transport, the endpoint catalog and the same safe-mode gate as a send.
- The connection is the FCM route of the scope when
$connectionis null (mobile-push.routes/default; the only FCM connection is picked, and several FCM connections without a route throw aConfigurationExceptionthat says how to choose), or the name you pass. An APNs connection throws aConfigurationException(“is not an FCM connection”): topic subscriptions exist only on FCM. An unknown name throwsUnknownConnectionException. Both are raised before any request. $scopeis the multi-tenancy scope; null means the current one.
use Padosoft\MobilePush\Core\Identity\Destination\FcmToken;
use Padosoft\MobilePush\Core\Identity\Destination\FcmTopic;
use Padosoft\MobilePush\Laravel\Facades\MobilePush;
$topics = MobilePush::topicSubscriptions('android');
$topics->subscribe(FcmToken::of($token), FcmTopic::of('breaking-news'));
// $installations: a list of FcmToken (or FcmFid) objects
foreach ($topics->subscribeMany($installations, FcmTopic::of('breaking-news')) as $i => $result) {
if (! $result->ok) {
logger()->warning('Topic subscription failed', ['position' => $i, 'reason' => $result->reason->code->value]);
}
}
This example is not run by the documentation tests: MobilePush::fake() does not replace the topic client, so it would need a real connection and transport.
The result objects:
subscribe(),get()andpatch()return aTopicSubscription(the topic name, and forsubscribe()thealreadyExistedflag);unsubscribe()returns nothing;list()yieldsTopicSubscriptions page by page.subscribeMany()/unsubscribeMany()return alist<TopicBatchResult>in the order of the input:ok,alreadyInState(the subscription already existed, for subscribe),status(HTTP status,0when no response exists: transport failure, simulation or a block) andreason(aReason,ReasonCode::Nonewhen ok). They never carry the registration token and never throw per installation.- Single calls throw
TopicApiExceptionon failure, including when safe mode simulated or blocked the call (itsreasonsays which);isNotFound()is true for HTTP 404.
Safe mode. Every call asks the safe-mode guard first, with the operation TopicSubscription and the installation as destination, using the connection’s default send options. In simulate mode nothing is sent and the result carries ReasonCode::Simulated. Outside production the call is blocked (ReasonCode::PolicySafeMode, no request made) unless the connection has live.allow, live.allow_topics and the installation in live.only_to. In production with the effective mode live it goes through. A blocked or simulated call is therefore not a failure of FCM: check the reason before suspecting the provider. The pages safe mode and the table above give the full rules.
The package does not bind a TopicSubscriptionClient in the container: ask the manager for one each time (it is cheap, and it follows the connection’s current credentials). It also makes no local record of subscriptions.
Safe mode rules
- In simulate mode nothing is sent: single calls throw a
TopicApiExceptionwith a simulated reason, batch helpers return failed results with that reason, the command says “Simulation mode”. - Outside production, publishing to a topic or condition and subscription calls are operations that reach many devices or manage provider state, so they need explicit authorisation on the connection:
live.allow = trueandlive.allow_topics = true(mobile-push.connections.<name>.live.allow_topics). Without them the operation is blocked with a message that names the missing flag. - Subscription calls name an installation (a token or FID): outside production that installation also has to be in the connection’s
live.only_toallowlist of test devices. A topic publication is a group destination and relies onallow_topicsalone. - In production, execution mode
liveallows both. See safe mode for the full table.
This page is generated from docs/topics.md. To change it, edit that file in the repository, not this site.