ErrorVault Laravel Package

Send PHP exceptions to your ErrorVault dashboard for centralized error monitoring with automatic health monitoring and reliability features.

Installation

composer require errorvault/laravel

Configuration

Publish the config file:

php artisan vendor:publish --tag=errorvault-config

Add these environment variables to your .env file:

ERRORVAULT_ENABLED=true
ERRORVAULT_API_ENDPOINT=https://your-errorvault-portal.com/api/v1/errors
ERRORVAULT_API_TOKEN=your-site-api-token

Usage

Once configured, exceptions are automatically reported to ErrorVault. You can also manually report errors:

use ErrorVault\Laravel\Facades\ErrorVault;

// Report a custom error
ErrorVault::reportError('Something went wrong', 'warning', __FILE__, __LINE__);

// Report with additional context
ErrorVault::reportError(
    'Payment failed',
    'critical',
    __FILE__,
    __LINE__,
    ['order_id' => $orderId, 'amount' => $amount]
);

// Manually report an exception
try {
    // risky operation
} catch (\Exception $e) {
    ErrorVault::report($e, ['custom' => 'context']);
}

Verify Connection

use ErrorVault\Laravel\Facades\ErrorVault;

$result = ErrorVault::verify();

if ($result['success']) {
    echo "Connected to: " . $result['data']['site_name'];
} else {
    echo "Error: " . $result['error'];
}

Get Statistics

$stats = ErrorVault::stats();

if ($stats) {
    echo "Total errors: " . $stats['total_errors'];
    echo "New errors: " . $stats['new_errors'];
}

Reliability Features (v1.3.0+)

Automatic Heartbeat

The package automatically sends a lightweight ping every 5 minutes to keep your site's last_seen_at updated in the portal. This prevents your site from appearing offline.

Connection Failure Tracking

All API connection failures are automatically logged with:

• Timestamp and error message
• Consecutive failure counter
• Last 20 failures stored
• Admin notification after 5 consecutive failures

Artisan Commands

Test Connection

php artisan errorvault:test-connection

Tests connectivity to the ErrorVault portal and displays detailed results.

View Diagnostics

php artisan errorvault:diagnostics

Displays comprehensive diagnostics including:

• Configuration status
• Health monitoring settings
• Connection failure history
• Scheduled task information

Clear Failure Logs

php artisan errorvault:diagnostics --clear-failures

Clears all connection failure logs.

Send Health Report

php artisan errorvault:health-report

Manually trigger a health report to the portal.

Programmatic Access

use ErrorVault\Laravel\Facades\ErrorVault;

// Test connection
$result = ErrorVault::testConnection();
if ($result['success']) {
    echo "Connection successful!";
}

// Get connection failures
$failures = ErrorVault::getConnectionFailures();
foreach ($failures as $failure) {
    echo $failure['timestamp'] . ': ' . $failure['message'];
}

// Get consecutive failure count
$count = ErrorVault::getConsecutiveFailures();

// Clear failure logs
ErrorVault::clearFailureLog();

// Send heartbeat/ping
ErrorVault::sendPing(); // Non-blocking
ErrorVault::sendPing(true); // Blocking

Backups

Enable portal-requested backups and make sure Laravel's scheduler is running:

ERRORVAULT_BACKUP_ENABLED=true
ERRORVAULT_BACKUP_POLL_INTERVAL=5
ERRORVAULT_BACKUP_INCLUDE_STORAGE=false

The package polls the portal, exports MySQL, builds either a database-only or full-project ZIP, and uploads it in chunks. Full backups exclude vendor, node_modules, .git, caches, logs, .env, and storage/app by default. Set ERRORVAULT_BACKUP_INCLUDE_STORAGE=true only when files in storage/app must be included.

The working directory defaults to storage/app/errorvault-backup. A custom ERRORVAULT_BACKUP_TMP_PATH must be private and writable; paths under public or storage/app/public are refused.

Run a poll manually with:

php artisan errorvault:run-backup

Health Monitoring

Enable comprehensive server health monitoring:

ERRORVAULT_HEALTH_ENABLED=true
ERRORVAULT_CPU_THRESHOLD=80
ERRORVAULT_MEMORY_THRESHOLD=80
ERRORVAULT_REQUEST_RATE_THRESHOLD=1000
ERRORVAULT_HEALTH_INTERVAL=5

Health monitoring tracks:

• CPU load and usage
• Memory consumption
• Request rates and traffic spikes
• Disk space
• Potential DDoS attacks

Reports are automatically sent every 5 minutes (configurable) and alerts are triggered when thresholds are exceeded.

Configuration Options

Basic Options

Health Monitoring Options

Ignoring Exceptions

Add exceptions to the ignore array in config/errorvault.php:

'ignore' => [
    \App\Exceptions\IgnoredException::class,
],

Or use patterns to ignore by message content:

'ignore_patterns' => [
    'deprecated',
    'cache miss',
],

Scheduled Tasks

The package automatically registers the following scheduled tasks:

1. Heartbeat (every 5 minutes) - Keeps site active in portal
2. Health Report (configurable, default 5 minutes) - Sends health metrics
3. Backup poll (configurable, default 5 minutes) - Runs when backups are enabled

Ensure your Laravel scheduler is running:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Or use Laravel's queue worker in production.

Version History

• 1.4.2 - Hardened backups and exception traces; fixed backup scopes, failure reporting, exporter fallback, Laravel reporting filters, and health thresholds
• 1.4.1 - Reported system RAM rather than only PHP process memory
• 1.4.0 - Added database and full-project backups
• 1.3.0 - Added heartbeat/ping system, connection failure tracking, diagnostics commands, and reliability improvements
• 1.2.0 - Added comprehensive server health monitoring
• 1.1.0 - Enhanced error context and server information
• 1.0.0 - Initial release

License

MIT