dockcodes / dock-ray-laravel

1.3.0 2026-10-11 13:37 UTC

Requires

• php: ^7.4 || ^8.0
• dockcodes/dock-ray: ^1.4
• illuminate/contracts: ^6.0|^7.0|^8.0|^9.0|^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^6.0|^7.0|^8.0|^9.0|^10.0|^11.0|^12.0|^13.0

Requires (Dev)

• orchestra/testbench: ^4.0|^5.0|^6.0|^7.0|^8.0|^9.0|^10.0
• phpunit/phpunit: ^9.6|^10.0|^11.0|^12.0|^13.0

MIT

• Jacek Sultan

• laravel
• error-monitoring
• crash-reporting
• performance-monitoring

Published on Packagist.org on 2026-10-11 13:39 UTC

README

Reports Laravel exceptions and HTTP transactions to DockRay.

Installation

composer require dockcodes/dock-ray-laravel
php artisan vendor:publish --tag=ray-config

The service provider is discovered automatically.

Requires PHP 7.4 or newer and Laravel 6 through 13.

Configuration

RAY_TOKEN=project-token
RAY_PRIVATE_KEY=project-private-key
RAY_TRACES_SAMPLE_RATE=1

Without RAY_TOKEN and RAY_PRIVATE_KEY the package stays inert - no requests, no errors. Everything else lives in config/ray.php.

Reporting exceptions

Laravel 11–13 with the new bootstrap, in bootstrap/app.php:

use Dock\Ray\Laravel\Ray;

->withExceptions(function (Illuminate\Foundation\Configuration\Exceptions $exceptions) {
    $exceptions->reportable(fn (Throwable $e) => Ray::report($e));
})

Laravel 8, 9 and 10, in app/Exceptions/Handler.php:

public function register(): void
{
    $this->reportable(fn (Throwable $e) => Ray::report($e));
}

Laravel 6 and 7, in the same file - they have no register() hook:

public function report(Throwable $exception)
{
    Ray::report($exception);

    parent::report($exception);
}

Ray::report() never throws and never rethrows: a monitoring outage must not break the error handling it was called from. Exceptions listed in ray.ignore_exceptions are skipped, on top of Laravel's own dontReport.

Reporting anything by hand works the same way:

Ray::message('Nightly import finished late', \Dock\Ray\Severity::warning());

Transactions

The package includes ready-to-use middleware: Dock\Ray\Laravel\Http\Middleware\TrackTransaction. No application wrapper is required. Provider discovery alone does not enable transaction tracking. Register the middleware once in each route group you want measured.

Laravel 11–13 with bootstrap/app.php

use Dock\Ray\Laravel\Http\Middleware\TrackTransaction;
use Illuminate\Foundation\Configuration\Middleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->appendToGroup('web', TrackTransaction::class);
    // Optional, for ordinary application APIs:
    // $middleware->appendToGroup('api', TrackTransaction::class);
})

Applications with app/Http/Kernel.php

This also applies to upgraded Laravel applications that retain the old kernel. Add the middleware to the existing group, keeping its other entries:

protected $middlewareGroups = [
    'web' => [
        // Existing middleware...
        \Dock\Ray\Laravel\Http\Middleware\TrackTransaction::class,
    ],
];

Use route groups, not the global middleware stack: the middleware needs the matched route to name transactions (GET /orders/{order} instead of a separate name for every order). It measures downstream handling and records the response status. Exceptions escaping the middleware are not completed transactions; configure exception reporting separately as described above.

Configuration and verification

Set both project credentials and RAY_TRACES_SAMPLE_RATE=1 for the initial test. The rate defaults to 0 (disabled); 1 measures every eligible request and 0.1 measures approximately 10%. Incomplete credentials disable tracking.

After deployment or environment changes:

php artisan config:cache

Restart persistent application processes as appropriate for your deployment. Open an HTTP page such as /login, then check the project's transactions in DockRay. report(new RuntimeException(...)) in Tinker tests exceptions, not HTTP transactions. No queue worker is required for transaction delivery.

Published config/ray.php can exclude paths:

'ignore_transactions' => ['horizon*', 'telescope*', '_debugbar*', 'health*'],

