Yii2 Debug Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev yiisoft/yii2-debug
   

   Add to your config/web.php (or relevant environment config):

   'modules' => [
       'debug' => [
           'class' => 'yiisoft\yii2\debug\Module',
           'allowedIPs' => ['127.0.0.1', '::1', '192.168.*'], // Restrict access
       ],
   ],
   

2. First Use Case:

   • Access /debug in your browser to see the dashboard.
   • Navigate to the "Requests" tab to inspect the current HTTP request/response.
   • Use the "Exceptions" tab to review unhandled errors (if enabled).

3. Key Initial Files:

   • vendor/yiisoft/yii2-debug/src/Module.php (core module logic).
   • vendor/yiisoft/yii2-debug/src/panels/ (individual panel implementations).

Implementation Patterns

Core Workflows

1. Debugging Requests/Responses:

   • Enable detailed request/response logging in config/web.php:

     'debug' => [
         'modules' => [
             'debug' => [
                 'panels' => [
                     'yiisoft\yii2\debug\panels\RequestsPanel',
                 ],
             ],
         ],
     ],
     

   • Useful for API debugging or troubleshooting edge cases (e.g., CORS, headers).

2. Database Queries:

   • Add the yiisoft\yii2\debug\panels\DbPanel to log and analyze SQL queries.
   • Configure in config/web.php:

     'components' => [
         'db' => [
             'enableProfiling' => true, // Critical for query logging
             'enableLogging' => true,
         ],
     ],
     

3. Performance Profiling:

   • Integrate with Yii’s built-in profiler:

     Yii::$app->getProfiler()->enable();
     

   • View results in the "Performance" panel.

4. Custom Panels:

   • Extend yiisoft\yii2\debug\Panel to create domain-specific panels (e.g., for caching or third-party APIs).
   • Example:

     namespace app\debug\panels;
     use yiisoft\yii2\debug\Panel;
     
     class MyCustomPanel extends Panel {
         public $name = 'My Custom Panel';
         public function getData() { /* ... */ }
     }
     

   • Register in config/web.php:

     'panels' => [
         'app\debug\panels\MyCustomPanel',
     ],
     

5. Error Tracking:

   • Use the "Exceptions" panel to log and review uncaught exceptions.
   • Configure error handling in config/web.php:

     'components' => [
         'errorHandler' => [
             'exceptionHandler' => 'app\components\DebugExceptionHandler', // Custom handler
         ],
     ],
     

Gotchas and Tips

Common Pitfalls

1. Performance Overhead:

   • Debug panels add significant overhead. Disable in production:

     'debug' => [
         'class' => 'yiisoft\yii2\debug\Module',
         'enabled' => Yii::$app->getRequest()->getHostInfo() === 'localhost', // Example condition
     ],
     

   • Use Yii::$app->getProfiler()->disable() in production.

2. Sensitive Data Exposure:

   • Never expose /debug publicly. Restrict allowedIPs strictly:

     'allowedIPs' => ['192.168.1.100'], // Only your IP!
     

   • Avoid logging passwords, tokens, or PII in panels. Use yiisoft\yii2\debug\DataMasker to sanitize data:

     Yii::$app->debug->dataMasker->mask('password', '****');
     

3. Panel Conflicts:

   • Some panels (e.g., yiisoft\yii2\debug\panels\AssetsPanel) may not work with custom asset managers.
   • Solution: Exclude unused panels or override their logic.

4. Database Panel Quirks:

   • The DbPanel may not log queries from raw PDO statements or non-Yii DB components.
   • Workaround: Use Yii’s DbCommand or wrap raw queries in Yii::$app->db->createCommand().

5. Caching Issues:

   • Debug panels bypass Yii’s cache. If using yiisoft\yii2\debug\panels\CachePanel, ensure cache components are properly configured:

     'components' => [
         'cache' => [
             'class' => 'yiisoft\yii2\caching\FileCache',
         ],
     ],
     

Debugging Tips

1. Log Filtering:

   • Use yiisoft\yii2\debug\DataMasker to filter sensitive data in logs:

     Yii::$app->debug->dataMasker->rules = [
         'password' => ['mask' => '****'],
         'token' => ['mask' => '***'],
     ];
     

2. Custom Logs:

   • Add custom logs to panels by extending yiisoft\yii2\debug\Panel and implementing getData():

     public function getData() {
         return [
             'custom_logs' => Yii::getLogger()->getLogs(),
         ];
     }
     

3. Remote Debugging:

   • For cloud environments, use SSH tunneling to access /debug:

     ssh -L 8080:localhost:80 user@your-server.com
     

   • Access http://localhost:8080/debug locally.

4. Panel Order:

   • Panels render in the order they’re defined. Reorder in config/web.php:

     'panels' => [
         'yiisoft\yii2\debug\panels\RequestsPanel',
         'yiisoft\yii2\debug\panels\DbPanel',
     ],
     

5. Debugging Debug:

   • If the debug toolbar disappears, check:
     • Yii::$app->getRequest()->getHostInfo() matches allowedIPs.
     • No middleware is stripping output (e.g., Response::send()).
     • No JavaScript errors (open browser console).