Urban Airship Bundle Laravel Package

Getting Started

First, an honest framing: this is a Symfony bundle, not a Laravel package. There is no service provider auto-discovery, no config/ publish tag, and no facade. The bundle's actual value is thin — it mostly wires the underlying Urban Airship PHP SDK (urbanairship/php-library or the newer REST wrapper) into Symfony's DI container with config-driven credentials. For a day-to-day Laravel workflow you will almost certainly skip the bundle and depend on the SDK directly, then reproduce the bundle's service wiring inside your own service provider.

Minimal path:

1. composer require urbanairship/php-library (or whatever the bundle's composer.json pins — check that file first; it is the single source of truth for what library version you are actually getting).
2. In the repo, read DependencyInjection/Configuration.php — it enumerates the config keys the bundle expects (typically app_key, master_secret, and an environment/development/production switch). Mirror these as config/urbanairship.php + .env entries.
3. Read Resources/config/services.yml to see the service ID and class the bundle exposes (usually a single UrbanAirship\Airship-style client). Bind that same class as a singleton in AppServiceProvider or a dedicated UrbanAirshipServiceProvider.
4. First use case: a broadcast push to a tag audience — create the client from config('urbanairship.app_key') and config('urbanairship.master_secret'), build a push with a notification payload and an audience selector, and call send(). Use the sandbox/dev environment flag first; you do not want to wake up 50k real devices while testing.

If you insist on using the bundle itself, you will need Symfony's kernel or a micro-Symfony alongside Laravel, which is not worth it for the ~50 lines of glue it provides.

Implementation Patterns

• Config as env, never code. The bundle reads credentials from DI parameters; in Laravel keep the same shape: config/urbanairship.php returning ['app_key' => env('UA_APP_KEY'), 'master_secret' => env('UA_MASTER_SECRET'), 'environment' => env('UA_ENV', 'development')]. Cache-safe because you only read env inside the config file.
• Bind a singleton client. Resolve the SDK client once in a service provider with $this->app->singleton(UrbanAirshipClient::class, fn () => new Airship(config(...))). The SDK client holds the HTTP transport; there is no reason to build one per request.
• Wrap it in a small domain service. Do not let controllers call $client->push()->setAudience(...) directly. Create App\Services\PushNotifier with methods like notifyUser(User $user, string $title, string $body) and notifyTag(string $tag, ...). This keeps the UA-specific audience/payload shapes out of your app code and makes swapping providers trivial.
• Store channel/device IDs in a devices table keyed by user_id + platform + token, with a last_seen_at. You need this for targeted pushes. The bundle does not manage device registration for you — it is purely server-side push sending.
• Queue the send. Wrap the UA call inside a ShouldQueue job (SendPushNotification). UA calls are network-bound and occasionally slow; doing them synchronously in a web request degrades UX and risks timeouts. Use a dedicated queue connection and a retryUntil tuned to your SLA.
• Segment with named tags, e.g. tag:user-{id}, tag:pref-news. UA supports named users and tags — the API wrapper exposes both audiences. Prefer tags/named users over maintaining a local subscriber list, since UA handles the intersection logic for you.
• Feature-test with a fake. Because the client is bound as a singleton, swap it in tests with a spy implementation that records the last push payload. Assert on audience + notification strings rather than hitting UA. Keep one manual integration test flagged @group integration for real credentials.
• Integration tip: if you also use UA for in-app automation or message center, the same client instance serves those endpoints — reuse the singleton, do not create parallel configs.

Gotchas and Tips

• Bundle ≠ Laravel package. This is the biggest pitfall. php artisan vendor:publish will not find it. Any tutorial mentioning app/AppKernel.php or services: urban_airship: is Symfony-only. Budget an hour to translate; it is small.
• Pin the transitive SDK version. With one star and zero dependents this project is effectively unmaintained. Lock the exact urbanairship/php-library commit in composer.lock and read its source once to know the method names — the bundle only exposes what the SDK already does.
• App key vs master secret vs bearer token. Older UA libs use HTTP Basic (app_key:master_secret), newer REST endpoints use an OAuth bearer token. If auth fails with a 401, first confirm which auth scheme the pinned SDK uses — the bundle's config keys may not map cleanly to a token flow.
• Environment flag is easy to forget. A dev app talking to production app key (or vice versa) is a classic "push doesn't arrive" bug. Make the env flag required with no default in config, and log it once at boot.
• Success is 202 Accepted, not 200. UA queues pushes; a queued response does not mean the push was delivered. If you need delivery confirmation, use the push ID returned and poll the reports endpoint — this is out of scope for the bundle, so wire it yourself if it matters.
• Payload size limits (~4 KB for iOS/APNS). Large extra/custom data silently truncates or errors depending on device type. Validate payload size in your service wrapper before calling UA.
• Config caching quirk (Laravel side). Once you run php artisan config:cache, editing .env is a no-op. Add config:clear to your deploy script before config changes, and never call env() outside config files.
• Credential leakage. Do not commit a config/urbanairship.php with secrets baked in from copying the bundle's example Symfony config. Use env() only.
• Extension points you would want but the bundle lacks: no events, no logging hook, no retry policy. Implement them in your wrapper (Log::info the push ID, wrap the call in retry(3, ...) with backoff), not in the bundle.
• If it breaks, debug at the SDK level, not the bundle level: echo the built payload JSON before calling send() and compare against UA's API reference. The bundle adds no logic that could be the culprit — it is only wiring.