Twig Inspector Laravel Package

Getting Started

Before doing anything, confirm the premise: this package inspects Twig templates, and Laravel ships Blade. There is no value here unless your app renders Twig — typically via rcrowe/twigbridge or a legacy Symfony front-end served alongside a Laravel API. If you can't point at a .twig file that gets rendered in your stack, stop and close the tab.

Assuming you do render Twig:

1. Read the repo before installing. At 1 star and 0 dependents this is effectively unreleased software. Open composer.json and the README and look for:
   • An extra.laravel.providers entry (auto-discovery) or a Symfony Bundle class.
   • Tagged releases (if only dev-main, you'll pin by commit SHA).
   • Stated Twig/Symfony/PHP version support.
2. Install as dev-only, pinned:

   composer require --dev hec-franco/twig-inspector
   

   Then immediately commit an exact constraint — "dev-main#<sha>" if there are no tags. Do not float on ^1.0; there is no release history to protect you.
3. Resolve the license before merging. NOASSERTION means Composer could not identify the license from metadata. Open LICENSE and read it. An unclear license is a hard gate, even for require-dev.
4. Register it (manually if needed). If there's no auto-discovery, add a thin service provider in app/Providers/ (or config/app.php) and have it no-op outside local.

First use case, in order:

• Boot the app in local with APP_DEBUG=true.
• Render a page with a deep template chain (layout.twig → section.twig → component.twig).
• Use View Source, not DevTools Elements. HTML comments are stripped from the rendered DOM tree; the whole point is to read the raw markup.
• Look for the injected comments/attributes and confirm they name the template and ideally file:line. That's the payoff — "which template emitted this <div>?"

If the output doesn't beat {{ dump() }} + Xdebug in the first ten minutes, stop. The package's only job is to be faster than your existing debugging loop.

Implementation Patterns

Gate on environment in code, not documentation. Register the insprector's extension against the Twig Environment only when app()->environment('local') and a dedicated flag (e.g. TWIG_INSPECTOR=true) are both true. A single mis-set env var across shared dev/staging is how this tool ends up leaking template paths into a staging response.

Wire it through TwigBridge, not the package. The inspector needs to decorate the same Environment instance TwigBridge renders through. Get the environment from the container (typically the twig binding) and register the extension/node-visitor there. Write the adapter yourself and own it — don't assume the package provides Laravel glue.

// app/Providers/TwigInspectorServiceProvider.php (skeleton)
public function register(): void
{
    if (! $this->app->environment('local') || ! env('TWIG_INSPECTOR', false)) {
        return;
    }
    // Defer: resolve twig environment after TwigBridge has booted.
}

Workflow pattern — enable, inspect, disable. Treat this like Debugbar: on when you're actively chasing a "where did this come from?" bug, off otherwise. Keep it out of your default local bootstrap if your test suite renders Twig, because injected markup will break snapshot assertions (see Gotchas).

Pair it with targeted logging. The inspector tells you which template; it does not tell you what variables were in scope. Combine it with a small middleware or a Twig dump extension to print the context array for the template you just identified. That two-step (locate template → inspect its context) is the actual diagnostic loop this tool accelerates.

Don't use it for production observability. Scope it strictly to local development. If you need to understand template rendering in staging/production, reach for structured logging, Sentry breadcrumbs, or an OpenTelemetry span around the render — not markup injection.

CI guard. Add a check that fails if hec-franco/twig-inspector appears in the non-dev autoload/require graph. It's a two-line composer show --no-dev grep and it prevents the most expensive misuse of this package.

Gotchas and Tips

• DevTools will lie to you. Injected HTML comments don't appear in the DOM tree — they're parsed and dropped. Always use View Source or curl the page.
• Non-HTML responses get corrupted. If the inspector runs unconditionally it will inject comments into JSON, XML, RSS, or email bodies, breaking clients and contract tests. Gate by request Accept header or route, not just environment.
• Snapshot/contract tests break. Any test that asserts exact response HTML will fail once markers are present. Either disable the inspector in the test environment (APP_ENV=testing, not local) or update snapshots — but don't let it silently leak into CI comparisons.
• CSP and client-side parsers. Injected data-* attributes or comments can trip a strict CSP, break naive HTML parsers in JS, and inflate response bytes. Measure the delta on one representative page before you roll it out across a team.
• Information disclosure. The markers typically include template file paths. If this ever runs on a staging box reachable by non-engineers, that's a leak. Env-gate in code, not in a wiki page.
• Compiled-template cache interaction. Template inspectors usually hook the compile step (node visitors, extensions). After enabling/disabling, clear the compiled Twig cache — you may otherwise see stale output without markers or markers on the wrong template, and waste an hour debugging the debugger.
• Twig major-version breakage. Twig 2 → 3 changed extension APIs. With one maintainer and no dependents, there is no compatibility work happening upstream. Pin Twig too, and treat any Twig upgrade as a required re-test of this integration.
• License is not resolved. NOASSERTION blocks adoption regardless of everything else. Get a human to read LICENSE and sign off before code enters the monorepo — even as require-dev.
• Extension point if you fork: the useful 20% here is template-name → HTML comment injection. If the package fights you, that's roughly 50–100 lines of your own Twig extension or middleware, under your own license, with your own guard. Weigh that against the cost of pinning and maintaining a fork of an unmaintained single-maintainer package before committing to either.