Getting Started

Minimal Steps

Installation:
```
composer require spatie/laravel-blade-comments --dev
```
- Automatically enabled in APP_DEBUG mode (configurable via blade-comments.enable).
- No additional setup required for basic usage.
First Use Case:
- Open your browser’s DevTools (e.g., Chrome/Firefox) and inspect any rendered Blade view.
- Look for HTML comments like:
```


```
- These wrap every Blade file, making it trivial to trace rendered HTML back to its source.
Where to Look First:
- Config File: Publish and review config/blade-comments.php to adjust exclusions or middleware.
- Middleware: Ensure Spatie\BladeComments\Http\Middleware\AddRequestComments is registered in app/Http/Kernel.php (it is by default).
- Exclusions: Check excludes.includes and excludes.sections to avoid cluttering partials or meta tags.

Implementation Patterns

Core Workflows

Debugging Blade Renders:
- Inspect Hierarchy: Use the top-level comment (e.g., ) to identify the root view.
- Trace Components: Livewire/Blade components (e.g., @component('widget.card')) are auto-detected and commented.
- Section Yields: @yield('section-name') directives are wrapped with comments, even in nested layouts.
Integration with Existing Tools:
- Browser DevTools: Right-click → "Inspect" to jump to the Blade file (VS Code/Laravel IDE Helper integration works seamlessly).
- CI/CD: Disable in production by setting APP_DEBUG=false or overriding blade-comments.enable=false in .env.

Custom Commenters:

Extend BladeCommenter: Add support for custom directives (e.g., @myDirective):

namespace App\BladeComments;

use Spatie\BladeComments\Commenters\BladeCommenters\BladeCommenter;

class MyDirectiveCommenter implements BladeCommenter {
    public function pattern(): string { return '/@myDirective\s*(.*?)\s*/'; }
    public function replacement(): string { return '<!-- BEGIN: @myDirective $1 -->$0<!-- END: @myDirective -->'; }
}

'blade_commenters' => [
    // ... default commenters
    App\BladeComments\MyDirectiveCommenter::class,
],

Request Metadata:

Leverage RequestCommenter to inject custom data (e.g., user agent, request duration):

namespace App\BladeComments;

use Spatie\BladeComments\Commenters\RequestCommenters\RequestCommenter;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class UserAgentCommenter implements RequestCommenter {
    public function comment(Request $request, Response $response): ?string {
        return "<!-- User Agent: {$request->userAgent()} -->";
    }
}

Add to request_commenters in config.

Pro Tips

Performance: Comments are only added in debug mode (APP_DEBUG=true). Zero overhead in production.
Livewire 4+: Supports component resolution via BladeComponentCommenter (no manual setup needed).
Exclude Strategically: Use excludes.includes for CSS/JS partials (e.g., 'styles.main') to avoid noise.
AST-Based Parsing: Since v2.0, the package uses Laravel’s Blade AST parser (more reliable than regex for complex directives).

Gotchas and Tips

Pitfalls

False Positives in Excludes:
- Issue: Partial matches in excludes.includes (e.g., 'header' might exclude 'header.partial').
- Fix: Use full paths (e.g., 'partials.header') or regex patterns in the config:
```
'excludes' => [
    'includes' => [
        '/^styles\./', // Exclude all files starting with "styles."
    ],
],
```
Conditional Includes:
- Issue: @include('partial', ['key' => $value]) may fail if $value is undefined.
- Fix: Ensure all included views are resolvable or use try-catch in custom commenters.
Middleware Order:
- Issue: Comments might not appear if AddRequestComments runs after the response is sent.
- Fix: Place it before StartSession and ShareErrorsFromSession in Kernel.php:
```
protected $middleware = [
    // ...
    \Spatie\BladeComments\Http\Middleware\AddRequestComments::class,
    // ...
];
```

Livewire Component Namespaces:

Issue: Custom Livewire components (e.g., App\Livewire\Admin\Dashboard) may not resolve correctly.

Fix: Extend LivewireComponentCommenter to handle namespaced classes:

class CustomLivewireCommenter extends \Spatie\BladeComments\Commenters\BladeCommenters\LivewireComponentCommenter {
    protected function resolveClass(string $class): ?string {
        return class_exists($class) ? $class : null;
    }
}

Debugging

Missing Comments:
- Verify APP_DEBUG=true in .env.
- Check if the middleware is registered in Kernel.php.
- Run php artisan config:clear if config changes aren’t reflected.
Malformed Comments:
- Ensure Blade files are not minified (comments won’t render in minified output).
- Use php artisan view:clear to regenerate cached views.

Extension Points

Dynamic Exclusions:

Override excludes via a service provider:

public function boot() {
    config(['blade-comments.excludes.includes' => array_merge(
        config('blade-comments.excludes.includes'),
        ['dynamic.partial']
    )]);
}

Conditional Commenting:

Disable comments for specific routes:

Route::middleware(['web', 'blade-comments:disable'])->group(function () {
    // Comments will be skipped here
});

Add this middleware to Kernel.php:

protected $routeMiddleware = [
    'blade-comments.disable' => \Spatie\BladeComments\Http\Middleware\DisableBladeComments::class,
];

Custom Comment Formatting:

Modify the comment template by extending BladeCommentsPrecompiler:

class CustomPrecompiler extends \Spatie\BladeComments\BladeCommentsPrecompiler {
    protected function wrapWithComments(string $content, string $path): string {
        return "<!-- CUSTOM: $path -->$content<!-- /CUSTOM -->";
    }
}

Update the config:

'precompiler' => App\BladeComments\CustomPrecompiler::class,

Performance Quirks

Large Views: Comments add negligible overhead (~1ms per view in debug mode). Monitor with:
```
php artisan debugbar:enable
```
Caching: Blade comments are not cached in production (disabled by APP_DEBUG). No impact on view:cache.

Laravel Blade Comments Laravel Package