Yii2 Debug Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --prefer-dist yiisoft/yii2-debug
   

2. Enable in config/web.php:

   'bootstrap' => ['debug'],
   'modules' => [
       'debug' => [
           'class' => 'yii\debug\Module',
       ],
   ],
   

3. Verify: Access any page—you’ll see a toolbar at the bottom with debug info.

First Use Case

• Quick Debugging: Click the toolbar to inspect:
  • Request/response details (headers, cookies, params).
  • Database queries (with execution time and SQL).
  • Memory/CPU usage.
  • Logs and exceptions.

Implementation Patterns

Core Workflows

1. Toolbar Integration:

   • Automatically appears in dev mode (YII_DEBUG = true).
   • Customize via panels config (e.g., disable specific panels):

     'panels' => [
         'db' => ['class' => 'yii\debug\panels\DbPanel'],
         'request' => ['class' => 'yii\debug\panels\RequestPanel'],
     ],
     

2. Detailed Debug Pages:

   • Access via /debug/default/view (or /debug/default for all panels).
   • Navigate to sub-pages (e.g., /debug/default/log-viewer) for granular data.

3. IDE Integration:

   • Configure traceLine for clickable file/line links:

     'traceLine' => '<a href="phpstorm://open?url={file}&line={line}">{file}:{line}</a>',
     

   • Handle Docker/virtualized paths with tracePathMappings:

     'tracePathMappings' => [
         '/var/www/html' => '/host/path/to/app',
     ],
     

Advanced Patterns

1. Custom Panels:

   • Extend yii\debug\Panel to collect app-specific metrics (e.g., rendered views, cache hits).
   • Example: Track view files in ViewsPanel (see docs).

2. Dynamic Panel Loading:

   • Load panels conditionally (e.g., only in staging):

     'panels' => YII_ENV_STAGING ? ['db', 'request'] : [],
     

3. Event-Driven Debugging:

   • Listen for yii.debug.toolbar_attached in JavaScript:

     document.addEventListener('yii.debug.toolbar_attached', (e) => {
         const toolbar = e.target;
         toolbar.querySelector('.yii-debug-toolbar__block').addEventListener('click', () => {
             console.log('Toolbar clicked!');
         });
     });
     

4. Performance Profiling:

   • Use the profiling panel to measure execution time of specific code blocks:

     Yii::$app->profiling->begin('custom_block');
     // Code to profile
     Yii::$app->profiling->end();
     

Gotchas and Tips

Pitfalls

1. Permission Issues:

   • Ensure @runtime/debug is writable by the web server user.
   • Fix: chmod -R 775 runtime/debug (Linux) or adjust Docker volumes.

2. Strict URL Parsing:

   • If using enableStrictParsing in urlManager, add:

     'rules' => [
         'debug/<controller>/<action>' => 'debug/<controller>/<action>',
     ],
     

3. IP Restrictions:

   • allowedIPs defaults to ['127.0.0.1', '::1']. Add your IP for remote access:

     'allowedIPs' => ['192.168.1.100', '127.0.0.1'],
     

4. Performance Overhead:

   • Debug mode (YII_DEBUG = true) slows down requests. Disable in production:

     defined('YII_DEBUG') or define('YII_DEBUG', false);
     

5. Panel Conflicts:

   • Third-party panels may override core panels. Explicitly list required panels:

     'panels' => [
         'db' => ['class' => 'yii\debug\panels\DbPanel'],
         'request' => ['class' => 'yii\debug\panels\RequestPanel'],
     ],
     

Debugging Tips

1. Toolbar Not Showing:

   • Check YII_DEBUG is true and bootstrap includes 'debug'.
   • Verify no JavaScript errors block toolbar rendering (inspect console).

2. Database Panel Issues:

   • Ensure db component is configured in components.
   • Slow queries? Use defaultOrder to sort by execution time:

     'panels' => [
         'db' => [
             'class' => 'yii\debug\panels\DbPanel',
             'defaultOrder' => ['duration' => SORT_DESC],
         ],
     ],
     

3. Custom Panel Data Missing:

   • Implement save() to return data. Empty returns hide the panel.
   • Example:

     public function save() {
         return $this->_collectedData ?: null;
     }
     

4. IDE Links Not Working:

   • For Docker, map container paths to host:

     'tracePathMappings' => [
         '/app' => '/host/path/to/app',
     ],
     

   • Test with file:// URLs first (e.g., ide://open?url=file:///path).

5. Log Viewer Empty:

   • Ensure log component is configured and traceLevel is set:

     'log' => [
         'traceLevel' => YII_DEBUG ? 3 : 0,
         'targets' => [...],
     ],
     

Extension Points

1. Override Panel Templates:

   • Copy vendor/yiisoft/yii2-debug/views to your app’s views/debug and modify (e.g., panel.php).

2. Modify Summary Output:

   • Extend getSummary() to change toolbar appearance:

     public function getSummary() {
         return '<div class="yii-debug-toolbar__block custom-style">' . parent::getSummary() . '</div>';
     }
     

3. Add Custom CSS/JS:

   • Include assets in your layout:

     Yii::$app->view->registerCssFile('@vendor/yiisoft/yii2-debug/web/css/debug.css');
     

4. Disable Specific Panels:

   • Exclude panels globally:

     'panels' => ['db', '!request'], // Disable 'request' panel
     

5. Log Custom Data:

   • Use Yii::debug() or Yii::error() to log app-specific data:

     Yii::debug(['user_id' => Yii::$app->user->id], 'user-session');