A modern Laravel logging package with multi-driver database support, web dashboard, and PHP attributes for declarative logging.
digitaldev-lx/log-hole is a Laravel package for a modern laravel logging package with multi-driver database support, web dashboard, and php attributes for declarative logging..
It currently has 2 GitHub stars and 13 downloads on Packagist (latest version v4.0.0).
Install it with composer require digitaldev-lx/log-hole.
Discover more Laravel packages by digitaldev-lx
or browse all Laravel packages to compare alternatives.
Last updated
LogHole is a modern, flexible Laravel logging package with multi-driver database support. Designed for seamless integration with Laravel's Log facade, it provides a web dashboard for browsing logs, an Artisan command for CLI access, and PHP 8.4+ attributes for declarative method-level logging.
/log-hole with Tailwind CSS v3 and Alpine.js (dark/light mode, filters, stats, auto-refresh)log-hole:tail to query and purge logs from the CLI#[Loggable] for declarative method and class-level logging via middlewareLogDriverInterface for extensibilityESCAPE clause — wildcards in search terms are always treated literally| Release | PHP | Laravel | |---------|--------|----------------| | 4.x | >= 8.4 | 13.x | | 3.x | >= 8.4 | 11.x, 12.x | | 2.x | >= 8.2 | 10.x, 11.x | | 1.x | >= 8.2 | 10.x |
Supported databases: MySQL, MariaDB, PostgreSQL, SQLite, SQL Server
Install the package via Composer:
composer require digitaldev-lx/log-hole
Publish the configuration file:
php artisan vendor:publish --tag="log-hole-config"
Run the migration to create the logs_hole table:
php artisan migrate
After publishing, the configuration file is located at config/log-hole.php:
return [
'database' => [
'driver' => 'custom',
'via' => DigitalDevLx\LogHole\Channels\DatabaseChannel::class,
'level' => env('LOG_LEVEL', 'debug'),
'table' => 'logs_hole',
],
// Database connection to use for logs (null = default connection)
'connection' => env('LOG_HOLE_DB_CONNECTION', null),
// Emails of users authorized to access the dashboard (empty = open access)
'authorized_users' => [],
// Route prefix for the dashboard
'dashboard_route' => 'log-hole',
// Number of logs per page in the dashboard
'per_page' => 25,
// Auto-refresh the dashboard every 5 seconds
'auto_refresh' => false,
// Cache TTL (in seconds) for the stats() query. 0 disables caching.
// Useful when the dashboard auto-refreshes against a large logs table.
'stats_cache_ttl' => env('LOG_HOLE_STATS_CACHE_TTL', 0),
];
Add the LogHole database channel to your config/logging.php:
'channels' => [
// ... other channels
'database' => config('log-hole.database'),
],
Then set the channel as your default (or use it alongside other channels):
Option A - Set as default channel in .env:
LOG_CHANNEL=database
Option B - Use as part of a stack:
'channels' => [
'stack' => [
'driver' => 'stack',
'channels' => ['single', 'database'],
],
'database' => config('log-hole.database'),
],
Option C - Log to the database channel on demand:
use Illuminate\Support\Facades\Log;
Log::channel('database')->info('This goes to the database');
If you want logs stored in a different database, set the environment variable:
LOG_HOLE_DB_CONNECTION=mysql_logs
Make sure the connection is defined in config/database.php and the migration has run on that connection.
On a logs table with millions of rows, the per-level COUNT(*) query that powers the dashboard's stats bar is expensive. With dashboard auto-refresh on, it runs every 5 seconds per visitor.
To cache the stats query, set a positive TTL:
LOG_HOLE_STATS_CACHE_TTL=5
The driver uses Laravel's default cache store under the key log-hole:stats:{connection}:{table}.
use Illuminate\Support\Facades\Log;
// If 'database' is your default channel
Log::info('User logged in', ['user_id' => 1]);
Log::error('Payment failed', ['order_id' => 42, 'reason' => 'timeout']);
Log::warning('Disk space running low');
// Or target the database channel explicitly
Log::channel('database')->debug('Debug info', ['context' => 'value']);
All standard log levels are supported: emergency, alert, critical, error, warning, notice, info, debug.
LogHole provides the #[Loggable] PHP attribute for declarative logging on controller methods and classes. When the LogHole middleware is active, annotated actions are automatically logged after the request is handled.
In bootstrap/app.php:
use DigitalDevLx\LogHole\Middlewares\LogHoleMiddleware;
return Application::configure(basePath: dirname(__DIR__))
// ...
->withMiddleware(function (Middleware $middleware) {
$middleware->append(LogHoleMiddleware::class);
})
->create();
Older Laravel setups (10.x with
app/Http/Kernel.php) are supported by LogHole^2.0. v3 and v4 expect the Laravel 11+ middleware bootstrap layout.
use DigitalDevLx\LogHole\Attributes\Loggable;
class OrderController extends Controller
{
#[Loggable(message: 'Order was created', level: 'info')]
public function store(Request $request)
{
// ... your logic
}
#[Loggable(message: 'Order was deleted', level: 'warning')]
public function destroy(Order $order)
{
// ... your logic
}
}
Apply the attribute to the class to log all controller actions:
use DigitalDevLx\LogHole\Attributes\Loggable;
#[Loggable(level: 'info')]
class UserController extends Controller
{
public function index() { /* logged automatically */ }
public function show(User $user) { /* logged automatically */ }
}
Method-level attributes take precedence over class-level attributes.
| Parameter | Type | Default | Description |
|------------------|-------------------|----------------|--------------------------------------------------|
| message | string | '' | Custom log message. If empty, uses "{method} was called" |
| level | LogLevel\|string | LogLevel::Info | Log level (enum or string like 'error') |
| includeRequest | bool | false | Include request method, URL, and IP in context |
| channel | ?string | null | Target a specific log channel (null = default) |
use DigitalDevLx\LogHole\Attributes\Loggable;
use DigitalDevLx\LogHole\Enums\LogLevel;
#[Loggable(message: 'Critical action', level: LogLevel::Critical, includeRequest: true)]
public function dangerousAction()
{
// ...
}
The LogHole dashboard provides a modern web interface for browsing and filtering logs.
URL: /log-hole (configurable via dashboard_route in config)
By default, the dashboard is open to everyone. To restrict access, add authorized emails to the config:
'authorized_users' => [
'[email protected]',
'[email protected]',
],
When the list is not empty, only authenticated users with matching emails can access the dashboard. Unauthenticated users or users not in the list will receive a 403 error.
LogHole also registers a viewLogHole Gate that you can use in your own authorization logic:
if (Gate::allows('viewLogHole')) {
// user can view logs
}
The log-hole:tail command allows you to query and purge logs directly from the CLI.
php artisan log-hole:tail {options}
| Option | Description |
|-----------------|----------------------------------------------------------|
| --emergency | Filter by EMERGENCY level |
| --alert | Filter by ALERT level |
| --critical | Filter by CRITICAL level |
| --error | Filter by ERROR level |
| --warning | Filter by WARNING level |
| --notice | Filter by NOTICE level |
| --info | Filter by INFO level |
| --debug | Filter by DEBUG level |
| --from= | Start date filter (e.g., 2024-10-01) |
| --to= | End date filter (e.g., 2024-10-31) |
| --take= | Limit the number of entries (default: 10, clamped 1-1000) |
| --purge | Purge all logs (asks for confirmation) |
If no level option is specified, all levels are returned.
Fetch the last 10 logs (default):
php artisan log-hole:tail
Fetch error-level logs from a date range:
php artisan log-hole:tail --error --from=2024-10-01 --to=2024-10-31
Fetch the last 5 critical logs:
php artisan log-hole:tail --critical --take=5
Purge all logs (with confirmation prompt):
php artisan log-hole:tail --purge
The command displays logs in a table with the following columns:
+-----------+----------------------------------+----------------------------+---------------------+
| Level | Message | Context | Logged At |
+-----------+----------------------------------+----------------------------+---------------------+
| ERROR | Payment failed | { | 2024-10-15 14:30:00 |
| | | "order_id": 42, | |
| | | "reason": "timeout" | |
| | | } | |
| WARNING | Disk space running low | | 2024-10-15 14:25:00 |
| INFO | User logged in | { | 2024-10-15 14:20:00 |
| | | "user_id": 1 | |
| | | } | |
+-----------+----------------------------------+----------------------------+---------------------+
Context is displayed as pretty-printed JSON for readability.
LogHole uses the Strategy Pattern for database access. All drivers implement LogDriverInterface:
use DigitalDevLx\LogHole\Drivers\Contracts\LogDriverInterface;
The DriverFactory auto-detects your database driver and returns the appropriate implementation:
| Database | Driver Class | Context search strategy |
|------------|--------------------|--------------------------------------------|
| MySQL | MySqlDriver | CAST(context AS CHAR) LIKE ? ESCAPE ? |
| MariaDB | MariaDbDriver | Inherits MySQL strategy. Auto-detected via PDO version string, or matched by the explicit mariadb driver name |
| PostgreSQL | PostgreSqlDriver | context::text ILIKE ? ESCAPE ? (case-insensitive Unicode) |
| SQLite | SqliteDriver | IFNULL(context, '') LIKE ? ESCAPE ? |
| SQL Server | SqlServerDriver | CAST(context AS NVARCHAR(MAX)) LIKE ? ESCAPE ? |
All drivers use ~ as the LIKE escape character — chosen for portability across MySQL/Postgres/SQLite/SQL Server string-literal handling. User-facing search semantics are unchanged: %, _, and ~ typed into the search box are matched literally.
The driver is registered as a singleton in the service container. You can resolve it directly:
use DigitalDevLx\LogHole\Drivers\Contracts\LogDriverInterface;
use DigitalDevLx\LogHole\Enums\LogLevel;
$driver = app(LogDriverInterface::class);
// Insert a log
$driver->insert(LogLevel::Info, 'Hello', ['key' => 'value'], now());
// Query logs with filters
$logs = $driver->query(level: LogLevel::Error, search: 'payment', limit: 20);
// Get paginated results
$paginated = $driver->paginate(level: LogLevel::Warning, perPage: 25);
// Get stats (cached when log-hole.stats_cache_ttl > 0)
$stats = $driver->stats();
echo $stats->total;
echo $stats->countForLevel(LogLevel::Error);
// Purge logs
$driver->purge(); // purge all
$driver->purge(level: LogLevel::Debug); // purge only debug logs
$driver->purge(before: now()->subMonth()); // purge logs older than 1 month
$driver->purge(before: now()->subYear(), chunkSize: 5000); // batched delete
The chunkSize argument on purge() lets you delete in batches instead of one statement — recommended on multi-million-row tables to reduce lock contention and binlog volume. Pass 0 (default) for a single DELETE statement.
The migration creates a logs_hole table (configurable via config('log-hole.database.table')) with the following structure:
| Column | Type | Notes |
|-------------|----------|------------------------------------|
| id | bigint | Primary key, auto-increment |
| message | text | Log message |
| level | string | Log level (e.g., ERROR) |
| context | json | Nullable, additional context |
| logged_at | datetime | Nullable, when the log was created |
Indexes: logged_at, and a composite (level, logged_at) that also covers level-only filters via leftmost-prefix.
v4 is a Laravel 13 release with no public API breaks. The driver layer was overhauled internally to fix LIKE wildcard escaping bugs in PostgreSQL and SQL Server, and to unify search semantics across MySQL/MariaDB. If you only used the Log facade, the dashboard, the log-hole:tail command or #[Loggable], the upgrade is composer require digitaldev-lx/log-hole:^4.0.
If you implemented a custom driver against LogDriverInterface, note that purge() now accepts a third optional argument int $chunkSize = 0. Existing callers continue to work; the new argument has a backward-compatible default.
Config file structure changed — re-publish the config:
php artisan vendor:publish --tag="log-hole-config" --force
Publish tag renamed — changed from --tag=logs-config to --tag=log-hole-config (Spatie convention)
#[Loggable] attribute — the level property is now a LogLevel enum (string values still work for backward compatibility). The $level public property was removed in favor of $logLevel (readonly LogLevel enum).
Views and routes moved — views moved from src/resources/views/ to resources/views/. Routes moved from src/routes/ to routes/. If you published views, re-publish them.
Migration indexes — re-run migrations to add the new performance indexes:
php artisan migrate
ESCAPE clause — wildcards in the search term are no longer ignoredCAST(context AS CHAR) LIKE ? ESCAPE ? instead of JSON_SEARCH, giving identical substring semantics across message and contextlogged_at (added id tiebreaker)DatabaseChannel resolves the driver from the container singleton on each write; DriverFactory::isMariaDb() is cached per-connectionstats_cache_ttl config option for caching the dashboard stats querypurge(); insert() falls back to now() when loggedAt is null; error_log fallback in the channel is rate-limitedSee CHANGELOG.md for the full list.
composer run test # Run default test suite (Pest, SQLite in-memory)
composer run test-coverage # Tests with coverage report
composer run analyse # PHPStan level 6
composer run format # Laravel Pint (PSR-12)
composer run check # analyse + format together
To run the integration suite against a real Postgres or MySQL database (skipped by default), set LOG_HOLE_INTEGRATION_DB:
LOG_HOLE_INTEGRATION_DB=pgsql DB_HOST=127.0.0.1 DB_PORT=5432 \
DB_DATABASE=log_hole_test DB_USERNAME=postgres DB_PASSWORD=postgres \
vendor/bin/pest --testsuite=integration
CI runs this suite automatically against Postgres 16 and MySQL 8.4 services.
digitaldev-lx/log-hole is open-sourced software licensed under the MIT license.
DigitalDev is a web development agency based in Lisbon, Portugal. We specialize in Laravel, Livewire, and Tailwind CSS.
Codeboys is our special partner and we work together to deliver the best solutions for our clients.
