Migrating from Pushok (edamov/pushok)
Pushok is a small, solid library: it speaks APNs over HTTP/2 with a token or a certificate and gives you back one response per notification. A lot of Laravel applications built their push on top of it, directly or through a notification channel. This page is for teams who want to move to padosoft/laravel-mobile-push without surprises: what maps to what, what behaves differently, and a plan that can be rolled back.
What I read. The Pushok README and the source of Payload, Notification, Payload\Alert, Client and Response at tag 0.19.1 (the latest tag I could list with git ls-remote --tags https://github.com/edamov/pushok), fetched from raw.githubusercontent.com. I did not run Pushok. Where I describe how Pushok behaves, it is what those files say; where I am not sure, I say so. If you use another version, check the method names against it.
Related pages: getting started, sending, messages, credentials for APNs, outcomes, testing, comparison, upgrading, and the sibling guide migrating from laravel-notification-channels/apn.
The model is different in three ways
- Typed, explicit destinations. Pushok takes a string token and a client built for one environment. Here a destination is a typed object (
ApnsDeviceToken,FcmToken, …) and the platform is always explicit:toToken(Platform::Ios, $token). A bare string is refused. The environment (production/sandbox) belongs to the connection and is declared, never guessed. - Outcomes instead of exceptions or raw responses. A send returns a report with one
SendResultper destination. A rejected token is a result, not an exception. Exceptions are only for input that is wrong as a whole (bad configuration, a malformed message, an invalid destination), raised before the network. - Safe by default. Outside production the package simulates: nothing is sent unless you opt in.
Side-by-side: sending
// Pushok 0.19.1
$alert = Alert::create()->setTitle('Hello!')->setBody('First push notification');
$payload = Payload::create()->setAlert($alert)->setSound('default')->setCustomValue('order_id', '1042');
$notifications = [];
foreach ($deviceTokens as $deviceToken) {
$notifications[] = new Notification($payload, $deviceToken);
}
$client = new Client($authProvider, $production = false);
$client->addNotifications($notifications);
$responses = $client->push(); // one Response per Notification
// This package
$report = MobilePush::toTokens(Platform::Ios, $deviceTokens)->send(
PushMessage::make('Hello!', 'First push notification')
->sound('default')
->data(['order_id' => '1042']),
);
$report->counts(); // consume the report: see "The report must be consumed"
use Padosoft\MobilePush\Core\Identity\Platform;
use Padosoft\MobilePush\Core\Message\PushMessage;
use Padosoft\MobilePush\Laravel\Facades\MobilePush;
$report = MobilePush::toTokens(Platform::Ios, [$iosToken])->send(
PushMessage::make('Hello!', 'First push notification')
->sound('default')
->data(['order_id' => '1042']),
);
$counts = $report->counts(); // consuming the report is part of sending
$fake->assertSentTimes(1);
Message API mapping
Pushok (Payload, Alert, Notification) |
This package |
|---|---|
Alert::setTitle(), setSubtitle(), setBody() |
PushMessage::make($title, $body) and ->subtitle(); or ApnsMessage::alert($title, $body, $subtitle) |
setTitleLocKey()/setTitleLocArgs(), setLocKey()/setLocArgs(), setActionLocKey() |
ApnsMessage::withAlert(Alert::localized(...)), Alert::withTitleLocalization(), withBodyLocalization() (see messages). I did not find an equivalent of action-loc-key |
setLaunchImage() |
Alert::withLaunchImage() |
Payload::setBadge($n) |
->badge($n) |
setSound('default') |
->sound('default'); critical sound: ApnsMessage::critical($name, $volume) or PushMessage::critical() |
setCategory($c) |
ApnsMessage::category($c) (APNs only) or PushMessage::actionCategory($c) (cross-platform; not the same as policy, see policies) |
setThreadId($id) |
PushMessage::group($id) or ApnsMessage::threadId($id) |
setInterruptionLevel() |
ApnsMessage::interruptionLevel(InterruptionLevel::TimeSensitive), or PushMessage::timeSensitive() / critical() |
setContentAvailability(true) |
ApnsMessage::background() or PushMessage::silent() (a silent push is content-available with priority 5) |
setMutableContent(true) |
->mutableContent() |
setCustomValue($k, $v), addCustomValue() |
PushMessage::data([$k => $v]); ApnsMessage::custom($k, $v) / data([...]) for non-scalar values |
setUrlArgs() |
no equivalent found (Safari web push is out of scope for this version) |
setRelevanceScore(), setStaleDate(), setTimestamp(), setContentState(), setEvent(), setAttributesType(), addAttribute(), setDismissalDate() (Live Activity fields on Payload) |
the Live Activities module, which also keeps the token registry and the rules: see live activities |
setPushType($type) |
ApnsMessage::pushType(PushType::...) or the factories (alert(), background(), voip(), widgetsReload(), …) |
Notification::setExpirationAt($dt) |
->expiresAt($dt) or ->ttl($seconds); ttl(0) means exactly one attempt, never stored by APNs |
setHighPriority() / setLowPriority() (10 / 5) |
->priority(MessagePriority::High) / Normal; APNs-specific: ApnsMessage::priority(Priority::...) |
setCollapseId($id) |
->collapse($key) (APNs collapse id, FCM collapse key) |
setId($uuid) (the apns-id) |
not settable per message. Provider message ids are derived deterministically from the effect key: set ->effectKey('...') and retries reuse the same id |
To reach APNs-only fields from a cross-platform PushMessage, use the overlay: PushMessage::make(...)->apns(fn (ApnsMessage $m) => $m->category('order')->threadId('orders')).
Responses and results
Pushok (Response) |
This package (SendResult) |
|---|---|
getStatusCode() (200, 410, 429, …) |
$result->httpStatus; and the classified $result->status (SendStatus: Accepted, Rejected, Failed, Deferred, OutcomeUnknown, Expired, Skipped, Simulated, Validated) |
getErrorReason() (Unregistered, BadDeviceToken, …) |
$result->reason->rawReason; the stable code is $result->reason->code (ReasonCode), and $result->reason->hint says what to do. php artisan mobile-push:explain Unregistered prints cause and remedy |
getApnsId() |
$result->providerMessageId |
getDeviceToken() |
the destination is masked in logs; $result->destination is the typed object (never print it) |
get410Timestamp() |
$result->invalidatedAtMs, plus $result->destinationAction (Invalidate / Quarantine / None) |
| a transport failure or a dropped connection | not an exception: Failed when it is known nothing was accepted, OutcomeUnknown when the request may have been accepted |
Read Accepted as “the provider accepted the request”, never as “delivered”. See outcomes.
use Padosoft\MobilePush\Core\Identity\Platform;
use Padosoft\MobilePush\Core\Message\PushMessage;
use Padosoft\MobilePush\Core\Outcome\SendStatus;
use Padosoft\MobilePush\Laravel\Facades\MobilePush;
$report = MobilePush::toToken(Platform::Ios, $iosToken)->send(PushMessage::make('Hi', 'There'));
$rejected = 0;
foreach ($report as $result) {
match ($result->status) {
SendStatus::Accepted, SendStatus::Simulated => null,
SendStatus::Rejected => $rejected++, // the provider refused it: see $result->reason
SendStatus::OutcomeUnknown => null, // it may have been accepted: NOT a failure, do not resend blindly
default => null, // Failed, Deferred, Expired, Skipped, Validated
};
}
expect($rejected)->toBe(0);
Configuration mapping
Pushok options (an array passed to AuthProvider\Token::create() or Certificate::create()) become one entry of mobile-push.connections. Secrets are sources (path, inline, base64 or resolver), never closures; see credentials for APNs and configuration.
| Pushok | config/mobile-push.php |
Notes |
|---|---|---|
key_id |
key_id |
|
team_id |
team_id |
required here for both token and certificate auth (Pushok needs it for the token only) |
app_bundle_id |
bundle_id |
the APNs topic |
private_key_path |
key => ['path' => ...] |
also inline, base64 or resolver |
private_key_secret |
no equivalent | the token-auth .p8 is read as Apple delivers it (an unencrypted PEM). I found no passphrase option for it. For a certificate the option is passphrase |
AuthProvider\Certificate + certificate_path |
auth => 'certificate', certificate => ['path' => ...] (+ certificate_key if separate) |
|
certificate_secret |
passphrase |
|
new Client($auth, $production) |
environment => 'production' or 'sandbox' |
explicit and per connection; it is not derived from APP_ENV and not guessed from the token |
setNbConcurrentRequests(n) |
window (default 100 requests multiplexed per window) |
transport settings can also be set globally in mobile-push.transport |
setMaxConcurrentConnections(n) |
max_connections (default 1) |
|
curl options such as CURLOPT_SSL_VERIFYPEER => false |
ca_bundle, proxy |
do not disable certificate verification; point the package at the right CA bundle |
// config/mobile-push.php
'connections' => [
'ios' => [
'driver' => 'apns',
'auth' => 'token',
'team_id' => env('MOBILE_PUSH_APNS_TEAM_ID'),
'key_id' => env('MOBILE_PUSH_APNS_KEY_ID'),
'key' => ['path' => env('MOBILE_PUSH_APNS_KEY_PATH')],
'bundle_id' => env('MOBILE_PUSH_APNS_BUNDLE_ID'),
'environment' => env('MOBILE_PUSH_APNS_ENVIRONMENT', 'production'),
],
],
Pushok’s README warns that its JWT goes stale after an hour and that you must regenerate it on long-running tasks. Here the provider token is cached, refreshed ahead of expiry and shared through the package cache; you do not manage it.
Behavioural differences a migrating team must know
- Simulation by default outside production.
mobile-push.modeisauto: live only whenAPP_ENV=production, otherwise every result issimulatedand nothing touches the network. A staging server that “worked” with Pushok will appear to send and deliver nothing until you opt in:MOBILE_PUSH_MODE=live,live.allow = trueon the connection and the test device tokens inlive.only_to; every other destination isSkipped. See safe mode. - Explicit platform and environment.
toToken(Platform::Ios, ...), never a bare string; the environment is part of the connection. A sandbox token on a production connection getsBadDeviceTokenand, with the device registry, the device is quarantined, not retried on the other endpoint (devices). - Statuses instead of exceptions. One destination failing never throws. Look at
$result->status. Only an invalid configuration, message or destination throws, before anything is sent. - The report must be consumed. A send returns a cursor over results. The first window of requests starts inside
send(), but the rest is pulled as you read: callcounts(),each(),results()or iterate it. Ignoring the report means ignoring the outcome (and, for a large stream, leaving work undone). Do not discard it. Acceptedis not delivered, andOutcomeUnknownis not a failure. When the connection drops after the request was written, the package cannot know whether APNs accepted it. It does not retry that blindly (only for replaceable messages, by default). Treatoutcome_unknownas its own bucket in your dashboards.- The package retries within a budget. Transient errors (5xx, throttling, expired provider token) are retried with backoff and jitter under a per-destination budget (
mobile-push.retry.*, retries and limits); a result is either final orDeferredwith a next attempt time. Remove your own retry loop around the call, or you will multiply attempts. - Dead tokens. Pushok hands you the 410 and its timestamp and you delete the token. Here, with the registry enabled,
Unregistered/ExpiredTokeninvalidate the row and routing mistakes quarantine it, automatically, comparing the 410 timestamp with the registration time. Without the registry you act on$result->destinationActionyourself. - Queues. Sending inside a request or a command is synchronous (
->send()); queue it with->queue($message)(light profile: encrypted jobs; durable profile: a ledger with idempotent retries). The package owns that queueing; do not wrap it in your own job that also retries. - Nothing is logged by default. Add a send log sink if you want one (observability); tokens are never written in clear, only a keyed index and a masked form.
A step-by-step plan, with a way back
- Inventory every place that builds a Pushok
Client/Notification(and the notification channels that wrap it). Note the connection each uses and what happens to the responses today. - Install and configure side by side.
composer require padosoft/laravel-mobile-push; add the connection as above using the same.p8key (it is just a key: nothing about it changes). Pushok stays installed. - Check the setup.
php artisan mobile-push:doctor(add--liveto send one real probe per connection), thenphp artisan mobile-push:connections. - Compare payloads without sending.
php artisan mobile-push:preview --connection=ios --title=... --body=...prints the headers and JSON the message compiles to; compare with what Pushok sent for the same notification. - Send to one test device for real, with the allowlist: set
MOBILE_PUSH_MODE=live,live.allowandlive.only_tofor that token, thenphp artisan mobile-push:send --platform=ios --connection=ios --stdin(exit codes: 0 ok, 1 partial, 2 invalid input, 3 simulated, 4 unknown outcome). - Switch one low-risk call site behind a flag (config value or feature flag), keeping the Pushok code path next to it. Consume the report: at minimum log the counts and every non-
Acceptedresult’sreason->code. - Move the rest, one notification at a time. Replace your retry and token-deletion code with the package’s (registry or
destinationAction). Decide whether you want the registry (devices) or keep your own token table and pass typed destinations. - Watch it. Enable a log sink and, if you use them, Pulse or Prometheus (observability). Look at the share of
outcome_unknownandrejectedby reason. - Remove Pushok (and its configuration) when nothing references it.
Rollback. While both libraries are installed, rolling back is flipping the flag of step 6 back: the key and the app are untouched. What is not undone by a rollback: rows already written (registry devices, durable-profile ledger rows, log rows), and the tokens the package invalidated or quarantined, which Pushok would have simply tried again. Keep a copy of the token table you had before step 7. Anything sent through the package was really sent; there is no “undo send”.
Not verified
Nothing in this package has run against real APNs or a real device; it is tested against a local HTTP/2 mock and a fake transport. The behaviour of Pushok described above comes from reading its source at 0.19.1, not from running it.
This page is generated from docs/migrating-from-pushok.md. To change it, edit that file in the repository, not this site.