Yii2 Dev Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require yiisoft/yii2-dev
   

   Ensure your composer.json includes the package under require-dev if using it only for development. Note: Verify PHP version compatibility (Yii 2.0.55+ requires PHP 7.4+; templates now target newer PHP versions).

2. First Use Case:

   • Debugging: Use yii\debug\Module for interactive debugging tools (e.g., database queries, logs, memory usage).
     • Enable via Yii::$app->set('enableProfiling', true) and access the toolbar at http://your-app.dev/?debug=1.
   • GridView Filtering: Leverage the new filterSelector Closure support in yii\grid\GridView for dynamic filtering:

     'filterSelector' => function($model, $attribute) {
         return $model->getAttributeFilters()[$attribute] ?? null;
     },
     

3. Where to Look First:

   • Debug Toolbar: Accessible via http://your-app.dev/?debug=1 (if enabled in config/web.php).
   • Configuration: Check config/web.php for pre-configured debug tools (e.g., modules['debug']).
   • Security: Review View::renderPhpFile() and ErrorHandler::renderFile() for updated parameter isolation (CVE-2026-39850).

Implementation Patterns

Debugging Workflows

1. Interactive Debugging:

   • Database Queries: Use the "Queries" tab in the debug toolbar to inspect slow queries.
   • Logs: View real-time logs via the "Logs" tab or configure yii\debug\LoggerTarget in config/web.php:

     'components' => [
         'log' => [
             'targets' => [
                 'debug' => [
                     'class' => 'yii\debug\LoggerTarget',
                     'categories' => ['yii\db\*'],
                     'levels' => ['error', 'warning'],
                 ],
             ],
         ],
     ],
     

2. Profiling:

   • Enable profiling in config/web.php:

     'components' => [
         'profiling' => [
             'class' => 'yii\debug\Profiler',
             'settings' => [
                 'triggers' => [
                     'yii\db\Command::execute' => ['yii\debug\DbTrigger'],
                 ],
             ],
         ],
     ],
     

   • View results in the "Profiling" tab of the debug toolbar.

3. Error Handling:

   • Customize error pages by configuring yii\web\ErrorHandler:

     'components' => [
         'errorHandler' => [
             'errorAction' => 'site/error',
             'exceptionAction' => 'site/error',
         ],
     ],
     

   • Security Note: Updated ErrorHandler::renderFile() now isolates internal variables to prevent path collisions.

Integration Tips

1. Conditional Debugging:

   • Disable debug tools in production by checking YII_ENV:

     if (YII_ENV_DEV) {
         $this->module->enabled = true;
     }
     

2. Custom Debug Panels:

   • Extend yii\debug\Panel to create custom panels (e.g., for monitoring third-party services):

     class MyServicePanel extends \yii\debug\Panel {
         public $name = 'My Service';
         public $icon = 'cloud';
         public $defaultPos = 10;
     
         public function collect() {
             return ['status' => 'ok', 'last_check' => time()];
         }
     
         public function getData() {
             return $this->collect();
         }
     }
     

   • Register in config/web.php:

     'modules' => [
         'debug' => [
             'panels' => [
                 'myService' => 'app\debug\panels\MyServicePanel',
             ],
         ],
     ],
     

3. GridView Enhancements:

   • Use the new filterSelector Closure support for dynamic filtering:

     GridView::widget([
         'dataProvider' => $dataProvider,
         'filterSelector' => function($model, $attribute) {
             return $model->getDynamicFilters()[$attribute] ?? null;
         },
     ]);
     

4. Asset Bundling:

   • Use yii\web\AssetBundle for debug-specific assets (e.g., CSS/JS for debug tools):

     class DebugAssets extends AssetBundle {
         public $sourcePath = '@vendor/yiisoft/yii2-dev/assets';
         public $css = ['debug.css'];
     }
     

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Debug tools add overhead. Disable them in production:

     if (!YII_ENV_DEV) {
         Yii::$app->set('enableProfiling', false);
     }
     

   • Avoid using yii\debug\Module in CLI applications (it’s web-only).

2. Cache Invalidation:

   • Debug toolbar caches data (e.g., queries, logs). Clear cache manually if stale data appears:

     php yii cache/flush
     

3. Key Conflicts:

   • If using multiple apps with shared cache (e.g., Redis), prefix keys to avoid collisions:

     $cache->set('app1_' . $key, $value);
     

4. Security Fixes:

   • CVE-2026-39850: Updated View::renderPhpFile() and ErrorHandler::renderFile() now isolate internal variables. Ensure custom views/handlers comply with this change to avoid path collisions.

5. PHP Version Compatibility:

   • Yii 2.0.55+ drops support for obsolete PHP versions (<7.4). Update templates to target newer PHP versions if needed.

Debugging Tips

1. Xdebug Integration:

   • Configure php.ini for Xdebug:

     xdebug.mode=debug
     xdebug.start_with_request=yes
     

   • Use yii\debug\XdebugPanel for IDE integration.

2. Log Filtering:

   • Filter logs by category/level in LoggerTarget:

     'targets' => [
         'debug' => [
             'categories' => ['yii\db\*', 'app\models\*'],
             'levels' => ['error', 'warning', 'info'],
         ],
     ],
     

3. Custom Error Actions:

   • Handle errors gracefully by extending yii\web\ErrorAction:

     class CustomErrorAction extends \yii\web\ErrorAction {
         public function run() {
             if (YII_ENV_DEV) {
                 return parent::run();
             }
             return $this->controller->render('error');
         }
     }
     

   • Register in config/web.php:

     'components' => [
         'errorHandler' => [
             'errorAction' => 'site/custom-error',
         ],
     ],
     

4. PHPDoc Annotations:

   • Leverage improved PHPDoc annotations (e.g., generics, conditional types) for better IDE support:

     /**
      * @param array<string, mixed> $data
      * @return array<string, mixed>
      */
     public function processData(array $data): array { ... }
     

Extension Points

1. Custom Panels:

   • Extend yii\debug\Panel for domain-specific insights (e.g., queue status, external API calls).

2. Profiling Triggers:

   • Add custom triggers to yii\debug\Profiler:

     'profiling' => [
         'settings' => [
             'triggers' => [
                 'app\services\MyService::doWork' => ['yii\debug\DbTrigger'],
             ],
         ],
     ],
     

3. Asset Overrides:

   • Override debug assets in config/web.php:

     'modules' => [
         'debug' => [
             'assetBundle' => 'app\assets\DebugAssets',
         ],
     ],
     

4. Environment-Specific Configs:

   • Use config/params-local.php for environment-specific debug settings:

     return [
         'enableProfiling' => YII_ENV_DEV,
         'debugPanels' => ['db', 'memory', 'time'],
     ];
     

5. GridView Filtering:

   • Implement dynamic filtering with Closures in filterSelector:

     'filterSelector' => function($model, $attribute) {
         return $model->getAttributeFilters()[$attribute] ?? null;
     },