README

Laravel client package for sending events to a NotifyHub server.

Requirements

For Laravel 13, PHP 8.3+ is required by Laravel itself.

The package test matrix is validated on PHP 8.2 with Laravel 10–12, and PHP 8.3 / 8.4 with Laravel 13.

Installation

composer require snb4crazy/notifyhub-laravel

Publish the config file:

php artisan vendor:publish --provider="NotifyHub\\LaravelClient\\NotifyHubServiceProvider" --tag=notifyhub-config

If Laravel still reports no publishable resources, make sure package discovery is enabled in the consuming app and refresh Composer's autoload/package manifest.

Configuration

Add to .env in the sending app:

NOTIFYHUB_ENABLED=true
NOTIFYHUB_URL=https://your-notifyhub-server.example.com
NOTIFYHUB_INGEST_KEY=your_project_ingest_key
NOTIFYHUB_TIMEOUT=5
NOTIFYHUB_RETRY_TIMES=2
NOTIFYHUB_RETRY_SLEEP_MS=200

Optional auto-reporting of logged exceptions:

NOTIFYHUB_AUTO_REPORT=true
NOTIFYHUB_AUTO_REPORT_MIN_LEVEL=error

Usage

Send a plain event

use NotifyHub\LaravelClient\Facades\NotifyHub;
use NotifyHub\LaravelClient\Data\EventPayload;

NotifyHub::send(new EventPayload(
    title: 'Payment declined',
    message: 'Stripe returned error code card_declined',
    severity: 'error',
    eventType: 'payment.failed',
    application: config('app.name'),
    environment: app()->environment(),
    context: ['order_id' => $order->id],
));

Report an exception

try {
    $this->chargeCard($order);
} catch (\Throwable $e) {
    NotifyHub::sendException($e, ['order_id' => $order->id]);
    throw $e;
}

Or use the EventPayload factories directly:

NotifyHub::send(EventPayload::fromException($exception));
NotifyHub::send(EventPayload::fromFailedJob(SendEmail::class, $exception));
NotifyHub::send(EventPayload::fromFailedCron('nightly-sync', 'exit 1'));

Use the DI interface

use NotifyHub\LaravelClient\Contracts\NotifyHubClientInterface;

class MyService
{
    public function __construct(private NotifyHubClientInterface $notifyHub) {}

    public function doWork(): void
    {
        try {
            // ...
        } catch (\Throwable $e) {
            $this->notifyHub->sendException($e);
        }
    }
}

Send a raw array

NotifyHub::sendRaw([
    'title'    => 'Custom alert',
    'message'  => 'Something interesting happened',
    'severity' => 'info',
    'event_type' => 'custom.event',
]);

Integration in the Laravel exception handler

Add to bootstrap/app.php (Laravel 11+) or App\Exceptions\Handler (Laravel 10):

// bootstrap/app.php
->withExceptions(function (Exceptions $exceptions) {
    $exceptions->report(function (\Throwable $e) {
        rescue(fn () => app(\NotifyHub\LaravelClient\Contracts\NotifyHubClientInterface::class)
            ->sendException($e));
    });
})

Or in Laravel 10's app/Exceptions/Handler.php:

public function register(): void
{
    $this->reportable(function (\Throwable $e) {
        rescue(fn () => app(\NotifyHub\LaravelClient\Contracts\NotifyHubClientInterface::class)
            ->sendException($e));
    });
}

Event payload contract

Testing

composer test

License

MIT — see LICENSE.