README

A beautiful, modern, and powerful in-browser debugging tool for Laravel applications. Inspired by Spatie Ray, but designed as a web-based viewer with persistent storage, real-time updates, and an intuitive interface.

✨ Features

🎯 Core Features

• 🌐 Web-Based Viewer - View dumps in a beautiful, dedicated web interface
• 💾 Persistent Storage - Dumps survive page refreshes and stay available across requests
• 🔄 Real-Time Updates - Auto-refresh to see new dumps as they arrive
• 🏷️ Smart Labeling - Organize dumps with custom labels and filter by them
• 🎨 Syntax Highlighting - SQL queries with beautiful formatting
• 🌓 Dark/Light Modes - Automatically adapts to your preference
• 📱 Responsive Design - Works perfectly on all screen sizes

🚀 Advanced Features

• ⚡ Tinker Support - Works seamlessly in php artisan tinker
• 🔍 Smart Detection - Automatically detects and formats SQL queries
• 📊 Collection Handling - Beautifully renders Laravel Collections and Models
• 🎯 Multiple Dumps - Dump multiple values in a single call
• 🔗 Fluent API - Chain methods like ->label() and ->stop()
• 🎨 Unique Colors - Each label gets a unique, consistent color
• 📈 Performance Mode - Handles large datasets with smart truncation

📦 Installation

Requirements

• PHP 8.2 or higher
• Laravel 10.x, 11.x, or 12.x

Install via Composer

composer require devportolio/laravel-dump-viewer --dev

Publish Configuration (Optional)

php artisan vendor:publish --tag=dump-viewer-config

Publish Assets (Optional)

php artisan vendor:publish --tag=dump-viewer-assets

🎯 Quick Start

Basic Usage

// Simple dump
dumpx($user);

// Dump with label
dumpx($user)->label('User Data');

// Dump multiple values
dumpx($user, $post, $comments);

// Multiple values with label
dumpx($a, $b, $c)->label('Debug Values');

// Label and stop
dumpx($data)->label('Final State')->stop();

View Your Dumps

After calling dumpx(), open your browser to:

http://your-app.test/dump-viewer

📖 Usage Guide

In Web Requests

Route::get('/test', function () {
    $user = User::first();
    
    // Dump the user
    dumpx($user)->label('First User');
    
    // Continue execution
    return view('test');
});

In Tinker

php artisan tinker

>>> $user = User::first()
>>> dumpx($user)->label('User from Tinker')
>>> dumpx(User::count())->label('Total Users')

Then open the viewer in your browser to see the dumps!

In Artisan Commands

class MyCommand extends Command
{
    public function handle()
    {
        $data = $this->fetchData();
        
        dumpx($data)->label('Command Data');
        
        $this->info('Data dumped to viewer!');
    }
}

SQL Query Debugging

$query = DB::table('users')
    ->where('active', true)
    ->toSql();

dumpx($query)->label('User Query');
// Automatically formats with syntax highlighting!

Eloquent Model Debugging

$user = User::with('posts', 'comments')->first();

dumpx($user)->label('User with Relations');
// Beautifully renders model attributes and relationships

Collection Debugging

$users = User::take(100)->get();

dumpx($users)->label('Users Collection');
// Smart rendering with expand/collapse

⚙️ Configuration

After publishing the config file, you can customize:

// config/dump-viewer.php

return [
    // Enable/disable the dump viewer
    'enabled' => env('DUMPX_ENABLED', true),
    
    // Route to access the viewer
    'route' => env('DUMPX_ROUTE', 'dump-viewer'),
    
    // Maximum dumps to store
    'storage_limit' => env('DUMPX_STORAGE_LIMIT', 500),
    
    // Storage driver (file, redis, database, etc.)
    'storage_driver' => env('DUMPX_STORAGE_DRIVER', 'file'),
    
    // Middleware for the viewer route
    'middleware' => ['web'],
];

Environment Variables

Add to your .env file:

# Enable/disable dump viewer
DUMPX_ENABLED=true

# Custom route
DUMPX_ROUTE=dump-viewer

# Storage settings
DUMPX_STORAGE_DRIVER=file
DUMPX_STORAGE_LIMIT=500

🎨 Interface Features

Header Controls

• 🔍 Filter by Label - Click labels to filter dumps
• 📊 Sort Options - Sort by time, label, or file
• ⤢ Expand/Collapse All - Toggle all dumps at once
• ⚡ Auto-Refresh Toggle - Enable/disable real-time updates
• 🌓 Theme Toggle - Switch between dark and light modes
• 🗑️ Clear All - Remove all dumps with one click

Dump Item Features

• 📂 Collapsible Content - Click to expand/collapse
• 🏷️ Color-Coded Labels - Each label has a unique color
• 📍 File Location - Shows file path and line number
• ⏰ Timestamp - When the dump was created
• 📋 Type Badge - Shows data type (Array, Model, Collection, etc.)

Keyboard Shortcuts

• Scroll to Bottom Button - In toolbar for quick navigation
• Floating Scroll to Top - Appears when scrolled down

