DEV Community: Guppylab

Push notifications the Laravel way: a custom APNs notification channel

Guppylab — Tue, 27 Oct 2026 13:00:00 +0000

In the first part we sent iOS push notifications straight to Apple: a .p8 key, a cached JWT, one HTTP/2 request inside a queued job. It works, but every place that sends a push has to know about tokens, devices and that job.

Laravel already has a better shape for this. Mail, SMS and Slack all go through notifications, and push can too. By the end of this post, this is all it takes:

$user->notify(new OrderShipped($order));

The notification lands on every iPhone the user is signed in on, a dead token cleans itself up, and a tap opens /orders/1234. No Firebase, no package. I ran it end to end on a real iPhone before writing this, and the channel, payload and endpoint tests below are the ones from that project.

What we're building

a device_tokens table, because people have more than one device
an endpoint the app calls to register its token
one APNs environment per token, so a development build and a store build can share a backend
an ApnsMessage, the push equivalent of a MailMessage
an ApnsChannel that turns one notification into one queued job per device
tests at three levels, none of which talk to Apple

ApnsClient and the SendPushNotification job come from part 1, with one small change in step 3.

1. Store one token per device

Schema::create('device_tokens', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->string('token')->unique();
    $table->string('environment')->nullable(); // 'sandbox' or 'production'
    $table->timestamps();
});

class DeviceToken extends Model
{
    protected $fillable = ['token', 'environment', 'user_id'];

    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}

On the User, the relationship plus the method the notification system calls to find where an apns notification should go:

public function deviceTokens(): HasMany
{
    return $this->hasMany(DeviceToken::class);
}

/** Every APNs token this user registered, one per device. */
public function routeNotificationForApns(): array
{
    return $this->deviceTokens()->pluck('token')->all();
}

2. Let the app register its token

When the app gets its raw APNs token (64 hex characters, see part 1 for why it must not be an FCM token), it posts it here, together with the APNs environment the build uses (more on that in step 3):

Route::post('/device-tokens', function (Request $request) {
    $data = $request->validate([
        'token' => ['required', 'string', 'regex:/^[0-9a-f]{64}$/i'],
        'environment' => ['nullable', 'in:sandbox,production'],
    ]);

    // A phone keeps its token when someone else signs in on it, so the token
    // moves to the new user instead of being added twice.
    DeviceToken::updateOrCreate(
        ['token' => strtolower($data['token'])],
        ['user_id' => $request->user()->id, 'environment' => $data['environment'] ?? null],
    );

    return response()->noContent();
})->middleware('auth:sanctum');

That comment is the whole point of the endpoint. The version most of us write first is $request->user()->deviceTokens()->firstOrCreate([...]). It works until two people share a phone: the second sign-in hits the unique index and the endpoint answers 500, or, without the index, the token belongs to both accounts and one person gets the other's notifications. The token identifies the device, not the user, so it is the key you look up by.

3. Sandbox and production, side by side

Part 1 picked the APNs host from one setting, APNS_PRODUCTION. That holds while every phone runs the same kind of build. It stops holding the day you have a development build on your own phone and the App Store build on your users' phones, both registering with the same backend: a sandbox token only works on api.sandbox.push.apple.com, a production token only on api.push.apple.com, and whichever way the switch points, one group gets BadDeviceToken. Eusebiu Balan pointed this out in the comments on part 1, and he's right: the environment belongs to the token, so it's stored next to it.

The client takes the environment as an argument and only falls back to the setting when it has none:

public function send(string $deviceToken, string $title, string $body, array $data = [], ?string $environment = null): Response
{
    // The token's own environment wins; APNS_PRODUCTION is the fallback.
    $production = $environment ? $environment === 'production' : config('services.apns.production');

    $host = $production
        ? 'https://api.push.apple.com'
        : 'https://api.sandbox.push.apple.com';

    // ...the rest is part 1, unchanged
}

And the job looks it up when it runs:

$environment = DeviceToken::where('token', $this->deviceToken)->value('environment');

$response = $apns->send($this->deviceToken, $this->title, $this->body, $this->data, $environment);

Looking it up in the job, instead of passing it through the channel, keeps the channel and routeNotificationForApns() as plain lists of tokens. A token that isn't in the table (an on-demand send, see step 6) or was registered without an environment simply gets the old behaviour.

