Download the PHP package thinwrap/notifications without Composer

thinwrap/notifications

Unified PHP facade over 35 notification providers across Email (10), SMS (10), Push (6), and Chat (9). Stateless. Zero vendor SDKs. Bring your own PSR-18 HTTP client.

Install

Requires PHP ≥8.2. PSR-18 HTTP client + PSR-17 factories are auto-discovered via php-http/discovery — if you don't already have one installed:

End-to-end example — 2-minute send

Switching providers

Change the NotificationProviderId case and config class; the EmailSendInput / SmsSendInput / PushSendInput / ChatSendInput shape stays identical.

Bring your own PSR-18 client

Inject any PSR-18 client through the client parameter on the *Config DTO — useful for tracing, mocking, or proxying through symfony/http-client.

php-http/discovery auto-detects an installed PSR-18 client (Guzzle, Symfony HttpClient, Buzz, etc.) when no $client is passed to the facade constructor.

The wrapper holds no state — no token cache, no connection pool, no retry buffer. The optional tokenCache hook on FcmConfig and ApnsConfig (the only two connectors with short-lived signed tokens) lets the consumer amortize signing cost; the hook owns the state, not the wrapper. See src/Providers/Fcm/README.md and src/Providers/Apns/README.md for hook shape.

Error handling

Every failure surfaces as ConnectorError with a typed ProviderCode. Compose your own retry strategy from $e->providerCode and $e->cause (which carries the raw Retry-After header where the vendor sets one). The wrapper performs no automatic retry.

The 6 ProviderCode cases are byte-exact across the TypeScript and PHP packages. ConnectorError extends \RuntimeException — catch (\Throwable $e) works too.

cause shape

$e->cause is a uniform array across every connector:

There is no top-level structured retryAfterSeconds field on ConnectorError — the wrapper performs no retry. The parsed seconds live inside $e->cause['retryAfterSeconds'] and are also echoed in $e->providerMessage (… (Retry-After: N seconds)). retryAfter carries the raw value verbatim (string|int|null) and is intentionally not normalized. Discord additionally exposes its body-sourced retryAfterBody (float) in cause.

Transport-layer failures (the PSR-18 client throwing before any HTTP response) are surfaced with a generic providerMessage (Upstream transport error) and only the exception class name in cause — never the raw client-exception message. That message can embed the full request URL, which for some providers (Telegram bot token in the path; Slack/Discord/Google Chat/Mattermost/MS Teams webhook URLs) is the credential. Do not log the raw HTTP-client exception directly for the same reason.

_passthrough escape valve

When the normalized input doesn't expose a vendor-specific field, forward arbitrary keys via the _passthrough parameter on the send input. Body merges deep, headers and query merge shallow, consumer values win on conflict. Keys are forwarded verbatim.

Each per-connector README documents vendor-specific _passthrough examples.

Bring your own connector

When _passthrough isn't enough — the provider isn't shipped at all — implement the channel's Contract\*ConnectorInterface (a single send() method over the normalized DTOs) and build the facade with fromConnector(). You keep the normalized input/result shapes and the uniform ConnectorError path; only the wire call is yours.

Throw ConnectorError from send() for hard failures so consumers keep a single error-handling path; return success: false for HTTP-2xx-but-rejected soft-rejects, matching the built-in connectors.

Language constraints (PHP)

• PHP 8.2 minimum; CI matrix runs on 8.2, 8.3, and 8.4 (Linux only at v1.0).
• PSR-18 HTTP client is BYO — php-http/discovery auto-detects Guzzle, Symfony HttpClient, Buzz, etc., when no $client is passed to the facade constructor.
• Zero runtime dependencies beyond psr/http-client + psr/http-factory + psr/http-message + php-http/discovery.
• 35 providers across 4 channels — same normalized facade surface as the TypeScript sibling @thinwrap/notifications. Novu drop-in compatibility (IEmailProvider / ISmsProvider / IPushProvider / IChatProvider) is a TypeScript-only feature; the PHP package does not implement Novu's provider interfaces.

Per-connector documentation

Each per-connector README documents auth, endpoints (regional / sandbox), narrowed input augmentations, error-code mappings, and _passthrough examples.

Email (10)

SMS (10)

Push (6)

Chat (9)

Baseline-coverage discipline

The unified facade surface includes only features ≥90% of providers in each channel support natively. Sub-baseline fields are accessible via per-provider narrowed input DTOs (<Provider>NarrowedInput) and the _passthrough escape hatch.

Migrating

From a vendor PHP SDK

Vendor-SDK conveniences (auto-retry, telemetry, idempotency-key generation) are intentionally absent — compose your own.

From hand-rolled HTTP / Guzzle

If you've been hand-rolling vendor HTTP calls with Guzzle, the facade collapses the boilerplate to one line per call. Error handling and retry composition stay yours; the PSR-18 client passes through unchanged via the facade constructor's $client argument.

From a previous Thinwrap PHP version

Not applicable at v1.0; thinwrap/notifications has not previously published. Forward looking: when v2.0 ships with breaking changes, this section will carry the v1→v2 recipe.

For AI agents and contributors

• .ai/guidelines.md — contributor entry point: how to add a connector.
• .ai/ARCHITECTURE.md — facade-dispatch-base pattern + invariants.
• .ai/CONVENTIONS.md — naming, file layout, test patterns.

AI agents working with this package should consult .ai/guidelines.md first.

Security

See SECURITY.md for private vulnerability disclosure. Releases are cosign-signed via GitHub Actions OIDC (no static signing keys); maintainer accounts require two-factor authentication (TOTP via an authenticator app) on GitHub. Packagist consumes the package via webhook auto-sync — no long-lived Packagist API token is stored anywhere.

License

MIT — see LICENSE.

Contributing

See CONTRIBUTING.md.