Download the PHP package esanj/notification-client without Composer

Esanj Notification Client

Laravel client package for the Esanj Notification Microservice. Handles OAuth 2.0 token acquisition, automatic caching, token refresh, and retry logic out of the box.

Supports: Laravel 12 & 13 · PHP 8.2+

Installation

Publish the config file:

Configuration

Add the following variables to your .env file:

The first three are required. If any is missing when the client is resolved, you get a ConfigurationException naming the variable — not a TypeError from inside the package. NOTIFICATION_SERVICE_URL must be a full URL, and must use https:// when the app runs in production: the client-credentials call carries your client_secret, and plain HTTP hands it to anyone on the network path.

Full config reference (config/esanj/notification.php):

Token Management

Token handling is fully automatic:

1. On the first request the package fetches a token via the OAuth 2.0 client-credentials flow (POST /api/v1/oauth/token).
2. The response is validated before anything is cached — it must carry a usable access_token and a numeric expires_in longer than buffer_seconds. A response missing either is rejected with an AuthenticationException rather than cached as a token that is already expired.
3. The token is stored in your configured cache store with a TTL equal to expires_in - buffer_seconds. Set NOTIFICATION_TOKEN_ENCRYPT=true to encrypt that cache entry with your APP_KEY — worth doing when the store is shared with anything you don't fully trust.
4. A fast in-memory copy avoids cache I/O on subsequent calls within the same process.
5. Fetching happens behind a cache lock. When the cache is cold — a deploy, a Redis restart, an invalidation — one process fetches the token while the others wait and then read its result, instead of twenty workers hitting the throttled token endpoint at once.
6. If a request receives an HTTP 401, the package invalidates the cached token, fetches a fresh one, and replays the request once. A second 401 means the credentials themselves are wrong, so it throws instead of hammering the token endpoint.
7. An HTTP 403 is left alone: the token is valid, the client simply has no permission for that endpoint. Refreshing would drop a healthy token for nothing — see $e->isForbidden().
8. If all retries fail, an ApiException (or AuthenticationException) is thrown and the error is logged.

Retry & Idempotency

A lost response does not mean the service ignored the request. The service creates the notification and queues the job before it answers, so replaying a POST /api/v1/send that timed out sends the message a second time. The client therefore retries by method:

Waits grow exponentially and carry jitter: retry.sleep_ms doubles per attempt (1s, 2s, 4s… capped at 10s) with half of each delay randomised, so clients that fail at the same moment don't all retry at the same moment. A 429 keeps the server's Retry-After as the floor and adds up to a second of spread on top.

With idempotency.enabled = false (the default) a failed send throws after a single attempt. Handle it yourself — usually by letting the queued job retry with a key of your own, see below.

Set NOTIFICATION_IDEMPOTENCY=true only if the service honours the Idempotency-Key header and replays the original response for a repeated key. The client then sends a fresh key with every send and reuses it across that call's retries, so a duplicate never reaches your users.

For a send that your application itself can issue twice — a queued job that gets retried, a form the user double-submits — pass a stable key so both attempts collapse into one notification:

The same parameter exists on SendBatchNotificationData.

Usage

Dependency Injection (recommended)

Facade

Sending Notifications

SMS — plain message

SMS — pattern (template code)

Email

Push Notification

Using a Template (any channel)

Targeting a Specific Provider

Adding Tags

Batch Notifications

Querying Notifications

List with filters

Walk every page

eachNotification() pulls one page at a time and yields the items lazily, so the whole result set never has to fit in memory:

Driving the loop by hand works too — advance the filter, otherwise you keep re-fetching page 1:

Get single notification

Batches

Providers & Tags

Error Handling

All exceptions extend Esanj\NotificationClient\Exceptions\NotificationClientException.

Fields the service may legitimately leave empty are typed nullable rather than blowing up: providerName and providerChannel (null when the underlying provider record is gone), and updatedAt on notifications, batches and tags (null instead of being parsed into a fake "now").

RateLimitException and ApiException::isRateLimited() both carry $e->retryAfter — the server's Retry-After in seconds, or null when it didn't send one. It's exactly what $job->release() wants.

What the status codes mean

ApiException has a helper for each one, so you never have to compare $e->statusCode by hand:

isClientInputError() covers 400 and 422 — the two cases where the fix is in what you sent, not in retrying. Checking only isValidationError() silently misses the "no active provider" case.

Testing

The package integrates cleanly with Guzzle's MockHandler. In your feature tests:

Available Payload Classes

Resource Properties

NotificationResource

BatchResource

ProviderResource

TagResource

Documentation

For a complete, beginner-friendly, step-by-step walkthrough — installing, sending your first notification, building custom payloads, swapping the client implementation, testing, and troubleshooting — see docs/GUIDE.md.

Changelog

See CHANGELOG.md for release history.

License

MIT — © Esanj