The value itself has to come from the app, because only the signed build knows it: the aps-environment entitlement, development for sandbox and production for TestFlight and the App Store. Builds from Xcode carry it in their embedded provisioning profile; store builds don't have one and are always production.

4. The message

namespace App\Notifications\Messages;

class ApnsMessage
{
    public function __construct(
        public string $title,
        public string $body = '',
        public array $data = [],
    ) {}
}

$data is custom payload. It ends up next to aps, not inside it, which is where your app (and the deep link handling in it) will look.

5. The channel

A notification channel is any class with a send($notifiable, $notification) method:

namespace App\Notifications\Channels;

use App\Jobs\SendPushNotification;
use Illuminate\Notifications\Notification;
use Illuminate\Support\Arr;

class ApnsChannel
{
    public function send(object $notifiable, Notification $notification): void
    {
        $tokens = Arr::wrap($notifiable->routeNotificationFor('apns', $notification));

        if ($tokens === []) {
            return;
        }

        $message = $notification->toApns($notifiable);

        // One job per device: a dead token or a 503 retries that device only,
        // never re-sends to the phones that already got it.
        foreach ($tokens as $token) {
            SendPushNotification::dispatch($token, $message->title, $message->body, $message->data);
        }
    }
}

Two decisions in there are worth calling out.

The channel doesn't call Apple. It only fans out. The tempting alternative is to make the notification ShouldQueue and loop over the devices inside one job. Then the third of four devices gets a 503, the job retries, and devices one and two receive the same push again. With one job per device, each retry is scoped to the device that failed, and the per-reason handling from part 1 (delete on Unregistered, refresh the JWT on ExpiredProviderToken, back off on 429 and 5xx) keeps working as is.

Arr::wrap lets the same channel take a single token, which is what you get from an on-demand route (below).

Notification::extend('apns', fn ($app) => $app->make(ApnsChannel::class));

You could return ApnsChannel::class from via() instead, but a name is what makes routeNotificationForApns() and Notification::route('apns', ...) line up.

6. A notification

class OrderShipped extends Notification
{
    public function __construct(public Order $order) {}

    public function via(object $notifiable): array
    {
        return ['apns'];
    }

    public function toApns(object $notifiable): ApnsMessage
    {
        return new ApnsMessage(
            title: "Order #{$this->order->number} shipped",
            body: 'Arriving tomorrow. Tap to track.',
            data: ['link' => "/orders/{$this->order->number}"],
        );
    }
}

And now it's the line from the top:

$user->notify(new OrderShipped($order));

Because it's an ordinary notification, everything else Laravel does with notifications comes for free: via() can return ['apns', 'mail'], you can decide per user ($notifiable->wantsPush ? ['apns'] : ['mail']), and on-demand sending works without a user at all, which is handy for internal alerts and for trying a token out:

Notification::route('apns', $token)->notify(new OrderShipped($order));

Notice the notification itself is not ShouldQueue. All the channel does synchronously is one query and a few dispatch calls; the slow part, talking to Apple, is already queued per device.

7. Test it without Apple

Three levels, each one catching a different kind of mistake.

In your application's own tests, you usually only care that the right notification went to the right user (the route here stands for wherever your app ships an order):

Notification::fake();

$this->post("/orders/{$order->id}/ship");

Notification::assertSentTo($order->user, OrderShipped::class);

For the channel, fake the queue and check the fan-out:

public function test_it_queues_one_job_per_device(): void
{
    Queue::fake();

    $user = User::factory()->create();
    $user->deviceTokens()->createMany([['token' => str_repeat('a', 64)], ['token' => str_repeat('b', 64)]]);
    $order = Order::factory()->for($user)->create();

    $user->notify(new OrderShipped($order));

    Queue::assertPushed(SendPushNotification::class, 2);
    Queue::assertPushed(fn (SendPushNotification $job) => $job->deviceToken === str_repeat('b', 64)
        && $job->data === ['link' => "/orders/{$order->number}"]);
}

public function test_a_user_without_devices_gets_nothing(): void
{
    Queue::fake();
    $order = Order::factory()->create();

    User::factory()->create()->notify(new OrderShipped($order));

    Queue::assertNothingPushed();
}

For the wire format, fake HTTP and run the job. The JWT has to be signed with something, so generate a throwaway P-256 key in setUp() instead of pointing tests at your real .p8:

