request-atlas/laravel

A Laravel package to capture and inspect request execution traces.

v1.0.0 2025-12-27 06:09 UTC

Requires

• php: ^8.0
• illuminate/console: ^8.0|^9.0|^10.0|^11.0|^12.0
• illuminate/database: ^8.0|^9.0|^10.0|^11.0|^12.0
• illuminate/events: ^8.0|^9.0|^10.0|^11.0|^12.0
• illuminate/http: ^8.0|^9.0|^10.0|^11.0|^12.0
• illuminate/support: ^8.0|^9.0|^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^7.0|^8.0|^9.0
• phpunit/phpunit: ^9.5|^10.0

MIT

• Abdullah Mohamed

README

A high-precision execution profiler providing a hierarchical view of the request lifecycle.

Request Atlas captures the complete execution flow of your Laravel applications—mapping database queries, cache operations, outbound HTTP calls, and application events into a structured "Execution Tree". Inspect your request's "Story" directly from your terminal or through a polished, educational Web UI.

🚀 Why Request Atlas?

Most profilers tell you what happened (flat lists) or what was slow (flamegraphs). Atlas tells you how it happened.

• Hierarchical Context: See exactly which controller method or middleware triggered which database query.
• CLI-First: Designed for developers who live in the terminal. No browser required.
• Educational Web UI: A "Junior-First" approach to performance, explaining the Laravel lifecycle as it happens.
• IDE Integration: Open files directly in your favorite editor (VS Code, Cursor, Trae, PhpStorm, or Antigravity) from the trace view.
• Production Ready: "Smart Disable" in production, request sampling, and high-performance cursor pagination.
• Data Scrubbing: Automatically masks sensitive information (passwords, tokens, keys) before saving to the database.
• Zero-Config Installation: One command and you're tracing.

🛠 Features

• Full Lifecycle Tracing: Captures everything from the public index.php to the final terminating cleanup.
• Execution Tree: Automatically reconstructs parent-child relationships using a LIFO context stack.
• Deep Database Insight: Records SQL, interpolates bindings, detects N+1 patterns, and groups queries by table.
• Comparison Dashboard: Side-by-side analysis of two traces with a categorical performance breakdown and duration gap indicators.
• Interactive Story: A visual flow of your request, explaining the Laravel phases (Entry Point, Middleware, Controller, etc.).
• Multi-Language: Fully localized for English and Arabic.

📋 Requirements

Before installing, ensure your environment meets the following criteria:

• PHP: 8.0 - 8.5
• Laravel: 8.x, 9.x, 10.x, 11.x, or 12.x
• Database: Any SQL-based driver supported by Laravel (MySQL, PostgreSQL, SQLite, SQL Server)
• Browser: Modern browser with JavaScript enabled (for the Web UI)

📦 Installation

1. Install via Composer:

   composer require request-atlas/laravel

2. Run the Automated Setup:

   php artisan atlas:install

   This will publish the configuration, run migrations, and enable the collector in your .env.

💻 Terminal Usage

Atlas provides a suite of powerful Artisan commands for fast, pipe-friendly inspection.

1. Listing Recent Traffic

php artisan atlas:list

Options: --slow, --failed, --has-n-plus-one, --limit=50.

2. The Execution Tree

php artisan atlas:show {trace_id}

Shows a hierarchical tree. Use --simple to hide framework noise (migrations, internal events).

3. Performance Analysis

php artisan atlas:analyze {trace_id}

Runs a diagnostic report: detects slow operations and highlights specific N+1 query candidates.

🌐 Web Interface

Accessible at /atlas, the Web UI is designed for deep exploration.

IDE Integration

Every file path in the UI (Controllers, Views, Entry Point) features an "Open in IDE" dropdown, allowing you to quickly jump to the code in VS Code, Cursor, Trae, PhpStorm, or Antigravity.

Comparison Mode

Select two traces from the index and click Compare.

• Performance Gap: Shows exactly how much faster or slower the new request is.
• Categorical Breakdown: Compare the number of DB queries, cache hits, and events side-by-side.

Maintenance & Scalability

• Clear All: A dedicated button in the Web UI to wipe the trace history (equivalent to atlas:clear).
• Infinite Loading: The index uses high-performance cursor pagination with a "Load More" button, making it snappy even with millions of records.

⚙️ Configuration

The config/atlas.php file allows you to fine-tune Atlas:

• enabled: Master switch. Defaults to null, which automatically disables Atlas in production for safety.
• sample_rate: Control how many requests are recorded (e.g., 0.1 for 10%).
• scrubbing: Define sensitive keys to be masked (e.g., password, _token).
• ignore: Define SQL or Route patterns to skip.
• view: Control the "Internal Noise" filtering.
• events: Group framework-internal events to reduce noise.

🤝 Atlas vs Laravel Telescope?

Feature	Request Atlas	Laravel Telescope
Primary Goal	Hierarchy & Flow	Feature Monitoring
Question it answers	"How did this happen?"	"What happened?"
Best for	Debugging & Learning	General Auditing
Footprint	Ultra-Lightweight	Medium/Heavy