Laravel Dump Viewer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require devportolio/laravel-dump-viewer
   php artisan vendor:publish --provider="DevPortolio\DumpViewer\DumpViewerServiceProvider" --tag="dump-viewer-config"
   php artisan dump-viewer:install
   

   • Publishes config, migrations, and assets.
   • Run migrations: php artisan migrate.

2. First Use Case: Replace dd() or dump() in your code with:

   \DevPortolio\DumpViewer\Facades\DumpViewer::dump($variable, 'label');
   

   • Access the viewer at /dump-viewer (configured in .env or config/dump-viewer.php).

3. Quick Start:

   • Trigger a dump in a controller or middleware:

     use DevPortolio\DumpViewer\Facades\DumpViewer;
     
     public function show(Request $request) {
         $data = User::first();
         DumpViewer::dump($data, 'User Data');
         return view('welcome');
     }
     

   • View the dump in the browser at /dump-viewer.

Implementation Patterns

Core Workflows

1. Debugging API Responses:

   public function apiResponse(Request $request) {
       $response = $this->service->process($request);
       DumpViewer::dump($response, 'API Response');
       return response()->json($response);
   }
   

   • Useful for inspecting complex JSON structures or error payloads.

2. Middleware Debugging:

   public function handle($request, Closure $next) {
       $user = auth()->user();
       DumpViewer::dump($user, 'Authenticated User');
       return $next($request);
   }
   

   • Attach to middleware to debug user sessions or request data.

3. Event Listeners:

   public function handle(OrderCreated $event) {
       DumpViewer::dump($event->order, 'New Order');
       // Process order...
   }
   

   • Log event payloads for debugging workflows.

4. Tinker Integration:

   php artisan tinker
   

   >>> $user = User::first();
   >>> \DevPortolio\DumpViewer\Facades\DumpViewer::dump($user, 'Tinker User');
   

   • View dumps in the browser while interacting with Tinker.

Integration Tips

1. Conditional Dumping: Use environment checks to avoid clutter in production:

   if (app()->environment('local')) {
       DumpViewer::dump($variable, 'Debug Label');
   }
   

2. Labeling Strategy:

   • Use descriptive labels (e.g., User::with('roles')->get() → 'User with Roles').
   • Group related dumps with similar prefixes (e.g., auth/, payment/).

3. Real-Time Debugging:

   • Enable auto-refresh in the viewer settings to monitor live updates.
   • Useful for debugging long-running processes (e.g., queue workers).

4. SQL Query Inspection: Dump Eloquent query builders or raw queries:

   $query = User::where('active', true)->toSql();
   DumpViewer::dump($query, 'Raw SQL');
   

5. Collection/Model Rendering: Automatically formats collections and models with relationships:

   $users = User::with('posts')->get();
   DumpViewer::dump($users, 'Users with Posts');
   

6. Custom Views: Extend the viewer by publishing assets:

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

   • Override resources/views/vendor/dump-viewer/ to customize UI.

Gotchas and Tips

Pitfalls

1. Storage Overload:

   • Dumps are stored in the database (dump_viewer_dumps table). Large or frequent dumps may bloat storage.
   • Fix: Use DumpViewer::clear() to manually purge old dumps or set max_dumps in config.

2. Performance Impact:

   • Dumping large objects (e.g., entire databases) can slow responses.
   • Fix: Use app()->environment('local') checks or disable in staging/prod.

3. Label Collisions:

   • Duplicate labels may obscure dumps.
   • Fix: Use unique labels with timestamps or UUIDs:

     DumpViewer::dump($var, "Label-" . Str::uuid());
     

4. Tinker Visibility:

   • Tinker dumps may not appear immediately due to session/connection differences.
   • Fix: Restart the Tinker session or check the viewer after running commands.

5. Middleware Conflicts:

   • Some middleware (e.g., CORS, auth) may block access to /dump-viewer.
   • Fix: Exclude the route from middleware or use a dedicated debug route:

     Route::middleware(['web', 'dump-viewer'])->group(function () {
         // Debug routes
     });
     

Debugging Tips

1. Clear Dumps:

   php artisan dump-viewer:clear
   

   • Or via the viewer UI (gear icon → "Clear All").

2. Filtering:

   • Use the search bar or label filters to locate specific dumps.
   • SQL queries are auto-highlighted; click to expand.

3. Dark Mode Issues:

   • If syntax highlighting is unclear, toggle dark/light mode in the viewer settings.

4. Missing Dumps:

   • Ensure DUMP_VIEWER_ENABLED=true in .env.
   • Verify the dump-viewer middleware is registered in app/Http/Kernel.php:

     protected $middleware = [
         // ...
         \DevPortolio\DumpViewer\Middleware\DumpViewerMiddleware::class,
     ];
     

5. Custom Data Rendering:

   • Extend the dumper by binding custom handlers:

     DumpViewer::extend(function ($dumper) {
         $dumper->handle(MyCustomClass::class, function ($value) {
             return "Custom Render: " . $value->toJson();
         });
     });
     

Extension Points

1. Custom Storage: Override the default database storage by binding a custom DumpStorage implementation:

   $app->bind(\DevPortolio\DumpViewer\Contracts\DumpStorage::class, function () {
       return new \App\Services\CustomDumpStorage();
   });
   

2. Event Hooks: Listen for dump events to log or process dumps externally:

   DumpViewer::dumping(function ($dump) {
       Log::debug('Dump created:', ['label' => $dump->label, 'data' => $dump->data]);
   });
   

3. Asset Overrides: Publish and modify the viewer’s Blade views or CSS/JS:

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

   • Edit resources/views/vendor/dump-viewer/ or public/vendor/dump-viewer/.

4. API Access: Fetch dumps programmatically via the DumpViewer facade:

   $dumps = DumpViewer::all();
   $latest = DumpViewer::latest()->first();
   

5. Localization: Extend language support by publishing translations:

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

   • Modify resources/lang/vendor/dump-viewer/ for multi-language support.