protected function setUp(): void
{
    parent::setUp();

    $key = openssl_pkey_new(['private_key_type' => OPENSSL_KEYTYPE_EC, 'curve_name' => 'prime256v1']);
    openssl_pkey_export($key, $pem);
    file_put_contents($path = tempnam(sys_get_temp_dir(), 'apns'), $pem);

    config([
        'services.apns.key_path' => $path,
        'services.apns.key_id' => 'TESTKEY123',
        'services.apns.team_id' => 'TEAM123456',
        'services.apns.bundle_id' => 'com.acme.app',
    ]);
}

public function test_the_request_matches_what_apns_expects(): void
{
    Http::fake(['api.sandbox.push.apple.com/*' => Http::response(status: 200)]);

    (new SendPushNotification(str_repeat('a', 64), 'Order #1234 shipped', 'Arriving tomorrow.', ['link' => '/orders/1234']))
        ->handle(app(ApnsClient::class));

    Http::assertSent(fn (Request $request) => $request->url() === 'https://api.sandbox.push.apple.com/3/device/'.str_repeat('a', 64)
        && $request->header('apns-topic') === ['com.acme.app']
        && $request['aps']['alert']['title'] === 'Order #1234 shipped'
        && ($request['link'] ?? null) === '/orders/1234');
}

public function test_an_unregistered_token_is_removed(): void
{
    Http::fake(['api.sandbox.push.apple.com/*' => Http::response(['reason' => 'Unregistered'], 410)]);

    $user = User::factory()->create();
    $user->deviceTokens()->create(['token' => str_repeat('c', 64)]);

    (new SendPushNotification(str_repeat('c', 64), 'Hi', 'There'))->handle(app(ApnsClient::class));

    $this->assertDatabaseMissing(DeviceToken::class, ['token' => str_repeat('c', 64)]);
}

public function test_each_token_goes_to_its_own_apns_host(): void
{
    Http::fake();
    config(['services.apns.production' => true]);

    $user = User::factory()->create();
    $user->deviceTokens()->createMany([
        ['token' => str_repeat('a', 64), 'environment' => 'sandbox'],   // dev build
        ['token' => str_repeat('b', 64), 'environment' => 'production'], // App Store build
    ]);

    (new SendPushNotification(str_repeat('a', 64), 'Hi', 'There'))->handle(app(ApnsClient::class));
    (new SendPushNotification(str_repeat('b', 64), 'Hi', 'There'))->handle(app(ApnsClient::class));

    Http::assertSent(fn (Request $request) => $request->url() === 'https://api.sandbox.push.apple.com/3/device/'.str_repeat('a', 64));
    Http::assertSent(fn (Request $request) => $request->url() === 'https://api.push.apple.com/3/device/'.str_repeat('b', 64));
}

These earn their keep. I broke the code on purpose to check: sending to the first device only fails the fan-out test, moving link inside aps (an easy slip when you build the payload) fails the wire-format test, and going back to the single APNS_PRODUCTION switch fails the host test. One more for the endpoint, signing two users in on the same phone with Sanctum::actingAs(), is what caught the firstOrCreate version returning 500.

Wrapping up

Part 1 was about talking to Apple. This part is about not having to think about it: a table for devices that remembers each token's environment, an endpoint that treats the token as the device's identity, a channel that fans out to one job per device, and $user->notify() everywhere else. Sending an iOS push now looks exactly like sending an email.

If you're building with NativePHP Mobile (v3 or v4), the app side of this is the plugin I sell, Push Direct: it registers with APNs directly on iOS (FCM on Android), hands you the raw token to post to the endpoint above along with its environment (Push::environment()), and delivers the payload, the tap and the cold start to your Livewire components, so that link opens the right screen even when the app was closed. It also handles action buttons, notification images and silent pushes. Full disclosure, it's paid. Everything in this post works without it.

Real road distance and travel time in Laravel with OSRM

Guppylab — Tue, 13 Oct 2026 13:00:00 +0000

"Nearest store" features usually sort by straight-line distance: the haversine formula, a few lines of trigonometry, no API. It's fast and it's wrong in a way users notice. A store across a river or on the other side of a highway looks close and isn't.

How wrong? From downtown São Paulo (Praça da Sé), measured with OSRM:

Destination	By road	Travel time	Straight line	Road vs. straight
Av. Paulista	3.8 km	7 min	2.6 km	+44%
Pinheiros	8.6 km	13 min	6.5 km	+33%
Santos	77.5 km	77 min	54.9 km	+41%

Worse than the error itself, the ranking changes: the store that is closest in a straight line is not always the one you reach first.

