Download the PHP package laith343/laravel-fcm-blast without Composer

laravel-fcm-blast

laith343/laravel-fcm-blast

High-throughput Firebase Cloud Messaging sender for Laravel. Pushes 10k+ req/s from PHP by driving a reused curl_multi handle pool with persistent TCP — OAuth handled by kreait/firebase-php, delivery handled by the engine.

This package is backend only. It exposes a programmatic API and a status DTO; build whatever UI/monitoring you want on top of status().

Contents

• Requirements
• Supported versions
• Install
• Configure
• Environment variables
• Sizing for your target RPS
• Integrate
• Per-request debug logging
• Run a blast
• Run locally
• Run in production
• Monitor
• How it hits 10k RPS

Requirements

SQLite caveat: fine for the test suite and single-worker dev runs, but its single-writer lock serializes the concurrent counter flushes — do not use it for multi-worker production blasts. Use Postgres or MySQL there.

Supported versions

Install

Configure

config/fcm-blast.php:

Real FCM needs HTTP/2. Over HTTP/1.1 every in-flight request needs its own TLS connection, so high concurrency to fcm.googleapis.com exhausts sockets (timeouts, broken pipes). http_version => '2tls' (the default) multiplexes thousands of requests over a handful of connections — set max_host_connections to something small (8-32). 2tls automatically uses HTTP/1.1 for plain-http endpoints, so a local mock is unaffected and can keep its many-connections setup (max_host_connections => null).

Environment variables

Every config key has an env override:

max_host_connections is per worker. Total connections to FCM = workers × max_host_connections. In-flight capacity per worker = max_host_connections × max_concurrent_streams (the engine sizes its concurrency to exactly this).

Sizing for your target RPS

Throughput is governed by Little's Law:

To hit a target RPS, make capacity ≥ in-flight needed, and keep FCM_BLAST_RATE_CAP at the rate you want (it caps emission so you never exceed it).

Worked example — 10,000 RPS (600k/min):

with 4 workers → 6,400 in-flight, enough for 10k RPS up to ~640ms latency; rate_cap then holds the ceiling at 10k.

Three real limits, in order of what you'll hit first:

1. Network egress — a single host (especially residential/cellular) tolerates only so many simultaneous connections. Failures show as transport errors (timeouts/resets), now auto-retried. Keep max_host_connections to what your link handles; scale out across hosts for more.
2. Latency — higher latency needs more in-flight for the same RPS. Measure avg_latency_ms from a run and plug it into the formula.
3. FCM project quota — above it, FCM returns 429/503 (the throttled counter). Check/raise it in Google Cloud Console → IAM & Admin → Quotas → "Firebase Cloud Messaging API".

Don't over-provision connections. Use the smallest connections × streams that covers your latency — extra connections only increase the handshake burst (more transport failures) without raising throughput, since rate_cap is the real ceiling.

Integrate

Implement two contracts. The package never touches your database directly.

Per-token context (localization, custom logic)

To tailor the message per user, have your TokenSource yield an OutboundToken (token + arbitrary context) instead of a plain string. The context reaches build() unchanged. It's fully optional — yielding a string keeps $context null, so existing sources/builders are unaffected.

context can be any value (array, DTO, model) — it's passed in-process, not serialized.

Per-run context (which campaign am I serving?)

Per-token context covers the message; per-run context tells the resolved TokenSource / MessageBuilder / InvalidTokenHandler instances which run they're serving. Workers resolve those classes from the container with no arguments, so without this they can't know the campaign. Implement ContextAware and pass the payload via withContext():

The context travels through the queued job, so it must be serializable (arrays/scalars, or SerializesModels-friendly values) — unlike per-token context, which stays in-process. Opt-in: classes that don't implement ContextAware are untouched.

Optional — prune permanently invalid tokens (FCM 404/400):

Per-request debug logging

Enable to capture every request's full body, context, outcome, HTTP code and latency for later debugging:

Output is one NDJSON record per request, in a daily-rotated file (fcm-blast-requests-YYYY-MM-DD.log):

Performance: records are buffered in memory and appended in bulk on the engine's existing 0.5s flush tick (with a hard buffer cap), so the send loop does one file append per half-second per worker — not one write per request. This is far cheaper than a per-request log queue (which would dispatch more jobs than the sends themselves), so logging stays in the worker. Keep it off in production unless actively debugging.

Run a blast

start() returns the run id. Spin up one queue worker process per worker — the process count must match the workers arg, since each job streams its own non-overlapping slice of the tokens.

Run locally

For development you don't need real Firebase credentials. Two modes:

1. Fake-token mode — leave credentials empty. The token provider returns a dummy bearer instead of minting a real OAuth token, so you can exercise the full dispatch/queue/counter pipeline without Firebase:

2. Mock endpoint — point the sender at a local HTTP server to load-test the engine without hitting FCM. Over plain http the 2tls setting auto-falls back to HTTP/1.1, so let the pool grow:

Start a worker and kick off a blast (one worker shown):

For multiple local workers, start that many queue:work processes:

Linux / macOS (bash/zsh)

Windows (PowerShell)

Run the test suite:

Run in production

Run the workers under a process supervisor instead of by hand, and make the process count match the workers you pass to start().

Supervisor (Linux)

/etc/supervisor/conf.d/fcm-blast.conf — numprocs=4 must match the workers you pass to start():

macOS (Homebrew supervisor)

Use the same [program:fcm-blast] block as above, adjusting command to your artisan path and user to your account.

Windows (production)

PowerShell Start-Process is fine for ad-hoc runs. For a managed service, wrap each queue:work in NSSM or run the workers inside WSL/Docker under Supervisor as above.

Monitor

throttled vs transportRetries tells you which ceiling you're hitting: throttled climbing = FCM project quota (request more); transportRetries climbing = network/connection limits (fewer connections, scale hosts). Both are retried automatically and only become failed once max_retries is exhausted.

A Laith343\FcmBlast\Events\FcmBlastCompleted event fires when a run finishes — listen for it to trigger follow-up work.

How it hits 10k RPS

• N parallel queue workers, each floor(rate_cap_per_sec / workers) RPS.
• Reused curl handle pool + persistent TCP — no curl_close per request, avoids ephemeral-port exhaustion.
• kreait OAuth token cached in your cache store, refreshed ~10 min before expiry under a lock (no per-request token fetch, no stampede).
• Paced token-bucket rate limiter per worker — refills continuously so sends are spread evenly across each second instead of bursting at the window edge. The burst is bounded by rate_burst (not by connection count), which keeps you under FCM's sub-second quota even with a large connection pool.
• Atomic delta counters flushed every 500 ms (UPDATE ... SET col = col + delta) — use Postgres/MySQL for concurrent worker writes.
• Exponential backoff + in-process retry for 429/503 and transient transport errors (timeouts, connection resets, send/recv failures), so network blips self-heal; 404/400 pruning via your handler.

Ephemeral port range (one-time host tuning)

At thousands of RPS the OS can run out of ephemeral ports for outbound connections. Widen the range once:

Windows (admin PowerShell)

Linux

macOS

The reused handle pool keeps sockets alive across requests, so this mainly matters during connection ramp-up and on hosts under other network load.