README

A Laravel package that logs HTTP requests, duration, status, SQL queries, and memory usage — with a built-in web dashboard to browse and inspect them.

Features

• Zero-config setup — auto-discovered and auto-registered into the web and api middleware groups
• Request metadata — method, URL, path, named route, IP address, authenticated user ID, status code
• Performance data — request duration (ms) and peak memory usage (MB)
• SQL query logging — captures all queries with bindings and execution time; automatically flags slow queries
• Sensitive header redaction — strips Authorization, Cookie, and X-CSRF-Token headers before persisting
• Privacy-first — request and response bodies are off by default
• Built-in dashboard — paginated, filterable log browser at /larascope
• Log pruning — php artisan larascope:prune removes logs older than a configurable retention period
• Database fallback — if a DB insert fails, the payload is written to the Laravel log so nothing is silently lost
• Octane-safe — per-request state is reset on every handle() call to prevent bleed between requests

Requirements

Installation

Install the package via Composer:

composer require amjad-ah/larascope

The package is auto-discovered — no manual provider registration needed.

Run the migration to create the larascope_request_logs table:

php artisan migrate

That's it. LaraScope is now logging every HTTP request in the web and api middleware groups.

Dashboard

Open /larascope in your browser to browse captured logs.

The list view supports filtering by HTTP method, status code, and path substring. The detail view shows the full SQL query log (with bindings and slow-query flags), request headers, memory peak, and duration.

Tailwind CSS is loaded via CDN — no asset pipeline required.

Protecting the dashboard in production

Add Laravel's auth middleware (or any middleware you prefer) to the dashboard:

// config/larascope.php
'dashboard' => [
    'middleware' => ['web', 'auth'],
],

Configuration

Publish the config file to customise any option:

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

Environment variables

Full config reference

// config/larascope.php

return [

    // Master switch — set to false to disable everything
    'enabled' => env('LARASCOPE_ENABLED', true),

    'database' => [
        'connection' => env('LARASCOPE_DB_CONNECTION', null),
        'table'      => env('LARASCOPE_DB_TABLE', 'larascope_request_logs'),
    ],

    // Middleware groups to auto-register the logging middleware into
    'middleware_groups' => ['web', 'api'],

    'dashboard' => [
        'enabled'    => env('LARASCOPE_DASHBOARD_ENABLED', true),
        'path'       => env('LARASCOPE_DASHBOARD_PATH', 'larascope'),
        'middleware' => ['web'],   // add 'auth' to restrict access
        'per_page'   => 25,
    ],

    'logging' => [
        'include_request_headers' => true,
        'include_request_body'    => false,  // off by default for privacy
        'include_response_body'   => false,  // off by default for privacy

        // Headers stripped before storing (case-insensitive)
        'exclude_headers' => [
            'authorization',
            'cookie',
            'x-csrf-token',
        ],

        // Paths to skip — supports Str::is() wildcards e.g. '_debugbar/*'
        'exclude_paths' => [],

        // HTTP methods to skip entirely e.g. ['OPTIONS']
        'exclude_methods' => [],
    ],

    'queries' => [
        'enabled'           => true,
        'slow_threshold_ms' => 100,  // queries >= this value are flagged as slow
    ],

    'pruning' => [
        'enabled'     => true,
        'retain_days' => 30,
    ],

];

Excluding paths and methods

Skip specific routes using wildcards (powered by Str::is()):

'exclude_paths' => [
    'health',
    '_debugbar/*',
    'telescope/*',
    'horizon/*',
],

'exclude_methods' => ['OPTIONS'],

The dashboard's own routes are always excluded automatically to prevent recursive log growth.

Captured data

Each log entry stores 15 fields:

Artisan commands

Prune old logs

php artisan larascope:prune

Deletes all log entries older than pruning.retain_days (default: 30 days). Schedule this command to keep your table from growing unbounded:

// routes/console.php (Laravel 11+)
Schedule::command('larascope:prune')->daily();

Publishing assets

# Publish config
php artisan vendor:publish --tag=larascope-config

# Publish migration (to customise the table schema)
php artisan vendor:publish --tag=larascope-migrations

# Publish Blade views (to customise the dashboard UI)
php artisan vendor:publish --tag=larascope-views

Architecture

HTTP Request
  → LaraScopeMiddleware   (resets state, captures start time, registers DB::listen)
    → RequestLogger       (builds structured 15-field payload)
      → DatabaseDriver    (persists to DB; falls back to Laravel log on failure)
        → RequestLog      (Eloquent model consumed by the dashboard)
          → DashboardController / PruneLogsCommand

Both LaraScopeMiddleware and RequestLogger are bound as singletons so the same instance handles both handle() and terminate(). Per-request state ($collectedQueries, $shouldSkip) is reset at the top of every handle() call, making the package safe under persistent runtimes like Laravel Octane.