This post builds a small Laravel service that answers "how far, and how long, by road" from one origin to many destinations, in a single request, with caching and a straight-line fallback when routing isn't available.

OSRM in two minutes

OSRM (Open Source Routing Machine) is a fast, open source routing engine built on OpenStreetMap data. The piece we need is its table service: give it one origin and N destinations and it returns a matrix of distances (meters) and durations (seconds) in one call.

There's a public demo server at router.project-osrm.org, which is fine for trying things out but not allowed for production use. Running your own takes a region extract and four commands with Docker. For example, Southeast Brazil:

wget https://download.geofabrik.de/south-america/brazil/sudeste-latest.osm.pbf

docker run -t -v "${PWD}:/data" ghcr.io/project-osrm/osrm-backend osrm-extract -p /opt/car.lua /data/sudeste-latest.osm.pbf
docker run -t -v "${PWD}:/data" ghcr.io/project-osrm/osrm-backend osrm-partition /data/sudeste-latest.osrm
docker run -t -v "${PWD}:/data" ghcr.io/project-osrm/osrm-backend osrm-customize /data/sudeste-latest.osrm
docker run -t -i -p 5000:5000 -v "${PWD}:/data" ghcr.io/project-osrm/osrm-backend osrm-routed --algorithm mld /data/sudeste-latest.osrm

Pick the smallest extract that covers your users: preprocessing needs RAM roughly proportional to the region, and a country is a lot more than a state. Check the osrm-backend README for current images and flags.

A table request looks like this. Note the order: OSRM takes longitude first, then latitude.

GET /table/v1/driving/-46.6333,-23.5505;-46.6559,-23.5614;-46.6820,-23.5880?sources=0&annotations=duration,distance

sources=0 says "only the first coordinate is an origin", so you get one row back instead of an N×N matrix.

1. Configuration

// config/services.php
'osrm' => [
    'url' => env('OSRM_URL', 'http://localhost:5000'),
],

2. The service

<?php

namespace App\Services\Routing;

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Http;
use Throwable;

class RoadDistances
{
    /** How far OSRM may move a point to reach a road before we stop trusting the route. */
    private const MAX_SNAP_METERS = 500;

    /**
     * @param  array{lat: float, lng: float}  $origin
     * @param  list<array{id: int|string, lat: float, lng: float}>  $destinations
     * @return list<array{id: int|string, meters: int, seconds: int|null, routed: bool}>
     */
    public function from(array $origin, array $destinations): array
    {
        if ($destinations === []) {
            return [];
        }

        $key = 'road-distances:'.md5(json_encode([
            $this->rounded($origin),
            array_map(fn (array $d) => [$d['id'], ...$this->rounded($d)], $destinations),
        ]));

        if (($cached = Cache::get($key)) !== null) {
            return $cached;
        }

        $table = $this->table($origin, $destinations);
        $rows = [];

        foreach (array_values($destinations) as $i => $destination) {
            $meters = $table['distances'][0][$i + 1] ?? null;
            $seconds = $table['durations'][0][$i + 1] ?? null;
            $snapped = $table['destinations'][$i + 1]['distance'] ?? INF;

            $rows[] = $meters !== null && $seconds !== null && $snapped <= self::MAX_SNAP_METERS
                ? ['id' => $destination['id'], 'meters' => (int) round($meters), 'seconds' => (int) round($seconds), 'routed' => true]
                : ['id' => $destination['id'], 'meters' => (int) round($this->straightLine($origin, $destination)), 'seconds' => null, 'routed' => false];
        }

        // Only cache real answers. A fallback caused by an outage shouldn't stick for a day.
        if ($table !== null) {
            Cache::put($key, $rows, now()->addDay());
        }

        return $rows;
    }

    /** Great-circle distance in meters (haversine). */
    public function straightLine(array $from, array $to): float
    {
        $dLat = deg2rad($to['lat'] - $from['lat']);
        $dLng = deg2rad($to['lng'] - $from['lng']);

        $h = sin($dLat / 2) ** 2
            + cos(deg2rad($from['lat'])) * cos(deg2rad($to['lat'])) * sin($dLng / 2) ** 2;

        return 2 * 6371000 * asin(sqrt($h));
    }