🔧 Advanced Usage

Custom Labels

// Organize related dumps
dumpx($query)->label('DB Query');
dumpx($result)->label('Query Result');
dumpx($processed)->label('Processed Data');

// Filter by label in the viewer

Multiple Values with Same Label

// All values get the same label
dumpx($var1, $var2, $var3)->label('Test Variables');

Stopping Execution

// Use ->stop() to dump and halt execution
dumpx($criticalData)->label('Critical Error')->stop();

// Or chain it
dumpx($data)->label('Before Error')->stop();

Performance with Large Datasets

// Automatically truncates large collections
$users = User::all(); // 10,000 users

dumpx($users)->label('All Users');
// Shows warning and first 100 items

// Better approach:
dumpx(User::take(50)->get())->label('Sample Users');

🎭 Use Cases

1. API Development

public function store(Request $request)
{
    dumpx($request->all())->label('Request Data');
    
    $validated = $request->validate([...]);
    dumpx($validated)->label('Validated Data');
    
    $user = User::create($validated);
    dumpx($user)->label('Created User');
    
    return response()->json($user);
}

2. Query Optimization

DB::listen(function ($query) {
    dumpx($query->sql)->label('Query: ' . $query->time . 'ms');
});

3. Event Debugging

Event::listen('*', function ($event, $payload) {
    dumpx([
        'event' => $event,
        'payload' => $payload
    ])->label('Event: ' . $event);
});

4. Job Debugging

class ProcessPodcast implements ShouldQueue
{
    public function handle()
    {
        dumpx($this->podcast)->label('Processing Podcast');
        
        // Process...
        
        dumpx($result)->label('Process Complete');
    }
}

🛡️ Security

Production Safety

The dump viewer is designed for development only:

// Disable in production
'enabled' => env('DUMPX_ENABLED', !app()->isProduction()),

// Or in .env
DUMPX_ENABLED=false

Route Protection

Add authentication middleware:

// config/dump-viewer.php
'middleware' => ['web', 'auth', 'admin'],

Access Control

Use custom middleware:

class DumpViewerAccess
{
    public function handle($request, Closure $next)
    {
        if (!app()->environment('local')) {
            abort(404);
        }
        
        return $next($request);
    }
}

// config/dump-viewer.php
'middleware' => ['web', DumpViewerAccess::class],

🎯 Tips & Best Practices

1. Use Labels Consistently

// Good: Organized and filterable
dumpx($query)->label('DB: User Query');
dumpx($result)->label('DB: Query Result');
dumpx($user)->label('User: Loaded');
dumpx($posts)->label('User: Posts');

// Bad: Hard to find and organize
dumpx($query);
dumpx($result);

2. Clean Up Regularly

// In your bootstrap or test setup
if (app()->environment('testing')) {
    app('dumpx')->clear();
}

3. Use in Tinker Workflows

// Keep viewer open in browser
// Run commands in Tinker
// Refresh browser to see dumps

4. Combine with Logs

// Dump for immediate visibility
dumpx($data)->label('Debug Point');

// Log for permanent record
Log::debug('Debug point', ['data' => $data]);

🔄 Comparison with Alternatives

Feature	dumpx	Ray	Laravel Debugbar	dump/dd
Web Interface	✅ Yes	❌ Desktop App	✅ Yes	❌ No
Persistent Storage	✅ Yes	✅ Yes	❌ Per Request	❌ No
Tinker Support	✅ Yes	✅ Yes	❌ No	✅ Yes
Real-time Updates	✅ Yes	✅ Yes	❌ No	❌ No
Labeling	✅ Yes	✅ Yes	❌ No	❌ No
Cost	🆓 Free	💰 Paid	🆓 Free	🆓 Free
Setup	⚡ Easy	📱 Desktop	⚡ Easy	✅ Built-in

🐛 Troubleshooting

Dumps Not Showing

1. Check if enabled:

php artisan tinker
>>> config('dump-viewer.enabled')

2. Check storage driver:

>>> config('dump-viewer.storage_driver')
// Should be 'file' for Tinker

3. Clear cache:

php artisan cache:clear
php artisan config:clear

4. Check file permissions:

chmod -R 775 storage/framework/cache

Tinker Not Working

1. Ensure file driver:

DUMPX_STORAGE_DRIVER=file

2. Test cache:

>>> Cache::store('file')->put('test', 'works', 60)
>>> Cache::store('file')->get('test')

3. Manually check dumps:

>>> app('dumpx')->all()

Route Not Found

1. Check route name:

>>> config('dump-viewer.route')

2. Clear route cache:

php artisan route:clear

3. List routes:

php artisan route:list | grep dump

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

The MIT License (MIT). Please see License File for more information.

👏 Credits

• Inspired by Spatie Ray
• Built with Laravel
• Uses Alpine.js for interactivity
• Styled with Tailwind CSS

🔗 Links

• Author: Joseph Getaruelas
• Email: developnow.415@gmail.com
• Package: devportolio/laravel-dump-viewer

Made with ❤️ for the Laravel community