Laravel Blade Comments Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-blade-comments
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Spatie\BladeComments\BladeCommentsServiceProvider"
   

2. First Use Case: Enable the package in config/blade-comments.php:

   'enabled' => env('BLADER_COMMENTS_ENABLED', false),
   

   Set the environment variable:

   BLADER_COMMENTS_ENABLED=true
   

   Restart your dev server. Now inspect any rendered Blade view in your browser’s dev tools—you’ll see comments like:

   <!-- Blade view: resources/views/layouts/app.blade.php -->
   

Where to Look First

• Config File: config/blade-comments.php (customize comment style, exclusions, or enabled routes).
• Service Provider: Spatie\BladeComments\BladeCommentsServiceProvider (registers middleware).
• Middleware: Spatie\BladeComments\Middleware\AddBladeComments (core logic).

Implementation Patterns

Core Workflow

1. Enable for Specific Routes: Use middleware in routes/web.php:

   Route::middleware(['web', 'blade.comments'])->group(function () {
       // Routes where comments are enabled
   });
   

2. Conditional Rendering: Disable comments for specific views in config/blade-comments.php:

   'exclude_views' => [
       'layouts.app',
       'emails.*',
   ],
   

3. Custom Comment Styling: Override the default comment template in the config:

   'comment_template' => '<!-- [VIEW: {{view}}] [LINE: {{line}}] -->',
   

4. Integration with Debugging Tools: Combine with laravel-debugbar or telescope for deeper insights:

   // In Telescope config
   'panels' => [
       \Spatie\BladeComments\Telescope\BladeCommentsPanel::class,
   ],
   

Advanced Patterns

• Dynamic Enablement: Toggle comments via a route parameter:

  Route::get('/debug', function () {
      config(['blade-comments.enabled' => request('enable') === 'true']);
      return view('home');
  });
  

• Component-Specific Comments: Use @comment directive in Blade:

  @comment('Custom section label')
  <div>...</div>
  

• CI/CD Exclusion: Disable in production via .env:

  BLADER_COMMENTS_ENABLED=${APP_ENV !== 'local'}
  

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Comments add minimal overhead (~1-2ms per request), but disable in staging/prod:

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

2. False Positives in Exclusions:

   • Wildcards in exclude_views may unintentionally skip critical views. Test exclusions:

     'exclude_views' => [
         'auth.*', // Excludes all auth views
     ],
     

3. Caching Conflicts:

   • Ensure Blade views aren’t cached when comments are enabled:

     'cache_views' => false, // In config/app.php
     

4. Nested Component Comments:

   • Deeply nested components (e.g., Alpine.js slots) may generate overlapping comments. Use @comment sparingly.

Debugging Tips

• Verify Middleware: Check if the middleware is registered in App\Http\Kernel.php:

  protected $middlewareGroups = [
      'web' => [
          \Spatie\BladeComments\Middleware\AddBladeComments::class,
          // ...
      ],
  ];
  

• Inspect Output: Search for <!-- Blade view: in the page source to confirm comments are rendering.

• Log Exclusions: Add debug logging for excluded views:

  'log_excluded_views' => true, // In config
  

Extension Points

1. Custom Directives: Extend the package by adding a directive (e.g., @debug):

   // In a service provider
   Blade::directive('debug', function ($expression) {
       return "<?php echo '<!-- DEBUG: {$expression} -->'; ?>";
   });
   

2. Event Listeners: Listen for blade.comments.rendered events to post-process comments:

   Event::listen('blade.comments.rendered', function ($view, $content) {
       $content = str_replace('<!-- Blade view:', '<!-- CUSTOM: ', $content);
       return $content;
   });
   

3. Testing: Mock comments in PHPUnit:

   $this->withoutMiddleware(\Spatie\BladeComments\Middleware\AddBladeComments::class);