    private function table(array $origin, array $destinations): ?array
    {
        $coordinates = collect([$origin, ...$destinations])
            ->map(fn (array $point) => $point['lng'].','.$point['lat'])
            ->implode(';');

        try {
            $table = Http::baseUrl(config('services.osrm.url'))
                ->timeout(5)
                ->get("/table/v1/driving/{$coordinates}", [
                    'sources' => 0,
                    'annotations' => 'duration,distance',
                ])
                ->throw()
                ->json();
        } catch (Throwable $e) {
            report($e);

            return null;
        }

        if (($table['code'] ?? null) !== 'Ok') {
            return null;
        }

        // An origin far from any road makes every route meaningless.
        return ($table['sources'][0]['distance'] ?? INF) <= self::MAX_SNAP_METERS ? $table : null;
    }

    /** ~11 m precision: close enough to share a cache entry, far enough to not lie. */
    private function rounded(array $point): array
    {
        return [round($point['lat'], 4), round($point['lng'], 4)];
    }
}

What it does:

One request for the whole batch. The table service returns every destination's distance and duration at once.
Never leaves the caller hanging. If OSRM is down, times out, or a destination has no route (OSRM returns null for that cell), that row falls back to straight-line meters with routed: false and seconds: null. Your UI can show "~6.5 km" instead of an ETA.
Doesn't trust a point that had to travel to find a road. OSRM never says "this point is in the ocean": it snaps every coordinate to the nearest road and routes from there. In my test, a point placed at sea was moved 62.8 km to a highway and came back as a perfectly normal 222 km route. The response tells you how far each point was moved (destinations[].distance, and sources[].distance for the origin), so anything moved more than 500 m falls back to straight line. Real addresses typically snap within a few dozen meters.
Caches real answers for a day, keyed by coordinates rounded to ~11 m. Users cluster around the same places, so a handful of upstream calls can serve a whole neighbourhood. Fallbacks are not cached, so a short outage doesn't stick.

OSRM durations come from road types and speed limits in OpenStreetMap, without live traffic. They're very good for ranking and for "about 15 min" estimates, not for promising an arrival time at rush hour.

3. An endpoint: stores sorted by travel time

<?php

namespace App\Http\Controllers;

use App\Models\Store;
use App\Services\Routing\RoadDistances;
use Illuminate\Http\Request;

class NearbyStoresController
{
    public function __invoke(Request $request, RoadDistances $roads)
    {
        $data = $request->validate([
            'lat' => ['required', 'numeric', 'between:-90,90'],
            'lng' => ['required', 'numeric', 'between:-180,180'],
        ]);

        $origin = ['lat' => (float) $data['lat'], 'lng' => (float) $data['lng']];

        // Pre-filter by straight line: routing 2,000 stores to show 10 is wasted work,
        // and osrm-routed caps table size (100 locations by default, see --max-table-size).
        $stores = Store::query()
            ->get(['id', 'name', 'lat', 'lng'])
            ->sortBy(fn (Store $store) => $roads->straightLine($origin, ['lat' => $store->lat, 'lng' => $store->lng]))
            ->take(25)
            ->values();

        $distances = collect($roads->from($origin, $stores->map->only(['id', 'lat', 'lng'])->all()))
            ->keyBy('id');

        return $stores
            ->map(fn (Store $store) => ['name' => $store->name, ...$distances[$store->id]])
            ->sortBy(fn (array $row) => $row['seconds'] ?? PHP_INT_MAX)
            ->values();
    }
}

// routes/api.php
Route::get('/nearby-stores', NearbyStoresController::class)->middleware('throttle:30,1');

GET /api/nearby-stores?lat=-23.5505&lng=-46.6333 now returns the 25 closest stores, ordered by how long it takes to drive there, with routed results first and straight-line estimates at the end.

