Runtime compatibility
How the package behaves in the PHP runtimes a Laravel application runs in, what was verified in this repository and how, and what was not. A runtime that was not run here is never called “supported”: its row says what the code is designed to do and what remains to be tested.
All measurements: PHP 8.3.6 CLI (NTS) with pcntl/posix, libcurl 8.5.0 (nghttp2), OpenSSL 3.0.13, Laravel 13.43, Node 22 (the local HTTP/2 mock server in tests/Support/H2Mock), redis-server 7 (local), SQLite. Every count of connections and requests below was read from the mock server, not from the package.
What “connection reuse” means here
CurlTransport keeps one persistent curl_multi handle per pool key (credential identity + endpoint role + environment + TLS/proxy profile + generation) in a per-process registry (CurlPoolRegistry::process(), a static). A connection is therefore reused only by later sends in the same OS process: across jobs of one queue worker, across requests of one long-lived HTTP worker. Nothing is shared between processes. The registry holds at most 32 pools by default (transport.max_pools; LRU; the evicted pool is closed), closes a pool idle longer than its max_idle_seconds, and abandons inherited pools when it notices a PID change. The manager keeps at most mobile-push.connection_cache.size (default 64) resolved connections and closes the pools of the one it evicts. See transport.md.
Reuse can be switched off: mobile-push.transport.reuse (auto by default, on, off). With off every send opens its own private pool (its own curl_multi handle and connection) and closes it when that send ends, so nothing is shared between concurrent callers and nothing is kept between sends. auto behaves as on, except for a send that starts while a coroutine runtime hooks curl (Swoole / OpenSwoole with SWOOLE_HOOK_CURL or SWOOLE_HOOK_NATIVE_CURL in its hook flags): that send runs as off. The price is one TCP + TLS handshake per send (measured on loopback: 200 sends → 200 connections instead of 1, about 3.1 ms instead of 0.6 ms per send) and, against APNs, many short connections, which Apple asks providers to avoid. Details in transport.md (“Connection reuse”).
Matrix
| Runtime | Connection reuse | Verified here, and how | Known limits | Required settings |
|---|---|---|---|---|
| PHP-FPM (and any one-request-per-process SAPI) | No reuse between requests. Within one request, yes (all the pushes of that request share the connection). | Not run under FPM. Follows from the design (per-process registry) and was read in source. | Every web request that sends pays a TCP + TLS handshake and, on a cold token cache, an APNs/Google token mint. With many pushes per request this adds latency to the user’s request. | Queue the sends (->queue(), notifications with ShouldQueue): the queue worker is the process that reuses the connection. A shared cache store (mobile-push.cache.store: redis, database, memcached) so that every FPM worker uses the same provider token instead of minting one per process. |
queue:work |
Yes, for the whole life of the worker. | Real process test (worker loop): Artisan::call('queue:work') (the real Illuminate\Queue\Worker daemon loop, in-process) on the database queue processed 2,000 light-profile SendPushJobs (10,000 in the slow group) through the real manager and the real CurlTransport → 1 connection for the whole run, 1 pool, 1 cached connection, memory growth after warm-up within 256 KiB of the same worker loop running empty jobs (the loop itself grows ~150 bytes per job in the test process, with or without the package), open descriptors unchanged (QueueWorkerRuntimeTest). Transport level, one process: 2,000 consecutive sends with idle gaps → 1 connection; memory growth < 256 KiB; descriptors unchanged; 20,000 sends in slow (LongLivedWorkerTest). Source: Worker::daemon() is a loop in one process, no fork (vendor/laravel/framework/src/Illuminate/Queue/Worker.php). |
Documented reconnects: after more than max_idle_seconds without a send (exactly one new connection, the old one closed); after the provider closes the connection (transparent, nothing lost when nothing was in flight). A job timeout kills the worker (SIGKILL), which ends its connections with it. |
Pass --memory above the process size (Laravel’s default 128 MB stops the worker early). Keep max_idle_seconds (default 3600) as is unless the network drops idle connections sooner. |
queue:listen |
No reuse between jobs. | Read in source: Illuminate\Queue\Listener starts a new queue:work --once process per job (Symfony Process / proc_open). |
Same cost as PHP-FPM per job. | Use queue:work in production. |
| Horizon | Yes, per worker process (Horizon workers run queue:work). |
Run in CI (runtimes job, Laravel Horizon 5 on a real Redis, the two supervisors mobile-push:install prints): the durable relay jobs were processed, carried the tags mobile-push, relay, scope:<scope>, effect:<id>, showed no device token in their payload, and doctor read the supervisor timeout and validated the whole timeout chain. Connection reuse across the jobs of one Horizon worker was not measured there (the sends were simulated); it follows from the queue:work measurement. |
As queue:work. |
As queue:work (memory in the supervisor config). |
| Octane + Swoole / OpenSwoole | Yes per worker process, without coroutine hooks (observed on Swoole 6.2 and OpenSwoole 26.11). | Run in CI (backends workflow, Laravel Octane 2.25 on Swoole 6.2, two workers, no coroutine hooks enabled): sixty HTTP requests each sent one simulated push (own result, default scope, sixty log records flushed per request), then sixty more each put one HTTP/2 request on the wire through the application’s transport to the local mock server, and then sixty more arriving eight at a time: the server counted 120 requests on 2 connections, one per worker. OpenSwoole 26.11 was run the same way with the same result. With Swoole’s coroutine hooks on (hook_flags = SWOOLE_HOOK_ALL, native curl hook included) a second request enters the worker while the first one waits inside curl. Two runs before transport.reuse existed, with one pool shared per worker: sixty sequential requests succeeded, but of sixty arriving eight at a time only 4 and 9 did, and the workers died with a fatal error in curl_multi_exec and were restarted. With transport.reuse = auto (the default), which gives such a send its own pool, the transport no longer fails: the mock counted one connection per send and no worker died inside curl. But the configuration is still not safe: in two runs 60 and then 55 of the sixty concurrent requests succeeded, the failed ones dying in Laravel’s container (Class "config" does not exist, Class "events" does not exist), because Octane keeps one application per worker and the requests a worker interleaves share it. That part is Octane’s, not this package’s to fix. mobile-push:doctor warns when Octane’s Swoole options turn a curl hook on. Also simulated: (1) Octane’s request sandbox (clone $app per request) → see “Octane-style sandbox” below; (2) two send() generators interleaved with PHP Fibers on one pool (the coroutine concern at the boundary between pushes) → correct (OverlappingSendsTest). |
Coroutine hooks are not supported for sending from HTTP workers: Swoole’s curl hooks (SWOOLE_HOOK_CURL / SWOOLE_HOOK_NATIVE_CURL) replace curl’s I/O and can switch coroutines inside a curl call — the case the Fiber simulation cannot reproduce. With transport.reuse at its default auto, a send that starts under such a hook gets its own pool instead of the worker’s shared one (one TCP + TLS handshake per send), so the transport itself holds; with on forced, concurrent requests crash the worker inside curl. Either way Octane’s per-worker application is shared by the interleaved requests and some of them fail (measured). Octane-specific state issues below. |
Run Octane workers without curl coroutine hooks for sending, or (safer) send from queue workers only. A shared cache store (not array). One scopeUsing() at boot (see below). |
| Octane + RoadRunner | Yes per worker process (RoadRunner workers are long-lived PHP processes, no coroutines). | Run in CI (runtimes job, Laravel Octane 2 on RoadRunner, two workers): sixty HTTP requests each sent one push; every request got its own result in the default scope, the two worker processes served all of them, and the database log sink held exactly sixty records afterwards, so each request’s records were flushed when that request ended. The pushes were simulated; sixty further requests each put one HTTP/2 request on the wire through the application’s transport to the local mock server, and sixty more arriving eight at a time, which the server counted as 120 requests on 2 connections (one per worker). No real provider was contacted. |
Octane-specific state issues below. | As Swoole, minus the coroutine rule. |
| Octane + FrankenPHP | Yes in the run below (worker mode; the registry is per thread under ZTS). | Run in CI (backends workflow, Laravel Octane 2.25 on FrankenPHP 1.14, whose binary embeds its own PHP — 8.6 in that run — and Caddy 2.11; two workers): the same two series as Swoole. Sixty simulated pushes with sixty log records, then sixty HTTP/2 requests through the application’s transport, and sixty more arriving eight at a time, which the mock server counted as 120 requests on 2 connections (one per worker thread). |
As above. | As RoadRunner. |
| AWS Lambda / Laravel Vapor | Designed: within one warm invocation container only; a frozen container may find its connection closed by the peer when it thaws. | Not verified, and not attempted: it needs an AWS account and a Vapor project to deploy to. Its usual backends were run against local emulators (SQS on ElasticMQ, DynamoDB Local as cache store; see queues). | A thawed container’s first send may hit a dead connection: libcurl detects it before reuse (measured on server-closed idle connections: transparent reconnect, nothing lost when nothing was in flight). Cold starts pay a handshake and a token mint. | Shared cache store (DynamoDB/redis) for tokens and guards; queue the sends (SQS worker). |
Forked children (pcntl_fork, spatie/fork, Laravel Concurrency::driver('fork')) |
Each child opens its own pools; the parent’s pools are put at risk by children that exit normally. | Real process test (ForkSafetyTest, see below). |
See “Fork” below. | Do not send from a process that forks, or close the pools before forking (MobilePush::flush()). |
How to check a runtime yourself
vendor/bin/pest tests/Scenario/Runtime # transport: worker life, fork, many tenants, overlapping sends
vendor/bin/pest tests/Scenario/Laravel/Runtime # queue:work, 200 runtime connections, request isolation, Octane sandbox, cache races
vendor/bin/pest tests/Scenario/Runtime tests/Scenario/Laravel/Runtime --group=slow # soak variants
They need Node ≥ 18 (mock server), pcntl/posix (fork scenarios) and, for the redis case of the cache race, redis-server + ext-redis (skipped otherwise). They prove the package’s mechanisms, not a runtime: to verify a runtime, run the same kind of scenario inside it (for Octane: a route that sends to a test endpoint, hit by many concurrent requests, counting the connections on the endpoint), and compare the server’s counters with the expectations above.
Scenario results
1. A queue worker that lives for a day
- Transport, one process: 2,000 batches of 5 requests on one pool key, a 300 ms pause every 250 batches → 10,000 requests received, 1 connection, memory growth after 200 batches < 256 KiB, open descriptors equal. Soak (
slow): 20,000 batches / 100,000 requests, same results. - Idle longer than
max_idle_seconds(1 s in the test) → exactly 2 connections in total, the old one closed. - The server closes the idle connection after each of 5 jobs → 20/20 requests answered, 5 connections (one reconnect per close, never more), no failure.
- Laravel: real
queue:workloop on thedatabasequeue, 2,000SendPushJobs → see the matrix.
2. Fork
- (a) Child sends while the parent sends (child ends with
SIGKILL): the child’s registry resets for its PID (CurlPoolRegistry::inheritedCount()= 1), it opens its own connection, the parent keeps one connection before, during and after; each process receives exactly the answers to its own request ids (the server echoes the request path in the body); 95/95 requests received and processed, 2 connections in total. - (b) Residual risk, reproduced: when a child exits normally, PHP’s shutdown frees the inherited curl handles; libcurl then reads from and writes a TLS
close_notifyon the socket the parent still uses.- parent idle at that moment: its connection is closed (server sees 0 open); the next send reconnects transparently, 3/3 answered;
- parent with 3 requests in flight: all 3 come back
Unknown(errno 55SSL_write: SSL_ERROR_ZERO_RETURN/ errno 65bad record mac), although the server processed all 3 (→OutcomeUnknown, possible duplicates if retried). The next send reconnects.
- Can the transport prevent it? No safe fix exists in PHP. The damage is done by
curl_multifree handlers during the child’s shutdown, which run for every live object even in fast shutdown, before and regardless of any code of the package; libcurl offers no option to drop a connection without the TLS shutdown, and PHP cannot close a raw descriptor in the child only (that would need FFI). A shutdown function that kills the child would change the child’s exit status and skip the application’s own shutdown work. The registry already never reuses or closes inherited pools itself. - Recommended patterns (both pinned by tests): close the pools before forking (
$transport->close()/MobilePush::flush()): the parent then sends on a fresh connection; or end children withposix_kill(getmypid(), SIGKILL)after their work. Best: do not send from a process that forks; let each worker open its own pools. - Laravel
queue:workdoes not fork;queue:listenand the framework’s process helpers useproc_open(read in source). Laravel’sConcurrencyfork driver (spatie/fork) does fork and its children exit normally: do not use it in a process that has sent pushes.
3. Two hundred tenants on one worker
- Transport: 200 pool keys in sequence, then all again: the server never saw more than 32 open connections (the registry limit) after each send, 400 connections in total (an LRU cycle longer than the limit reconnects every revisit), 368 evictions, each evicted pool closed (server-side close observed), process sockets = 32, descriptors and memory flat between the first and the second pass. A working set under the limit (8 tenants × 3 passes) → 8 connections, no eviction. Soak (
slow): 10 passes. - Laravel: 200 tenants registered at runtime (
MobilePush::register(..., scope)), each with its own APNs key, served twice: withconnection_cache.size16 the server never saw more than 16 open connections (the manager closes the pools of the drivers it evicts); with the default 64 above the registry’s 32, never more than 32. 400/400 accepted, memory growth on the second pass < 512 KiB, descriptors equal;MobilePush::flush()closes all. - The registry limit (32) is configurable:
transport.max_pools(envMOBILE_PUSH_TRANSPORT_MAX_POOLS, an integer of at least 1). With the default valueSendingModulebuildsnew CurlTransporton the shared per-process registry. With any other value it gives theTransportsingleton a dedicated registry of that size: its pools are no longer shared with otherCurlTransportinstances of the process, and live as long as that singleton. Raise it when one process serves many distinct connections or tenants (one pool per provider endpoint, credential and settings); the numbers measured above are for the default of 32 and have not been repeated for other values.
4. Overlapping sends in one process (simulated coroutines)
Two “requests” (PHP Fibers) each iterate their own send() on the same pool and yield to each other after every answer, so the generators overlap on one curl multi handle:
- 40 + 40 requests interleaved (the server received them alternating): every answer reached the generator that sent it, nothing lost or duplicated, one connection.
- One generator abandoned after 3 answers with requests still in flight: its streams were reset (
RST_STREAM, counted by the server), the other finished 30/30 correctly, the connection survived, the next send was correct. - A request suspended forever keeps its pool “in use” (never evicted;
close()defers until release); destroying its Fiber runs the generator’s cleanup and the deferred close happens. - Defect found and fixed (
CurlPool::perform()): while one generator waited for its answer and another, suspended generator had completions queued, the waiting generator skippedcurl_multi_select()and spun oncurl_multi_exec()for the whole wait (measured 0.15 s of CPU for a 0.4 s wait). The wait is now skipped only when the caller itself has a completion to take (measured < 1 ms of CPU). Pinned byOverlappingSendsTest. - Safe rule: concurrent sends on one pool are correct when the switching happens between pushes (Fibers, generators, a consumer starting a second send inside the first). Switching inside a curl call (Swoole curl hooks) on a shared pool is not supported and crashes the worker.
transport.reuse = off(orauto, the default, when a curl hook is detected) gives every send its own pool, so two coroutines never drive the samecurl_multihandle: measured under Octane on Swoole 6.2 with every hook on, the transport then never failed (one connection per send), while some concurrent requests still failed in Octane’s shared application container. Under such a runtime send from queue workers. - Reuse off, the same Fiber simulation (
tests/Scenario/Transport/ConnectionReuseTest.php): two interleaved sends of one pool key arrived on two server-side sessions, each sender’s requests on its own one, every answer to its sender; one abandoned half-way with requests in flight did not disturb the other; a send suspended forever held only its own connection, closed when its Fiber was destroyed; after every case the server saw 0 open connections and the transport 0 private pools.
5. State between requests (Octane-style)
Shared app (the app booted once, the same container for every request — a queue worker, or an Octane worker where the manager was resolved at boot), 40 tenants in a row, each request with scopeUsing(), a tenant resolver, its own key and device (RequestIsolationTest): every request sent only with its own scope, its own team/key JWT, to its own device; the PushBatchCompleted event and the log record carried its scope; the log buffer was empty after terminate(); one bearer per tenant, never another tenant’s. A tenant whose key is refused trips its auth breaker only (shared store, keyed by account): the next tenant is accepted, the refused tenant stays off the wire in its next request (Skipped / CircuitOpen).
Pinned limitations of a shared manager (the API is process-level, not request-level). The recommended pattern stays configure once, at boot; each of these has an undo for the cases where that is not possible:
- a request that does not call
scopeUsing()inherits the previous request’s scope → callscopeUsing()once at boot with a resolver that reads the current request (fn () => app(CurrentTenant::class)->id ?? 'default'). To remove a resolver, callMobilePush::scopeUsing(null)orMobilePush::forgetScopeResolver()(the scope then falls back tomobile-push.scope); eligibleUsing()called per request accumulates: every earlier check keeps running in later requests (FallbackPolicy::allowUsing()of the notifications module has the same shape) → register checks once, at boot. To remove one, pass the same callable toMobilePush::forgetEligibility($check)(it returns how many registrations it removed; a closure must be the very same instance).FallbackPolicy::forget($check)(same rules, returns the count removed) andFallbackPolicy::flush()(removes all) do the same for the fallback checks registered withallowUsing();register()keeps every runtime connection (with its key material) for the life of the process → for many tenants useresolveConnectionUsing()(resolved on demand, the drivers bounded by the cache). To drop one, callMobilePush::unregister($name, $scope)(it also drops the cached driver and closes its pools; a configured connection of the same name is used again from the next send); to drop a connection resolver,MobilePush::forgetConnectionResolver()(drivers already resolved through it stay cached untilforgetConnection($name)orflush()).
Octane sandbox (OctaneSandboxTest; Octane’s mechanism reproduced: clone $app per request, the clone bound as container and facade root, cloned config, terminate() at the end; Octane itself not installed):
- A manager resolved during the request lives only in that request: nothing set by one request was seen by the next (scope, runtime registrations). Connections still reused: 20 sandboxed requests → 1 connection, because the transport each request builds uses the per-process registry; one provider token for all of them when the cache manager is warm (Octane warms
cacheby default). - With the
arraycache store resolved per request, every request minted a new APNs token (3 requests → 3 tokens): Apple rejects frequent token updates (TooManyProviderTokenUpdates). Use a shared store. - A manager resolved at boot (e.g. by calling
MobilePush::resolveConnectionUsing()in a service provider) is shared by every sandbox: the limitations of a shared manager apply. - Defect found and fixed (Logging module): the terminating hook used to look at the application that booted the module, where a
SinkManagerresolved inside a sandbox is not visible, so the buffered records of a sandboxed request were lost with the clone. It now flushes theSinkManagerof the application being terminated (the sandbox); a test pins it.
Singletons registered by the package and what a long-lived process must know about them:
| Singleton | Shared state | Classification |
|---|---|---|
Transport (CurlTransport) |
pools in the static per-process registry | share (designed to be shared; with the default transport.max_pools the registry survives even a per-request transport, with another value the pools belong to the singleton) |
SendingSettings, HealthSettings, LiveActivitiesConfig, FrequencyLimits, EndpointCatalog |
config snapshot at first resolution | share; a config change at runtime needs forgetInstance() (as with any Laravel singleton) |
TokenIndex, TokenCipher, Redactor, ReceiptMarker |
key rings from config | share |
TokenStore (CacheTokenStore), GuardStore (CacheGuardStore), CacheHealth |
none (refresh locks only during a call; warning throttle) | share; the cache store behind them must be shared across processes (not array) |
Senders, Guards, Sender, SafeModeGuard, ConnectionFactory |
no per-request state (guard state is in the store) | share |
PushManager (PushDispatcher, facade MobilePush) |
scope resolver, tenant resolver, runtime registrations, consent checks, bounded connection cache | needs care: configure at boot only (see above); per-request calls to scopeUsing() / eligibleUsing() / register() leak or accumulate unless you undo them with forgetScopeResolver() / forgetEligibility() / unregister() (and FallbackPolicy::forget() / flush()). With Octane, either resolve it at boot and configure it once, or flush it per request (Octane flush list: Padosoft\MobilePush\Laravel\Sending\PushManager — but then connections are rebuilt per request; pools survive in the registry) |
SinkManager |
buffered log records, sink stats; static $extensions |
flushed when the application (or the Octane sandbox) terminates and after each queued job; share |
LogRecordFactory, LogPruner, DevicePruner, ActivityPruner, MessageVault, Rows |
none | share |
DatabaseLedger, DeviceRegistrar, DeviceOutcomeApplier, DeviceEligibility, ReceiptRecorder, ReceiptFunnelReader |
none in PHP (state in the database) | share |
ReceiptMarkerIssuer |
bounded set of message ids issued by this process | share (process-level by design) |
FrequencyCounter, FrequencyCapGate, PolicyGates, BadgeCounter, BadgeResolver |
none in PHP (state in the store) | share |
TypeRegistry, ActivityRegistry, ChannelRegistry, ActivityManager |
none per request | share |
MetricsRecorder |
60 s memo of known/rejected connection labels | share |
OpsAlerter |
local alert cooldowns, last seen sink failures | share (process-level by design) |
CredentialMonitor, HealthInspector, PrometheusExporter, MobilePushRecorder (Pulse), PushWatcher (Telescope) |
counters of their own failures | share |
FallbackPolicy (notifications) |
list of checks added by allowUsing() |
needs care: register at boot only (accumulates); undo with forget($check) / flush() |
ConnectionCredentialsSource (integration) |
closures over the manager | share |
TestingSession, StdinReader, XcrunRunner |
testing / console only | n/a |
Octane flush/reset hooks are not required for correctness when the package is configured at boot. They would be needed only for PushManager (if the application calls its setters per request).
6. Cache-backed coordination across real processes
Eight PHP processes (proc_open), each booting the application, start at the same instant on a cold store, ask for the APNs provider token and take 30 permits each (240 asked) from a rate limiter of 100 with a frozen clock (CacheCoordinationTest):
| Store | Exercised | Token | Permits granted |
|---|---|---|---|
redis (real redis-server, phpredis) |
yes | one token used by all 8 (1–8 signatures: on a cold store every process may sign, the compare-and-swap keeps one) | exactly 100 |
| database (shared SQLite file, WAL) | yes | one token | exactly 100 |
| file (shared directory) | yes | one token | exactly 100 |
memcached 1.6 (ext-memcached) |
yes, in CI (backends workflow) |
one token | exactly 100 |
dynamodb (DynamoDB Local, aws/aws-sdk-php) |
yes, in CI (backends workflow) |
one token | exactly 100 |
With the store unreachable: each process signs and uses its own token (the designed local fallback), and the rate limiter and the circuit breakers fail open: they cannot coordinate without the store, so they stop limiting instead of stopping the sends (every take is granted, nothing throws; measured with 8 processes against a port with nothing listening). After a failure the cache backend is left alone for 5 seconds, so a dead cache server does not cost a connection timeout on every send, and a warning is logged at most once a minute per process. A store that is alive but so contended that 50 compare-and-set attempts lose is a different case: nothing is granted and the destinations come back Deferred (quota_exceeded), never as an exception.
This was a defect found and fixed here: before the fix an unreachable store surfaced as RuntimeException('Guard state is too contended to update.') thrown out of the send.
Not verified
- AWS Lambda/Vapor (needs an AWS account), PHP-FPM (not run; the conclusion follows from the design). Octane on RoadRunner, Swoole, OpenSwoole and FrankenPHP is run in CI with sequential requests and with eight requests at a time, simulated pushes and a local HTTP/2 mock server on the wire: what a real provider connection does across their requests, and sustained production load, were not measured. Swoole’s coroutine hooks were run and are not supported for sending from HTTP workers (see the table): the transport holds with reuse off, Octane’s shared application does not. Horizon is run with simulated sends only.
- A worker running for real hours: idle periods were simulated with short pauses and a 1-second
max_idle_seconds; the libcurl default for idle reuse (118 s, overridden by the transport) and TCP keepalive were measured by the transport author (see transport.md), not re-measured here. queue:workwas run in the test process throughArtisan::call()(the real worker loop), not as a separatephp artisanprocess.- The cache stores against production services: memcached and DynamoDB were run against a local memcached and DynamoDB Local, Redis against a local
redis-server; MySQL/PostgreSQL as thedatabasecache store were not run.
This page is generated from docs/runtimes.md. To change it, edit that file in the repository, not this site.