Notificato Laravel Package

Getting Started

Notificato is a small, framework-agnostic APNS client for iOS push notifications. It speaks Apple’s legacy binary gateway and also exposes a feedback-service reader. It is not a Laravel package: there is no service provider, facade, config file, or notification channel. You wire it yourself.

It is archived (last release 2019-05-27) and built around the legacy binary APNS protocol, which Apple has retired. Treat it as legacy-maintenance only. If you inherit a codebase using it, start here:

1. Install with composer require wrep/notificato, or use a fork/VCS repository if the old constraints conflict with your PHP version.
2. Confirm ext-openssl and stream/SSL support are available. Test on your actual PHP version before relying on it.
3. Read src/Notificato/Notificato.php, PushMessage.php, and FeedbackService.php first. The README is short but shows the core flow.
4. Store the .pem certificate outside the web root, e.g. storage/app/certs/apns-production.pem, and keep the passphrase in .env.
5. Bind a singleton in a service provider so you are not loading the certificate and opening a connection per request.
6. Use a sandbox certificate and setSandbox(true) for your first single-device test.

Typical first use case — a transactional push to one stored device token:

use Notificato\Notificato;
use Notificato\PushMessage;

$notificato = new Notificato(
    config('services.apns.certificate'),
    config('services.apns.passphrase')
);
$notificato->setSandbox(config('services.apns.sandbox'));

$message = new PushMessage($deviceToken, 'Your order has shipped');
$message->setBadge(1);
$message->setSound('default');

$notificato->send($message);

Verify method names against the source for your pinned version; the package predates current PHP and Laravel conventions.

Implementation Patterns

Bind and configure once. Put certificate path, passphrase, and sandbox flag in config/services.php or a small config/notificato.php. Bind Notificato\Notificato as a singleton in AppServiceProvider. If you support multiple apps or environments, create named singletons or a small factory because each certificate/gateway pair must not be mixed.

Wrap it behind an interface. Do not scatter new Notificato(...) through controllers. Create an ApnsSender interface with a send(PushMessage $message) method and a concrete NotificatoSender. That keeps day-to-day usage clean and makes a later migration to an HTTP/2 client a one-class change.

Use a Laravel notification channel. The idiomatic Laravel pattern is a custom channel:

class ApnsChannel
{
    public function __construct(private ApnsSender $sender) {}

    public function send($notifiable, Notification $notification): void
    {
        $tokens = $notifiable->routeNotificationFor('apns');
        $message = $notification->toApns($notifiable);

        foreach ($tokens as $token) {
            $this->sender->send($token, $message);
        }
    }
}

Then a notification implements via() returning ApnsChannel::class and toApns(). This is the most maintainable day-to-day integration.

Queue every send. Push delivery involves an SSL handshake and network I/O. Implement ShouldQueue on the notification or dispatch a dedicated job. Add retries and backoff, but distinguish retryable connection errors from permanent invalid-token errors.

Model device tokens properly. Use a device_tokens table with user_id, token, environment, platform, invalid_at, and timestamps. Enforce a unique constraint on token + environment. Upsert on login/token-refresh; soft-delete or mark invalid on logout and feedback. Keep sandbox and production tokens separate.

Run the feedback loop. Schedule a daily Artisan command that calls the feedback service and marks returned tokens invalid:

foreach ($notificato->getFeedbackService()->receiveFeedback() as $feedback) {
    DeviceToken::where('token', $feedback->getDeviceToken())
        ->update(['invalid_at' => now()]);
}

This is the package’s main operational value beyond sending. Without it you keep pushing to dead tokens.

Keep the payload small and boring. Use alert, badge, sound, and custom data. Stay well under the legacy 2 KB payload limit. For silent pushes, omit the alert and use content-available; expect throttling.

Testing pattern. Bind a fake ApnsSender in tests and assert that the expected message was built. Reserve real APNS calls for a sandbox device and a manual integration check. Do not call Apple from CI.

Gotchas and Tips

• The protocol is retired. Notificato uses Apple’s legacy binary APNS gateway and feedback service. Apple shut that down; it will not work for current production APNS. Do not start new work with it. Isolate it and plan migration to a token-based HTTP/2 client such as Pushok or a maintained Laravel APN channel.
• Certificate-only auth. There is no .p8 token support. APNS certificates expire annually; put expiry monitoring on a calendar and alert well in advance.
• Sandbox vs production is easy to get wrong. Use the matching certificate, gateway, and device token environment. A production cert pointed at sandbox (or vice versa) usually produces connection/TLS failures or silent non-delivery.
• Feedback is not a complete error log. It reports tokens Apple has determined are invalid, but not every send failure. Wrap sends in try/catch, log the gateway/environment/token prefix, and check return values. Binary-protocol error reporting is coarse.
• No batching API. You build one PushMessage per token. For high volume, reuse the client where safe, run sends in queue workers, and watch connection timeouts and memory. Do not loop over thousands of devices in a web request.
• Payload failures are easy to miss. Invalid JSON, non-UTF-8 text, oversized payloads, and malformed custom data may fail at send time. Validate before sending and log the payload size.
• PHP 8 compatibility risk. The package predates modern PHP. Expect deprecations or fatal errors from old syntax and dynamic properties. Pin PHP, patch a fork, or containerize the legacy service.
• No Laravel auto-discovery. If something “just works” in another package, it will not here. Register bindings and config manually.
• Certificate handling. The PEM must contain the certificate and key, with the correct passphrase and restrictive file permissions. Never commit it. Test the certificate with openssl before debugging application code.
• Extension points are minimal. There are no events or hooks. Subclass or wrap the client. Emit your own Laravel events after send for auditing and metrics.
• Debugging checklist. Confirm sandbox flag, certificate fingerprint, gateway host, token environment, payload JSON, and queue worker logs. Test with a real device and inspect device console logs; server-side logs alone will not tell you whether APNS accepted the payload.
• If you must keep it running. Pin the package version, isolate it in a queue worker/container, process feedback daily, monitor certificate expiry, and keep the sender behind an interface so migration is contained.