Yii2 Debug Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

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

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

2. First Use Case:

   • Enable YII_DEBUG = true in your index.php or index-test.php.
   • Visit any page in your app. A toolbar appears at the bottom with:
     • Request info (time, memory, route).
     • Logs (if configured).
     • Database queries (if DB component is enabled).
     • Errors (if any occurred).

3. Where to Look First:

   • Toolbar: Quick overview of the request (click to expand).
   • Debug Panel: Access via /debug/default/view (shows detailed request data).
   • Logs Panel: /debug/default/log (view all logged messages).
   • DB Panel: /debug/default/db (query logs, execution times).

Implementation Patterns

Core Workflows

1. Debugging a Request:

   • Use the toolbar to check execution time, memory usage, and route.
   • Click the toolbar to expand panels (logs, DB, errors).
   • Navigate to /debug/default/view for a full request dump (headers, POST/GET data, cookies, etc.).

2. Database Debugging:

   • Enable the DB panel by ensuring your db component is configured in components.
   • View queries in /debug/default/db with:
     • Execution time per query.
     • Bind parameters.
     • Query duration trends (graph).
   • Configure default sorting/filtering:

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

3. Customizing Logs:

   • Configure the log component to include debug-level messages:

     'components' => [
         'log' => [
             'traceLevel' => YII_DEBUG ? 3 : 0,
             'targets' => [
                 [
                     'class' => 'yii\log\FileTarget',
                     'levels' => ['error', 'warning', 'trace'],
                 ],
             ],
         ],
     ],
     

   • View logs at /debug/default/log.

4. Profiling:

   • Use the profile panel to track:
     • Component initialization time.
     • Event handling durations.
   • Access via /debug/default/profile.

5. IDE Integration:

   • Configure traceLine for direct file/line jumps in your IDE:

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

   • For Docker/virtualized environments, use tracePathMappings:

     'tracePathMappings' => [
         '/app' => '/absolute/path/to/your/app',
     ],
     

6. Environment-Specific Debugging:

   • Restrict debug access to specific IPs (e.g., staging):

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

   • Disable in production:

     if (YII_ENV_PROD) {
         unset($config['bootstrap'][array_search('debug', $config['bootstrap'])]);
         unset($config['modules']['debug']);
     }
     

Integration Tips

1. URL Manager: If using enableStrictParsing, add this rule:

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

2. Custom Panels: Extend yii\debug\Panel to create reusable debug panels (e.g., for tracking rendered views, cache hits, or custom metrics). Example:

   namespace app\panels;
   use yii\debug\Panel;
   
   class CachePanel extends Panel {
       public function getName() { return 'Cache'; }
       public function getSummary() { /* ... */ }
       public function getDetail() { /* ... */ }
       public function save() { return $this->cacheStats; }
   }
   

   Register in config:

   'panels' => [
       'cache' => ['class' => 'app\panels\CachePanel'],
   ],
   

3. JavaScript Integration: Listen for the yii.debug.toolbar_attached event to interact with the toolbar dynamically:

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

4. Performance Monitoring:

   • Use the memory and time panels to identify bottlenecks.
   • Correlate slow queries (DB panel) with high memory usage.

5. Error Debugging:

   • The errors panel shows exceptions, warnings, and deprecations.
   • Use YII_DEBUG to control verbosity:

     defined('YII_DEBUG') or define('YII_DEBUG', true); // Enable full debugging
     

Gotchas and Tips

Pitfalls

1. Permission Issues:

   • Ensure the @runtime/debug directory is writable by the web server user.
   • Symptoms: Blank toolbar, missing debug data, or "Permission denied" errors.
   • Fix: Run chmod -R 775 runtime/debug (adjust permissions as needed).

2. Strict Parsing Conflicts:

   • If using enableStrictParsing, forget the debug/ rule, and the toolbar/debug panels will 404.
   • Fix: Add the rule as shown in the Integration Tips section.

3. IP Restrictions:

   • Forgetting to add your IP to allowedIPs in non-local environments will hide the toolbar.
   • Fix: Uncomment and update:

     'allowedIPs' => ['your.ip.here', '127.0.0.1'],
     

4. IDE Links Not Working:

   • If traceLine links don’t open in your IDE:
     • Ensure the IDE protocol is registered (e.g., phpstorm:// for PhpStorm).
     • For Docker, verify tracePathMappings points to the correct host path.
   • Fix: Test with a simple file:// link first:

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

5. Performance Overhead:

   • Debugging adds ~10-30ms per request. Disable in production:

     if (YII_ENV_PROD) {
         $config['bootstrap'] = array_filter($config['bootstrap'], fn($item) => $item !== 'debug');
     }
     

6. Missing Panels:

   • If a panel (e.g., DB) doesn’t appear:
     • Ensure the corresponding component (e.g., db) is configured in components.
     • Check for typos in the panel class name or path.

7. Log Overload:

   • Setting traceLevel too high (e.g., 3) in production can bloat logs.
   • Fix: Use YII_DEBUG to toggle:

     'traceLevel' => YII_DEBUG ? 3 : 0,
     

Debugging Tips

1. Toolbar Not Showing?:

   • Check YII_DEBUG is true in index.php.
   • Verify the debug module is bootstrapped and configured.
   • Inspect browser console for errors (e.g., failed JS/CSS loads).

2. Debug Data Not Persisting:

   • Ensure @runtime/debug is writable.
   • Check PHP error logs for write permission issues.

3. Custom Panel Not Loading:

   • Verify the panel class path is correct (e.g., app\panels\CachePanel).
   • Ensure the panel is registered in panels config:

     'panels' => ['cache' => ['class' => 'app\panels\CachePanel']],
     

4. Slow Debug Panels:

   • Large log files or DB queries can slow down /debug/default/view.
   • Filter logs or queries in the panel’s UI to improve performance.

5. Docker-Specific Issues:

   • If paths in traceLine are incorrect, use tracePathMappings:

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