When monitoring the DockRay server itself, never attach tracking to its ingest routes. Reporting a transaction about receiving a transaction creates a loop. For the DockRay panel, attach this middleware only to web, leaving ingest outside that group.

Optional application circuit breaker

The middleware emits Dock\Ray\Laravel\Events\TransactionStarting before starting a transaction. A listener can return false to skip tracking, for example while the application's reporting circuit breaker is open. Return null to allow other listeners to run. Register listeners in a service provider:

use Dock\Ray\Laravel\Events\TransactionStarting;
use Illuminate\Support\Facades\Event;

Event::listen(TransactionStarting::class, function (TransactionStarting $event) {
    // DockRay panel-specific service; not required by other applications:
    return app(\App\Support\Monitoring\SelfReport::class)->suspended()
        ? false
        : null;
});

After installing the release containing this event, the DockRay panel can replace App\Http\Middleware\TrackPanelTransaction in its web group with the package's TrackTransaction, register the listener above, and remove the wrapper class. Keep the existing exception hook and SDK logger: this event controls transactions only. Publishing this package does not update consuming applications; update their Composer lock file and deploy the updated dependencies too.

User context

The middleware attaches the authenticated user's id, e-mail and name. Turn it off with RAY_SEND_DEFAULT_USER=false, or replace it:

Ray::setUser(['id' => $account->id, 'username' => $account->slug]);

The IP address and user agent are only attached when RAY_SEND_DEFAULT_PII=true.

Queues and console

Both run outside the middleware stack, so they report errors but produce no transactions. The hub is a singleton for the whole process - a long-running queue worker keeps one client and one connection.

Tests

composer install
composer test

For development inside a consuming application, reuse its installed dependencies:

DOCKRAY_TEST_AUTOLOAD=/absolute/path/to/app/vendor/autoload.php \
    php /absolute/path/to/app/vendor/bin/phpunit -c phpunit.xml

The tests load this package's source, including when the consumer uses an optimized Composer classmap. Transport is replaced in tests; no requests leave the process. The local verification used Laravel 13 and PHP 8.5; it is not a compatibility matrix for all supported Laravel/PHP versions.

License

MIT.

Opt-in vulnerability monitoring (bridge 1.3+, PHP SDK 1.4+)

Enable package inventory with one option, alongside your existing project credentials:

RAY_INVENTORY=true

The bridge uses the configured APP_URL (config('app.url')) as the site URL. It must match the production or development URL configured for the DockRay project. Override it with RAY_INVENTORY_SITE_URL when needed. If configuration is cached, rebuild it with php artisan config:cache after changing these settings. Existing published config/ray.php files can add the following optional block; the package supplies defaults for installations without the block:

'inventory' => [
    'enabled' => (bool) env('RAY_INVENTORY', false),
    'site_url' => env('RAY_INVENTORY_SITE_URL'),
    'exclude_packages' => ['company/*'],
],

Keep Laravel's normal scheduler running (php artisan schedule:run every minute). The provider adds an hourly inventory check automatically; no requests are made while serving HTTP pages or booting the provider. A changed snapshot is sent on the next check; an unchanged snapshot is sent every 12 hours. To report immediately on deployment, or to check configuration:

php artisan ray:inventory --force

--force still respects retry backoff. Disable reporting with RAY_INVENTORY=false. The command prints only a sanitized status, never keys or the package payload.

The report includes PHP/agent/framework versions, the configured site URL, and only names and versions of installed production Composer packages. It requires composer.lock and installed Composer metadata, excludes dev dependencies and the root application, and supports exclusion patterns for private namespaces. It does not include code, .env, configuration, repository URLs, paths or users. It does not scan PHP extensions or the operating system. Excluded packages cannot be checked for vulnerabilities.

Delivery uses verified HTTPS, Bearer authentication, no redirects, short timeouts, size limits, retry backoff and a lock. Local timing/hash state is stored privately under storage/app/dockray/inventory; keep that directory persistent and outside the public web root. For multi-server deployments, run the scheduler on one server or use a shared filesystem for this lock.

DockRay maps Composer packages to its vulnerability database and closes findings after a fixed package version is reported. Confirmed findings use the project's existing notification recipients and channels, duplicate suppression and alert scheduler (currently every 15 minutes). Reporting is opt-in in every environment; use the appropriate project URL and credentials for each deployment.