snb4crazy/notifyhub-laravel

Laravel client package for sending events to a NotifyHub server.

v1.0.0 2026-06-19 21:21 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^10.0|^11.0|^12.0|^13.0
• illuminate/http: ^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^10.0|^11.0|^12.0|^13.0

Requires (Dev)

• guzzlehttp/guzzle: ^7.0
• mockery/mockery: ^1.6
• nunomaduro/collision: ^7.0|^8.0
• orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
• phpunit/phpunit: ^10.0|^11.0|^12.0

MIT

• Serhii Dymenko

• exceptions
• monitoring
• laravel
• alerting
• notifyhub

README

Laravel client package for sending events to a NotifyHub server.

Requirements

Dependency	Version
PHP	8.2+
Laravel	10, 11, 12, 13

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

Field	Type	Required	Notes
title	string	✓	Max 140 chars
message	string	✓	Max 5000 chars
severity	string	✓	info, warning, error, critical
event_type	string	–	e.g. laravel.exception, queue.failed
application	string	–	Identifies the sending app
environment	string	–	production, staging, local
context	object	–	Non-sensitive metadata (visible to all members)
sensitive_context	object	–	Stack traces, file paths (role-redacted on server)
fingerprint	string	–	For future deduplication/grouping
occurred_at	ISO 8601	–	When the incident happened

Testing

composer test

License

MIT — see LICENSE.