PHPackages                             sluice/laravel-sluice - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. sluice/laravel-sluice

ActiveLibrary[Logging & Monitoring](/categories/logging)

sluice/laravel-sluice
=====================

Sluice aggregates logs, exceptions, and events from across your Laravel application into a single controlled stream — filterable, searchable, and chronologically sane.

v0.1.0(yesterday)00MITPHPPHP ^8.1

Since Apr 6Pushed yesterdayCompare

[ Source](https://github.com/claytonengle/laravel-sluice)[ Packagist](https://packagist.org/packages/sluice/laravel-sluice)[ Docs](https://github.com/claytonengle/laravel-sluice)[ RSS](/packages/sluice-laravel-sluice/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (8)Versions (2)Used By (0)

    ![Sluice](art/logo-light.svg)

 **A log aggregation dashboard for Laravel. Reads your existing log files and database tables, merges them into a single chronological timeline, and gives you a web UI, JSON API, and CLI to explore them.**

 [![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](LICENSE) [![Laravel](https://camo.githubusercontent.com/36ab9eb40d419c375ec1c19e6d5fd0d5ae0aeb01372cc6b164966c412feecdad/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302532422d7265642e737667)](https://laravel.com) [![PHP](https://camo.githubusercontent.com/fb7c72456e13f7d5ecf8486e29d02a2e6775aaf4d18622a63529976b0ed0740e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d707572706c652e737667)](https://php.net)

---

What It Actually Does
---------------------

[](#what-it-actually-does)

Sluice reads logs from places you point it at and displays them on a single page, sorted by time. It does not replace your logging stack. It sits next to it and gives you one place to look when something goes wrong.

**Out of the box, it can read from:**

- **Local log files** — `laravel.log`, rotated daily logs, or any text file with timestamps. Supports Laravel's standard format, plain text, and a config-driven custom regex parser for arbitrary formats (nginx, syslog, etc.).
- **Database tables** — Query any table in your database and map its columns to timeline events. Works with the package's own `sluice_logs` table or any existing table you already have.
- **AWS CloudWatch Logs** — Pull events from any CloudWatch log group (Lambda, ECS, EC2). Requires `aws/aws-sdk-php`.
- **S3 log files** — Download and parse log files from S3 buckets (CloudFront access logs, ALB logs, etc.). Requires `aws/aws-sdk-php`.
- **HTTP/REST APIs** — Fetch JSON from any API endpoint and map the response into timeline events. Uses Laravel's built-in HTTP client.

**It also includes a built-in logger** that can write structured events to a database table, a log file, or both. This is optional — you can use Sluice purely as a reader if you already have logs elsewhere.

### What it does NOT do

[](#what-it-does-not-do)

- It does not automatically discover every log source in your application. You tell it where to look via the config file.
- It does not natively integrate with Telescope, Horizon, Sentry, Flare, or Bugsnag. If those tools expose a REST API or write to a file/database, you can point Sluice at them using the HTTP or database source types — but there are no pre-built connectors.
- It is not a replacement for dedicated error tracking services. It is a single-pane view of what happened and when.

---

Features
--------

[](#features)

FeatureDetailsMulti-source aggregationMerge file + database + remote sources into one timelineConfig-driven sourcesDefine sources in `config/sluice.php` — labels, icons, colors, parsing rulesCustom format parsingConfig-defined regex patterns to parse any log format without writing codeSmart groupingRepeated identical entries within a time window collapse into x N badgesLevel filteringFilter by debug / info / warning / error / critical / securityText searchServer-side search across all sources + client-side instant filterSource togglesShow/hide individual sources with checkboxesJSON exportDownload filtered timeline as JSON for external analysisBuilt-in loggerOptional: log to DB, file, or both via a clean facade APIException captureOptional: automatically capture exceptions from Laravel's reporting pipelineFrontend error captureDedicated table and logger for JavaScript errorsBatch loggingEfficient bulk insert for high-throughput scenariosCustom layoutsUse the built-in standalone UI or embed into your app's Blade layoutJSON APIOptional REST endpoints for headless/external dashboard integrationCLI commands5 Artisan commands: view, filter, export, log, and cleanup from the terminalFlexible auth4 authorization strategies: Gate, callback, env variable, or open accessLaravel 10+Works with Laravel 10, 11, and 12---

Installation
------------

[](#installation)

### 1. Require the package

[](#1-require-the-package)

```
composer require sluice/laravel-sluice
```

The service provider auto-registers via Laravel's package discovery.

### 2. Publish the config

[](#2-publish-the-config)

```
php artisan vendor:publish --tag=sluice-config
```

This creates `config/sluice.php` where you define your sources.

### 3. (Optional) Run the migration

[](#3-optional-run-the-migration)

Only needed if you want database-backed logging via the built-in logger:

```
php artisan vendor:publish --tag=sluice-migrations
php artisan migrate
```

This creates two tables:

- `sluice_logs` — structured log entries
- `sluice_frontend_errors` — frontend JavaScript error capture

### 4. (Optional) Publish views for customization

[](#4-optional-publish-views-for-customization)

```
php artisan vendor:publish --tag=sluice-views
```

Views are copied to `resources/views/vendor/sluice/`.

### 5. Set up authorization

[](#5-set-up-authorization)

The dashboard supports 4 authorization strategies. Choose one:

**Strategy 1: Laravel Gate** (recommended)

```
// In AuthServiceProvider (Laravel 10) or AppServiceProvider (Laravel 11+)
use Illuminate\Support\Facades\Gate;

Gate::define('view-sluice', function ($user) {
    return $user->hasRole('developer');  // Your logic here
});
```

**Strategy 2: Callback** (no Gate needed)

```
// In config/sluice.php
'auth_gate' => null,
'auth_callback' => fn($user) => in_array($user->email, ['admin@example.com']),
```

**Strategy 3: Environment variable** (simple on/off)

```
// In config/sluice.php
'auth_gate' => null,
'auth_env' => 'SLUICE_ACCESS',
```

```
SLUICE_ACCESS=true
```

**Strategy 4: Open to all authenticated users**

```
// In config/sluice.php
'auth_gate' => null,
'auth_callback' => null,
'auth_env' => null,
```

### 6. Visit the dashboard

[](#6-visit-the-dashboard)

```
https://yourapp.com/sluice

```

---

Configuration
-------------

[](#configuration)

All configuration lives in `config/sluice.php`. Key sections:

### Defining Log Sources

[](#defining-log-sources)

Sources are the heart of the package. Each source tells Sluice where to find logs and how to display them.

#### File Sources

[](#file-sources)

```
'sources' => [
    'laravel' => [
        'type'    => 'file',
        'label'   => 'Laravel Log',
        'icon'    => 'bi-file-earmark-code',
        'badge'   => 'bg-danger',
        'enabled' => true,
        'paths'   => ['laravel.log'],
        'format'  => 'laravel',
    ],
],
```

**File Formats:**

FormatDescription`laravel`Standard Laravel log format: `[2026-04-06 12:00:00] production.ERROR: ...``plain`Line-based, detects level from keywords (ERROR, WARNING, etc.)`custom`Config-defined regex patterns for timestamp, level, and message extraction#### Database Sources

[](#database-sources)

```
'activity' => [
    'type'             => 'database',
    'label'            => 'Activity Logs',
    'icon'             => 'bi-database',
    'badge'            => 'bg-primary',
    'enabled'          => true,
    'table'            => 'activity_logs',
    'timestamp_column' => 'created_at',
    'mapping'          => [
        'level'   => 'log_level',
        'title'   => 'event_type',
        'message' => 'message',
        'context' => 'context',
        'user_id' => 'user_id',
    ],
    'filters' => [
        'search_columns' => ['event_type', 'message'],
        'level_column'   => 'log_level',
    ],
],
```

#### Remote Sources (CloudWatch, S3, HTTP)

[](#remote-sources-cloudwatch-s3-http)

See the commented examples in `config/sluice.php` for CloudWatch, S3, and HTTP source configurations.

### Exception Capture

[](#exception-capture)

Sluice can optionally hook into Laravel's exception reporting pipeline. When enabled, any exception that Laravel reports is automatically written to the Sluice timeline with the exception class, message, file, line, and a truncated stack trace.

```
// In config/sluice.php
'capture_exceptions' => true,
```

Or via environment variable:

```
SLUICE_CAPTURE_EXCEPTIONS=true
```

This uses Laravel's `MessageLogged` event, so it captures anything that passes through `report()` or `Log::error()` with an exception in the context. Built-in dedup prevents the same exception from flooding the timeline.

---

Using the Built-in Logger
-------------------------

[](#using-the-built-in-logger)

### Via Facade

[](#via-facade)

```
use Sluice\LaravelSluice\Facades\Sluice;

Sluice::info('user_login', 'User logged in successfully', ['ip' => '1.2.3.4'], $userId);
Sluice::warning('rate_limit', 'API rate limit approaching', ['current' => 95, 'max' => 100]);
Sluice::error('payment_failed', 'Stripe charge declined', ['charge_id' => 'ch_xxx'], $userId);
Sluice::critical('database_down', 'Primary database connection lost');
Sluice::security('brute_force', 'Multiple failed login attempts', ['attempts' => 15], $userId);
```

### Via Dependency Injection

[](#via-dependency-injection)

```
use Sluice\LaravelSluice\Logging\TimelineLogger;

class PaymentController extends Controller
{
    public function __construct(
        protected TimelineLogger $logger
    ) {}

    public function charge(Request $request)
    {
        $this->logger->info('payment_initiated', 'Processing payment', [
            'amount' => $request->amount,
        ], auth()->id());
    }
}
```

### Frontend Error Logging

[](#frontend-error-logging)

```
Sluice::frontendError(
    message: 'TypeError: Cannot read property "x" of undefined',
    type: 'javascript',
    stack: $stackTrace,
    source: 'https://app.example.com/js/app.js',
    line: 42,
    column: 15,
    url: 'https://app.example.com/dashboard',
    context: ['browser' => 'Chrome 120'],
    userId: auth()->id()
);
```

### Batch Logging

[](#batch-logging)

```
Sluice::batch([
    ['event_type' => 'page_view', 'message' => '/dashboard', 'log_level' => 'info'],
    ['event_type' => 'page_view', 'message' => '/settings', 'log_level' => 'info'],
], $userId);
```

---

CLI Commands
------------

[](#cli-commands)

All commands work without a web server.

```
php artisan sluice:show                          # View timeline in terminal
php artisan sluice:show --days=3 --level=error   # Filter by time and level
php artisan sluice:show --json | jq '.'          # Pipe JSON output

php artisan sluice:stats                         # Aggregate statistics
php artisan sluice:stats --json                  # Stats as JSON

php artisan sluice:export                        # Export to JSON file
php artisan sluice:export --days=14 --level=error --output=errors.json

php artisan sluice:log deploy_complete "Deployed v2.3.1 to production"
php artisan sluice:log disk_space_low "Disk at 92%" --level=warning

php artisan sluice:clear                         # Archive entries older than 90 days
php artisan sluice:clear --days=30 --delete      # Permanently delete
```

Schedule cleanup:

```
$schedule->command('sluice:clear --days=90 --force')->monthly();
```

---

JSON API
--------

[](#json-api)

Optional REST endpoints, disabled by default.

```
// config/sluice.php
'api' => [
    'enabled'    => true,
    'prefix'     => 'api/sluice',
    'middleware' => ['api', 'auth:sanctum'],
],
```

MethodEndpointDescriptionGET`/api/sluice`Full timeline with statsGET`/api/sluice/stats`Aggregate statistics onlyGET`/api/sluice/sources`Source metadataGET`/api/sluice/export`Downloadable JSON exportAll endpoints accept: `?days=`, `?limit=`, `?level=`, `?search=`, `?sources=`

---

Extending Sluice
----------------

[](#extending-sluice)

Sluice is designed to be extended through configuration and, when needed, through new source driver classes. If the five built-in source types (file, database, cloudwatch, s3, http) don't cover your use case, you can write a custom source driver.

### Writing a Custom Source Driver

[](#writing-a-custom-source-driver)

A source driver is a class that fetches log events from some external system and returns them as a Laravel Collection of normalized event arrays. Look at the existing drivers in `src/Sources/` for the pattern:

1. Create a class in `src/Sources/` (e.g., `RedisSource.php`).
2. Implement a static `isAvailable()` method that returns `false` if required dependencies are missing.
3. Implement a `fetch()` method that accepts a source key, start date, level filter, search filter, and limit, and returns a Collection of normalized event arrays.
4. Add a new `elseif` branch in `TimelineService::getTimeline()` for your new type.
5. Add a config block in `config/sluice.php` with `'type' => 'your_type'`.

The normalized event array structure:

```
[
    'source'       => 'source_key',
    'level'        => 'error',                // debug|info|warning|error|critical|security
    'timestamp'    => Carbon::instance(),
    'icon'         => 'bi-file-text',
    'badge_class'  => 'bg-danger',
    'source_badge' => 'bg-primary',
    'title'        => 'Source: ERROR',
    'subtitle'     => 'First 200 chars...',
    'details'      => ['key' => 'value'],
    'user_id'      => 42,                     // nullable
    'group_count'  => 1,
    'group_key'    => 'md5_hash',
]
```

### Contributing New Source Drivers

[](#contributing-new-source-drivers)

If you build a source driver that could be useful to others, please consider submitting it as a pull request. The things we would most like to see community drivers for:

- **Redis** — Read from Redis streams or pub/sub channels
- **Telescope** — Read from Telescope's database tables (for projects that use both)
- **Sentry/Bugsnag/Flare** — Fetch recent issues via their REST APIs
- **Elasticsearch/OpenSearch** — Query log indices
- **Kafka** — Consume from Kafka topics
- **Docker/container logs** — Read from Docker's JSON log files
- **Systemd journal** — Read from `journalctl` output

To submit a driver:

1. Fork the repository
2. Add your source class to `src/Sources/`
3. Add the corresponding type handling in `TimelineService::getTimeline()`
4. Add a commented example config block in `config/sluice.php`
5. Include a brief section in this README under "Remote Sources"
6. Submit a PR with a description of what the driver connects to and any required dependencies

We will review and merge drivers that follow the existing patterns: graceful degradation when dependencies are missing, config-driven setup, and no hard requirements on external packages.

---

Architecture
------------

[](#architecture)

```
sluice/laravel-sluice
+-- config/
|   +-- sluice.php                       -- All configuration
+-- database/migrations/
|   +-- create_sluice_tables.php         -- Optional DB tables
+-- resources/views/
|   +-- timeline.blade.php               -- Main page
|   +-- _sidebar.blade.php               -- Filter sidebar
|   +-- _timeline_content.blade.php      -- Timeline events
+-- routes/
|   +-- web.php                          -- Web dashboard routes
|   +-- api.php                          -- JSON API routes
+-- src/
    +-- SluiceServiceProvider.php
    +-- Console/Commands/                -- sluice:show, :stats, :export, :log, :clear
    +-- Facades/Sluice.php               -- Facade
    +-- Http/Controllers/
    |   +-- SluiceController.php         -- Web dashboard
    |   +-- Api/SluiceApiController.php  -- JSON API
    +-- Http/Middleware/SluiceAccess.php  -- Auth (4 strategies)
    +-- Listeners/ExceptionListener.php  -- Optional exception capture
    +-- Logging/TimelineLogger.php       -- Dual-driver logger
    +-- Models/                          -- Eloquent models
    +-- Sources/                         -- CloudWatch, S3, HTTP drivers
    +-- Services/TimelineService.php     -- Core aggregation engine

```

---

Security
--------

[](#security)

- The dashboard requires authentication (`auth` middleware) by default.
- Access is controlled by 4 configurable authorization strategies.
- The `SLUICE_ENABLED` env variable disables the package entirely.
- Individual interfaces can be toggled independently: `web_enabled`, `api.enabled`, `cli.enabled`.
- All `request()` calls are CLI-safe.

### Recommended Production Setup

[](#recommended-production-setup)

```
SLUICE_ENABLED=true
SLUICE_LOGGER_DRIVER=database
SLUICE_CAPTURE_EXCEPTIONS=true
```

```
Gate::define('view-sluice', fn($user) => $user->hasRole('developer'));
```

---

Quick Start
-----------

[](#quick-start)

**Minimal setup** — just view your `laravel.log`:

```
composer require sluice/laravel-sluice
php artisan vendor:publish --tag=sluice-config
```

```
Gate::define('view-sluice', fn($user) => $user->hasRole('admin'));
```

Visit `/sluice`.

**Full setup** — database logging + exception capture + API:

```
composer require sluice/laravel-sluice
php artisan vendor:publish --tag=sluice-config
php artisan vendor:publish --tag=sluice-migrations
php artisan migrate
```

```
SLUICE_CAPTURE_EXCEPTIONS=true
SLUICE_API_ENABLED=true
```

```
use Sluice\LaravelSluice\Facades\Sluice;

Sluice::info('order_placed', 'Order #1234 placed', ['total' => 99.99], $user->id);
```

---

Contributing
------------

[](#contributing)

Pull requests are welcome, especially for new source drivers. See the "Extending Sluice" section above for guidance on the expected structure.

Please open an issue first if you want to discuss a significant change before investing time in implementation.

---

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

###  Health Score

36

—

LowBetter than 81% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity32

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

1d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/10750734?v=4)[claytonengle](/maintainers/claytonengle)[@claytonengle](https://github.com/claytonengle)

---

Top Contributors

[![claytonengle](https://avatars.githubusercontent.com/u/10750734?v=4)](https://github.com/claytonengle "claytonengle (2 commits)")

---

Tags

laravelloggingDevtoolslog viewertimelinedashboardlog-aggregationsluice

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/sluice-laravel-sluice/health.svg)

```
[![Health](https://phpackages.com/badges/sluice-laravel-sluice/health.svg)](https://phpackages.com/packages/sluice-laravel-sluice)
```

###  Alternatives

[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.5k25.9M106](/packages/laravel-cashier)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k12.1M99](/packages/laravel-pulse)[laravel/cashier-paddle

Cashier Paddle provides an expressive, fluent interface to Paddle's subscription billing services.

264778.4k3](/packages/laravel-cashier-paddle)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[psalm/plugin-laravel

Psalm plugin for Laravel

3274.9M308](/packages/psalm-plugin-laravel)[masterro/laravel-mail-viewer

Easily view in browser outgoing emails.

6392.1k](/packages/masterro-laravel-mail-viewer)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)