Rentgen Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require czogori/rentgen
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Czogori\Rentgen\RentgenServiceProvider::class,
   ],
   

2. Basic Usage Rentgen is a data visualization and reporting tool for Laravel. Start by publishing its config:

   php artisan vendor:publish --provider="Czogori\Rentgen\RentgenServiceProvider"
   

   This generates a config file at config/rentgen.php.

3. First Use Case: Query Visualization Use Rentgen to log and visualize database queries in real-time:

   use Czogori\Rentgen\Facades\Rentgen;
   
   // Enable query logging
   Rentgen::enableQueryLogging();
   
   // Run a query (e.g., in a controller or service)
   $users = User::where('active', true)->get();
   
   // View queries in `/rentgen` (if configured)
   

Implementation Patterns

Core Workflows

1. Query Logging & Debugging

   • Enable/Disable: Toggle logging dynamically:

     Rentgen::enableQueryLogging(); // Global
     Rentgen::enableQueryLogging(true, ['User']); // Per-model
     

   • View Queries: Access the dashboard at /rentgen (or custom route) to see:
     • Query execution time
     • Bindings
     • SQL structure
     • Frequency metrics

2. Reporting & Analytics

   • Custom Metrics: Track business logic alongside queries:

     Rentgen::logEvent('checkout_completed', [
         'user_id' => auth()->id(),
         'amount' => $order->total,
     ]);
     

   • Export Data: Use the Rentgen::export() method to generate CSV/JSON reports:

     $data = Rentgen::export('queries', 'last_7_days');
     

3. Integration with Laravel Features

   • Middleware: Log queries for specific routes:

     public function handle($request, Closure $next) {
         Rentgen::enableQueryLogging();
         return $next($request);
     }
     

   • Events: Hook into Rentgen\Events\QueryLogged to process queries in real-time:

     event(new Rentgen\Events\QueryLogged($query));
     

4. Performance Profiling

   • Tag Queries: Label queries for grouping:

     Rentgen::tagQuery('admin_dashboard');
     

   • Filter by Tags: Use the dashboard to isolate performance bottlenecks.

Gotchas and Tips

Common Pitfalls

1. Memory Usage

   • Rentgen logs queries in memory by default. For long-running processes (e.g., queues), disable logging or use Rentgen::flush() to clear logs periodically.
   • Fix: Configure config/rentgen.php:

     'storage' => 'database', // Store logs in DB instead of memory
     

2. Route Conflicts

   • The default /rentgen route may conflict with other packages. Override it in config:

     'dashboard_route' => 'admin/performance',
     

3. Query Overhead

   • Logging queries adds minimal overhead (~1-5ms per query). For high-traffic apps, disable in production:

     if (app()->environment('production')) {
         Rentgen::disableQueryLogging();
     }
     

4. Database Storage Quirks

   • If using database storage, ensure the rentgen_logs table exists. Run:

     php artisan rentgen:install
     

   • Tip: Schedule a cleanup job to purge old logs:

     Rentgen::pruneLogs(Carbon::now()->subDays(30));
     

Pro Tips

1. Custom Query Formatting Extend the query formatter to highlight slow queries:

   Rentgen::extend('formatter', function ($query) {
       if ($query->duration > 100) { // ms
           return "<span style='color:red'>$query->sql</span>";
       }
       return $query->sql;
   });
   

2. API Access Expose Rentgen data via an API endpoint:

   Route::get('/api/performance', function () {
       return Rentgen::getLogs()->take(100);
   });
   

3. Slack/Email Alerts Trigger alerts for slow queries using Laravel's Handle facade:

   use Czogori\Rentgen\Events\QueryLogged;
   
   QueryLogged::listen(function ($query) {
       if ($query->duration > 500) { // 500ms threshold
           Notification::route('slack', 'channel-id')
               ->notify(new SlowQueryAlert($query));
       }
   });
   

4. Testing Mock Rentgen in tests to avoid logging:

   $this->partialMock(Rentgen::class, ['logQuery'])
       ->shouldReceive('logQuery')
       ->andReturnNull();
   

5. Configuration Overrides Dynamically adjust settings per request:

   Rentgen::setConfig([
       'log_bindings' => true, // Enable for current request only
   ]);