Debug Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev redaxo/debug:^2.0@dev
   bin/console addon:install debug
   

   Ensure you’re in a development environment—this package is not for production.

2. First Use Case:

   • Visit your REDAXO admin or frontend URL in a browser.
   • Open Clockwork (via browser extension or standalone app at /clockwork).
   • Observe pre-integrated data:
     • Database queries (Redaxo\Core\Database\Sql).
     • Log entries (Redaxo\Core\Log\Logger).
     • Timers (Redaxo\Core\Util\Timer).
     • Extension points (Redaxo\Core\ExtensionPoint\*).

3. Quick Check:

   • Trigger a slow query or log a message to verify Clockwork captures it.

Implementation Patterns

Core Workflows

1. Debugging Queries:

   • Use Redaxo\Core\Database\Sql for queries. Clockwork auto-instruments them.
   • Example:

     $sql = new Redaxo\Core\Database\Sql();
     $sql->get('SELECT * FROM articles');
     

   • View in Clockwork: Tab → "Queries" to see execution time, SQL, and bindings.

2. Logging Integration:

   • Log messages via Redaxo\Core\Log\Logger:

     $logger = Redaxo\Core\Log\Logger::getLogger();
     $logger->info('User loaded', ['user_id' => 123]);
     

   • View in Clockwork: Tab → "Logs" to see context and timestamps.

3. Timing Code Blocks:

   • Wrap critical sections with Redaxo\Core\Util\Timer:

     $timer = new Redaxo\Core\Util\Timer();
     // ... code ...
     $timer->stop('rendering_page');
     

   • View in Clockwork: Tab → "Timers" for duration breakdowns.

4. Extension Points:

   • Monitor ExtensionPoint calls (e.g., Redaxo\Core\ExtensionPoint\ExtensionPoint::get('article_list')).
   • View in Clockwork: Tab → "Events" to see extensions fired and their payloads.

Integration Tips

• Custom Data: Use Clockwork’s store() method to log custom data:

  \Clockwork\Clockwork::store('custom_data', ['key' => 'value']);
  

  Accessible via the "Custom" tab in Clockwork.

• Middleware: Add Clockwork to REDAXO’s middleware stack (if needed) via config/debug.php:

  'middleware' => [
      \Redaxo\Debug\Middleware\ClockworkMiddleware::class,
  ],
  

• Queue Jobs: Clockwork supports queue jobs. Ensure your REDAXO queue worker is configured to use Clockwork’s listener.

• Browser Extension: Install the Clockwork Chrome/Firefox extension for real-time insights without appending /clockwork to URLs.

Gotchas and Tips

Pitfalls

1. Production Leakage:

   • Never enable Clockwork in production. The package is dev-only and may expose sensitive data (e.g., SQL queries, logs).
   • Fix: Use environment checks:

     if (app()->environment('local')) {
         \Clockwork\Clockwork::enable();
     }
     

2. Performance Overhead:

   • Clockwork adds ~5–10ms per request. Disable it in staging:

     'enabled' => app()->environment(['local', 'staging'] === false),
     

3. Missing Data:

   • If data isn’t appearing, verify:
     • The class is instrumented (e.g., Redaxo\Core\Database\Sql is auto-instrumented; custom classes need manual setup).
     • Clockwork is enabled (\Clockwork\Clockwork::enable()).

4. REDAXO-Specific Quirks:

   • Database Queries: Only Redaxo\Core\Database\Sql queries are tracked. Raw PDO queries won’t appear.
   • Logs: Only Redaxo\Core\Log\Logger logs are captured. Use Clockwork\Clockwork::store() for other logs.

Debugging Tips

1. Clockwork Not Loading:

   • Check config/debug.php for correct middleware configuration.
   • Ensure the /clockwork route is accessible (may require REDAXO route adjustments).

2. Custom Instrumentation:

   • To track custom classes, use Clockwork’s span():

     \Clockwork\Clockwork::span('my_process', function() {
         // Code to profile
     });
     

3. Log Context:

   • Attach metadata to logs for better debugging:

     $logger->info('Error loading article', [
         'article_id' => 42,
         'trace' => $e->getTraceAsString(),
     ]);
     

4. Extension Points:

   • Use Clockwork to debug extension conflicts:
     • Check the "Events" tab to see which extensions are firing and their order.

Extension Points

1. Custom Tabs: Extend Clockwork’s UI by creating a custom tab. Example:

   \Clockwork\Clockwork::addTab('my_tab', function() {
       return view('clockwork.my_tab');
   });
   

2. Middleware Hooks: Override Clockwork’s middleware in config/debug.php:

   'middleware' => [
       \App\Middleware\CustomClockworkMiddleware::class,
   ],
   

3. Data Sanitization: Redact sensitive data before storing:

   \Clockwork\Clockwork::store('user_data', [
       'email' => '[email protected]',
       'password' => '*****', // Manually redacted
   ]);