With a few hundred stores, loading them all to pre-filter is fine. With thousands, do the first cut in SQL instead (a bounding box on lat/lng, or your database's spatial functions) and only rank the survivors.

Wrapping up

Straight-line distance is a fine first filter and a bad final answer. One OSRM table request, a day of cache and a haversine fallback give you real road distances and travel times without paying per request, and without your users discovering the river on their own.

If you're building a NativePHP Mobile app (v3 or v4), I packaged the on-device side of this as a plugin, Routing: on iOS it uses Apple's MapKit, on the device and free, and on Android you pick the provider: Mapbox, openrouteservice, Geoapify, Google, or an OSRM endpoint like the one in this post. Full disclosure, it's a paid plugin I built. Everything in this post works without it.

Push notifications on iOS without Firebase: talking to APNs directly from Laravel

Guppylab — Wed, 07 Oct 2026 02:47:29 +0000

Most push tutorials for iOS start with "add the Firebase SDK to your app". It works, but it means shipping Google's SDK inside your iOS binary just to forward a message to Apple, and keeping a second service configured for every app.

Your Laravel backend can talk to Apple Push Notification service (APNs) directly. All it takes is a .p8 key, a short-lived JWT and one HTTP/2 request. This post walks through the whole thing, including the two mistakes that cost the most time: the wrong token type and the wrong environment.

What you need

An Apple Developer account
Your app's bundle ID (for example com.acme.app)
An APNs .p8 key, its Key ID and your Team ID
The raw APNs device token from the iOS app (a hex string, more on that below)

1. Create the `.p8` key

In the Apple Developer portal, go to Certificates, Identifiers & Profiles → Keys, click +, give the key a name and enable Apple Push Notifications service (APNs). Register it and download the .p8 file.

You can only download it once, so store it somewhere safe. Write down:

the Key ID shown on the key page
your Team ID (top right of the portal, or under Membership)

Unlike the old .p12 certificates, the key does not expire every year. If the portal asks which environment the key is for, pick Sandbox & Production so the same key works for development builds and the App Store.

Keep the file out of public/ and out of git, for example in storage/app/private/apns/AuthKey.p8.

2. Configuration

// config/services.php
'apns' => [
    'key_id' => env('APNS_KEY_ID'),
    'team_id' => env('APNS_TEAM_ID'),
    'bundle_id' => env('APNS_BUNDLE_ID'),
    'key_path' => env('APNS_KEY_PATH', storage_path('app/private/apns/AuthKey.p8')),
    'production' => env('APNS_PRODUCTION', false),
],

APNS_KEY_ID=ABC123DEFG
APNS_TEAM_ID=TEAM123456
APNS_BUNDLE_ID=com.acme.app
APNS_PRODUCTION=false

The JWT is signed with ES256. Instead of converting OpenSSL's DER signature by hand, use firebase/php-jwt (just the JWT library, nothing to do with Firebase itself):

composer require firebase/php-jwt

3. The client

<?php

namespace App\Services\Apns;

use Firebase\JWT\JWT;
use Illuminate\Http\Client\Response;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Http;

class ApnsClient
{
    public function send(string $deviceToken, string $title, string $body, array $data = []): Response
    {
        $host = config('services.apns.production')
            ? 'https://api.push.apple.com'
            : 'https://api.sandbox.push.apple.com';

        return Http::withOptions(['version' => 2.0])
            ->withHeaders([
                'authorization' => 'bearer '.$this->providerToken(),
                'apns-topic' => config('services.apns.bundle_id'),
                'apns-push-type' => 'alert',
                'apns-priority' => '10',
            ])
            ->post("{$host}/3/device/{$deviceToken}", [
                'aps' => [
                    'alert' => ['title' => $title, 'body' => $body],
                    'sound' => 'default',
                ],
                ...$data,
            ]);
    }

    public function forgetProviderToken(): void
    {
        Cache::forget('apns.provider_token');
    }

    private function providerToken(): string
    {
        return Cache::remember('apns.provider_token', now()->addMinutes(50), fn () => JWT::encode(
            ['iss' => config('services.apns.team_id'), 'iat' => time()],
            file_get_contents(config('services.apns.key_path')),
            'ES256',
            config('services.apns.key_id'),
        ));
    }
}

A few details worth knowing:

HTTP/2 is required. APNs does not speak HTTP/1.1. ['version' => 2.0] tells Guzzle to use it, but only if PHP's cURL extension was built with HTTP/2 support (the nghttp2 library). Most recent systems have it; older shared hosting and some minimal Docker images don't. Check on the server that will send the pushes:

  php -r 'var_dump((bool) (curl_version()["features"] & CURL_VERSION_HTTP2));'

bool(true) means you're good. If it prints false, install a cURL/libcurl build with nghttp2 (or use a PHP image that ships one) before going further.

The provider token is cached. Apple rejects tokens older than an hour and also complains if you generate new ones too often. Caching for 50 minutes keeps you inside both limits.
apns-topic is your bundle ID. A wrong topic is rejected even if everything else is right.
Custom data goes next to aps, not inside it. The whole payload must stay under 4 KB.

4. Send from a queued job

Don't call APNs inside the request that triggered the notification. The user would wait for a round trip to Apple, and a slow or failing response would slow down your app. Put the send in a job, one job per device, so a bad token never blocks the others:

<?php

namespace App\Jobs;

use App\Models\DeviceToken;
use App\Services\Apns\ApnsClient;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use RuntimeException;

class SendPushNotification implements ShouldQueue
{
    use Queueable;

    public int $tries = 5;

    public function __construct(
        public string $deviceToken,
        public string $title,
        public string $body,
        public array $data = [],
    ) {}

    public function handle(ApnsClient $apns): void
    {
        $response = $apns->send($this->deviceToken, $this->title, $this->body, $this->data);

        if ($response->successful()) {
            return;
        }

        // Rate limited, or APNs is having a moment: try again later.
        if (in_array($response->status(), [429, 500, 503])) {
            $this->release($this->attempts() * 30);

            return;
        }

        $reason = $response->json('reason');

        match ($reason) {
            // The app was uninstalled or the token is no longer valid: stop sending to it.
            'Unregistered' => DeviceToken::where('token', $this->deviceToken)->delete(),

            // Usually a sandbox/production mismatch, see below. Don't delete the token yet.
            'BadDeviceToken' => logger()->warning('APNs BadDeviceToken', ['token' => $this->deviceToken]),

            // The cached JWT is too old: drop it and retry with a freshly signed one.
            'ExpiredProviderToken' => $this->retryWithFreshToken($apns),

            // Wrong Key ID, Team ID, bundle ID or key file. Retrying won't help; a human will.
            default => $this->fail(new RuntimeException("APNs error: {$reason}")),
        };
    }

    private function retryWithFreshToken(ApnsClient $apns): void
    {
        $apns->forgetProviderToken();
        $this->release(1);
    }
}

DeviceToken stands for wherever you store your users' tokens. Dispatching is one line, and the request returns immediately:

SendPushNotification::dispatch($deviceToken, 'Order shipped', 'Order #1234 is on its way.', ['order_id' => 1234]);

The job reads every answer from APNs and acts on it: retries with a backoff on 429 and 5xx, deletes tokens that are gone for good, refreshes an expired JWT, and fails loudly on configuration errors instead of retrying them five times.

The two mistakes that cost the most time

Wrong token type

APNs needs the raw APNs device token: 64 hex characters. If your iOS app already uses the Firebase SDK, the token you've been storing is probably an FCM registration token, and APNs will reject it.

In native Swift, the raw token is the Data you get in didRegisterForRemoteNotificationsWithDeviceToken, converted to hex:

let token = deviceToken.map { String(format: "%02x", $0) }.joined()

Wrong environment

A token issued for the sandbox only works on api.sandbox.push.apple.com, and a production token only on api.push.apple.com. Send to the other one and you get BadDeviceToken.

As a rule of thumb, builds you run from Xcode are sandbox, and TestFlight and App Store builds are production. But the entitlement that decides it lives in the signed binary, and with automatic signing it may not be what you think. Check it instead of guessing:

codesign -d --entitlements - /path/to/YourApp.app | grep -A1 aps-environment

development means sandbox, production means production. Point APNS_PRODUCTION at whatever the binary says.

Wrapping up

That's the whole integration: one key, one cached JWT, one HTTP/2 request inside a queued job, and a match on the reason when something goes wrong. No Firebase SDK in your iOS app, and no second dashboard to keep in sync.

If you're building with NativePHP Mobile, I packaged the app side of this as a plugin, Push Direct: it registers with APNs directly on iOS (FCM on Android), hands you the raw device token, and delivers the payload, the tap and the cold start to your Livewire components. Full disclosure, it's a paid plugin I built. Everything in this post works without it.

DEV Community: Guppylab

Push notifications the Laravel way: a custom APNs notification channel

What we're building

1. Store one token per device

2. Let the app register its token

3. Sandbox and production, side by side

4. The message

5. The channel

6. A notification

7. Test it without Apple

Wrapping up

Real road distance and travel time in Laravel with OSRM

OSRM in two minutes

1. Configuration

2. The service

3. An endpoint: stores sorted by travel time

Wrapping up

Push notifications on iOS without Firebase: talking to APNs directly from Laravel

What you need

1. Create the .p8 key

2. Configuration

3. The client

4. Send from a queued job

The two mistakes that cost the most time

Wrong token type

Wrong environment

Wrapping up

1. Create the `.p8` key