Download the PHP package allanzico/laravel-helios without Composer

Laravel Helios

A lightweight, self-hosted monitoring tool for Laravel applications. Helios provides real-time monitoring of:

• Slow and failed requests
• Application Logs
• Queued Jobs
• Scheduled Tasks
• Slow Database Queries
• Health Checks
• Error Tracking

Features

• Real-time Monitoring: Track your Laravel application's performance in real-time
• Modern UI: Beautiful React-based dashboard with TanStack Router and Query
• Easy Installation: Simple Composer installation with automatic service provider registration
• Lightweight: Minimal overhead on your application
• Self-hosted: All data stays in your database
• Error Tracking: Automatic error grouping and tracking with detailed stack traces
• Queue Actions: Retry or forget failed queue jobs from the dashboard
• Scheduled Commands: Run known scheduled tasks manually when enabled

Requirements

• PHP 8.2 or higher
• Laravel 11.0 or higher (Laravel 11, 12, and 13 supported)
• MySQL/PostgreSQL database

Installation

1. Install via Composer

The service provider will be automatically registered via Laravel's package auto-discovery.

2. Run Migrations

This will create the following tables:

• helios_jobs - Track queued jobs
• helios_queries - Database query logs
• helios_requests - HTTP request tracking
• helios_scheduled_tasks - Scheduled task execution logs
• helios_task_definitions - Scheduled task definitions
• helios_health_check_settings - Health check configuration
• helios_errors - Error tracking and grouping

3. Open Helios

That's it! Frontend assets are automatically inlined (similar to Laravel Horizon), so no asset publishing is required.

Helios will try to discover scheduled tasks from Laravel's schedule automatically. If your app only exposes scheduled tasks through a console kernel, you can still sync them manually:

Note: If you're upgrading from an earlier version, clear your view cache: php artisan view:clear

Usage

Once installed, access the Helios dashboard at:

For local development:

Dashboard Features

• Overview: Problems-first health summary, failed jobs, errors, slow requests, and slow queries
• Operations: Health checks, queue status/actions, and scheduler monitoring/manual runs
• Performance: Request and query performance samples
• Events: Application logs and grouped errors

Local Playground

This repo includes a real Laravel playground app in playground/ that installs Helios through a local Composer path repository.

Then open:

To generate sample requests, queries, logs, errors, and a failed queued job:

Testing

Run the package test suite with:

Run the playground smoke tests with:

Configuration

Publishing Resources (Optional)

You can publish configuration and other resources if needed for customization:

Note: Asset publishing is not required. All CSS and JavaScript are automatically inlined in the HTML, similar to how Laravel Horizon works.

Configuration File

Optionally publish and customize the configuration file:

This creates config/helios.php:

Production Access

In production, define a viewHelios gate in your application:

Optional action-specific gates are also supported:

Environment Variables

Add to your .env file:

Queue Actions

Helios uses Laravel's configured failed-job provider for retry and forget actions. Actions are supported when the failed-job provider stores UUIDs that match Helios job IDs, such as database-uuids, file, and dynamodb.

Legacy numeric failed-job IDs from the database failed driver are shown as unsupported because Helios cannot safely map them back to the UUIDs emitted by Laravel queue events.

Error Tracking

Automatic error tracking is registered by the package service provider. You do not need to replace your application's exception handler.

Health Checks

Helios includes operational health checks for application boot, database, cache, Redis, disk space, storage writability, queue status, scheduler freshness, and environment configuration. Redis is skipped unless Redis is used by cache, queue, or session configuration, or HELIOS_HEALTH_REDIS_ENABLED=true.

The scheduler freshness check compares discovered scheduled tasks against their cron expressions. If a task was due within the configured lookback window but Helios has not recorded a scheduler-triggered run within the grace period, the check fails.

Purging Old Data

You can purge old monitoring data directly from the dashboard when HELIOS_ALLOW_PURGE_DATA=true, or programmatically:

Or use the built-in prune command:

Troubleshooting

"Unable to locate file in Vite manifest" Error

If you see an error like:

This error occurs when Laravel's Vite helper conflicts with Helios's custom asset loading. Helios uses inline assets (like Laravel Horizon) and does not use Laravel's Vite system.

Solution:

1. Clear Laravel caches:

2. Clear browser cache:

   • Hard refresh your browser (Ctrl+F5 or Cmd+Shift+R)
   • Or clear browser cache completely

3. Verify the package is properly installed:

4. If using Laravel Herd or Valet, restart the service:

5. Check your application's vite.config.js: Make sure your application's Vite configuration is not scanning the vendor directory. Your config should NOT include paths like vendor/**/*.blade.php.

Assets Not Loading

If the Helios dashboard appears blank or unstyled:

1. Verify migrations have run:

2. Clear view cache:

3. Check file permissions on the vendor directory:

Database Connection Errors

If you see database-related errors:

1. Ensure migrations have run:

2. Verify your database connection is configured correctly in .env

3. Check that your database user has permissions to create tables

Technical Architecture

Helios uses a modern tech stack:

Backend

• Laravel Package: Middleware for request tracking, event listeners for job monitoring
• Database: All monitoring data stored in your application's database
• Service Provider: Auto-discovery with automatic registration

Frontend

• React 18: Modern React with hooks
• TanStack Router: File-based routing with type safety
• TanStack Query: Efficient data fetching and caching
• Tailwind CSS v3: Utility-first styling
• Recharts: Data visualization
• Vite: Fast build tool and dev server

Asset Management

The package uses inline asset loading (inspired by Laravel Horizon). The @heliosAssets Blade directive reads the built CSS and JavaScript files from the package directory and embeds them directly into the HTML as <style> and <script> tags. This approach:

• Eliminates the need for asset publishing - No vendor:publish required
• Simplifies updates - composer update automatically updates frontend code
• Reduces HTTP requests - Assets are served with the initial HTML response
• Works in any environment - No public directory configuration needed
• Provides better caching - The entire page can be cached as one unit

Building from Source

If you want to modify the frontend or contribute to development:

Prerequisites

• Node.js 18+ and npm
• PHP 8.2+
• Composer

Setup

Development

For frontend development with hot module replacement:

The Vite dev server runs on http://localhost:5173 and proxies API requests to http://localhost:8000.

Building for Production

This creates optimized production assets in the public/ directory with:

• Minified JavaScript and CSS
• Content hashing for cache busting
• Vite manifest for dynamic asset loading