signalstack/laravel

Laravel SDK for SignalStack error logging

1.0.0 2026-02-23 05:03 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0|^12.0

MIT

README

Laravel SDK for sending error logs to a SignalStack server.

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12

Installation

composer require signalstack/laravel

Publish the config file:

php artisan vendor:publish --tag=signalstack-config
php artisan config:clear

Configuration

Add these variables to your .env:

SIGNALSTACK_URL=https://your-signalstack-server.com
SIGNALSTACK_API_KEY=your-project-api-key
SIGNALSTACK_ENVIRONMENT=production
SIGNALSTACK_SOURCE=my-app
SIGNALSTACK_LEVEL=warning
SIGNALSTACK_EXCEPTION_HANDLER=true

All available variables

Variable	Default	Description
SIGNALSTACK_URL	http://localhost:8000	Your SignalStack server URL
SIGNALSTACK_API_KEY	—	Project API key (from the SignalStack dashboard)
SIGNALSTACK_ENVIRONMENT	APP_ENV value	Environment name sent with each error
SIGNALSTACK_SOURCE	APP_NAME value	Source identifier sent with each error
SIGNALSTACK_LEVEL	error	Minimum log level to capture (see note below)
SIGNALSTACK_TIMEOUT	5	HTTP request timeout in seconds
SIGNALSTACK_EXCEPTION_HANDLER	true	Auto-capture unhandled exceptions
SIGNALSTACK_QUEUE_ENABLED	false	Send errors via queue (recommended for production)
SIGNALSTACK_QUEUE_CONNECTION	null	Queue connection (database, redis, etc.)
SIGNALSTACK_QUEUE_NAME	default	Queue name to push jobs onto
SIGNALSTACK_BATCH_ENABLED	false	Accumulate errors and send in batches
SIGNALSTACK_BATCH_SIZE	10	Number of errors per batch

Important: SIGNALSTACK_LEVEL=error will silently drop warning, notice, info, and debug messages. Set to warning if you want to capture both warnings and errors.

Verify Connection

After configuring your .env, run:

php artisan signalstack:test

Expected output:

Sending test error to SignalStack...
Test error sent successfully!

Check the health of your SignalStack server:

php artisan signalstack:health

Usage

Facade

use SignalStack\Laravel\Facades\SignalStack;

SignalStack::error('Something went wrong');
SignalStack::warning('Disk space low', ['free_mb' => 512]);
SignalStack::critical('Database connection failed');

Capturing exceptions

use SignalStack\Laravel\Facades\SignalStack;

try {
    // ...
} catch (\Throwable $e) {
    SignalStack::captureException($e);
}

Unhandled exceptions are also captured automatically when SIGNALSTACK_EXCEPTION_HANDLER=true (the default).

As a Laravel log channel

Add the channel to config/logging.php:

'channels' => [
    'signalstack' => [
        'driver' => 'custom',
        'via' => \SignalStack\Laravel\Logging\SignalStackLogChannel::class,
    ],
    'stack' => [
        'driver' => 'stack',
        'channels' => ['daily', 'signalstack'],
    ],
],

Now Log::error(...) and Log::warning(...) automatically forward to SignalStack.

Artisan commands

# Send a test error to verify connectivity
php artisan signalstack:test

# Check the health of your SignalStack server
php artisan signalstack:health

Advanced

Queue mode (recommended for production)

Send errors asynchronously so they don't slow down user requests:

SIGNALSTACK_QUEUE_ENABLED=true
SIGNALSTACK_QUEUE_CONNECTION=database
SIGNALSTACK_QUEUE_NAME=default

Staging vs Production:

• On staging — set SIGNALSTACK_QUEUE_ENABLED=false. Errors are sent immediately via HTTP, no queue worker needed.
• On production — set SIGNALSTACK_QUEUE_ENABLED=true. Errors are dispatched to the queue and processed by Supervisor in the background, with zero impact on response time.

Make sure the SIGNALSTACK_QUEUE_NAME matches the queue your Supervisor worker is listening to.

Batch mode

Accumulate errors and send them in a single request instead of one-by-one:

SIGNALSTACK_BATCH_ENABLED=true
SIGNALSTACK_BATCH_SIZE=10

The batch is flushed automatically when it reaches the configured size, or when the application terminates.

Minimum log level

Only capture errors at or above a given severity:

# Accepted values (low to high): debug, info, notice, warning, error, critical, alert, emergency
SIGNALSTACK_LEVEL=warning

Context collection

Context fields collected automatically with each error (all enabled by default):

// config/signalstack.php
'context' => [
    'request_url'     => true,
    'user_id'         => true,
    'ip'              => true,
    'php_version'     => true,
    'laravel_version' => true,
    'hostname'        => true,
],

Safe usage in jobs and background processes

When using SignalStack inside queue jobs or any code where it must not affect core logic, use this safe pattern:

private function sendWarning(string $message, array $context = []): void
{
    try {
        if (!class_exists('SignalStack\Laravel\Facades\SignalStack')) {
            return;
        }
        $signalStack = 'SignalStack\Laravel\Facades\SignalStack';
        $signalStack::warning($message, $context);
    } catch (\Throwable $e) {
        Log::error('SignalStack failed: ' . $e->getMessage());
    }
}

This ensures:

• If the package is not installed → returns silently
• If the SignalStack server is down → caught and logged
• Core business logic is never affected

Troubleshooting

signalstack:test returns "Failed to send test error"

• Check SIGNALSTACK_URL is reachable from your server: curl https://your-signalstack-server.com/api/v1/logger/health
• Check SIGNALSTACK_API_KEY matches the project key in the dashboard
• Check the project is active in the SignalStack dashboard

Warnings are not appearing in the dashboard

• Check SIGNALSTACK_LEVEL — if set to error, warnings are silently dropped. Set to warning.
• Run php artisan config:clear after changing .env

Errors are sent but no Telegram/Slack notification received

• The notification channel may not be linked to the project in the dashboard
• Check the minimum notification level set on the channel (must be ≤ the error level being sent)
• Click Test Connection on the channel in the dashboard

Jobs stuck in queue / notifications delayed

• Queue worker is not running. Either start it (php artisan queue:work) or set SIGNALSTACK_QUEUE_ENABLED=false
• Clear stuck jobs: php artisan queue:clear
• Check Supervisor is running: sudo supervisorctl status