Twig Inspector Laravel Package

Product Decisions This Supports

• Build vs. buy for developer tooling — the core decision. This package sits squarely in the "adopt or replicate" bucket. The useful capability is narrow and well understood: annotate rendered Twig output with the template, block, and file:line that produced each fragment. That is a buildable 50–100 line internal helper. The PM question is not "should we have this capability" but "is a require-dev dependency on a one-star, zero-dependent, NOASSERTION-licensed package cheaper than owning a small debug middleware?" Default answer tilts toward build.

• Framework-fit triage, not roadmap. Laravel renders Blade; Twig arrives only through a bridge such as rcrowe/twigbridge. This package is therefore relevant to a minority architecture (Twig-on-Laravel, or Symfony-adjacent services), and only for teams with a recurring class of template-context bugs. It never touches user-facing behavior, so it has no place on a product roadmap — it is an engineering-enablement line item at best.

• Developer-experience investment sizing. The benefit is diagnosability: hours saved per template bug (missing variables, silent nulls, escaping surprises, inheritance confusion) and faster onboarding for engineers new to a template-heavy codebase. Quantify it that way when prioritizing against other DX work — not as a feature.

• Vendor-risk and dependency-governance decisions. One star, zero dependents, single maintainer, no release cadence, no CVE response, and a license that automated tooling could not identify. This package is a worked example for the evaluate-then-fork path in your dependency policy, and a prompt to confirm that policy exists and is enforced (e.g., a CI check that blocks non-dev autoload of unvetted packages).

• Production-safety decision. Template inspectors inject markup into responses. If mis-gated, that corrupts JSON/XHR payloads, breaks snapshot and contract tests, trips CSP, and leaks template paths. The PM-relevant decision is whether the enablement guard lives in code or in documentation — documentation-only guards are not controls.

When to Consider This Package

Consider it only when all of the following hold:

• The service genuinely renders Twig (via TwigBridge or a Symfony/Twig component), not Blade. For a Laravel + Blade codebase this is a no-go; Blade-native tooling, Telescope, and Debugbar cover the same need with none of the risk.
• You have a measurable, recurring class of template bugs that logs, dd(), {{ dump() }}, and Xdebug handle poorly — you can name the pain, not just imagine it.
• You will treat it as dev-only: require-dev, pinned to a commit SHA rather than a floating constraint, registered through a thin internal adapter that no-ops outside local/dev, with no production deployment path.
• Legal has read the LICENSE file and cleared it, or you intend to fork and relicense the useful 20% under your own terms. NOASSERTION means "unidentified," not "permissive" — do not let it into a commercial repo on assumption.

Look elsewhere or build in-house when:

• You are on standard Blade — the premise does not apply.
• You need maintained, supported tooling. No community backstop exists, so support is internal by definition and any incident routes to the adopting team.
• The license cannot be resolved to something permissive. An unclear license is a durable liability, not a one-time review cost.
• Your need is production observability rather than local debugging — Telescope, Sentry, or OpenTelemetry are the correct answers and are actively maintained.
• A half-day spike shows the inspector duplicates what a small internal debug panel would give you, with code you own and can license cleanly.

Recommended path before any adoption: timebox a half-day spike (one engineer, one representative Twig service, behind a debug flag) plus a license read. Measure bytes added per response, snapshot/assertion breakage, and compiled-template cache behavior. If both gates pass, fork internally and own it; if either fails, close the ticket and document why.

How to Pitch It (Stakeholders)

For executives (30 seconds): "A small open-source helper that would make a specific kind of template bug faster to diagnose. It is free but unmaintained, has essentially no users, and its license is unclear — so we are not adopting it as a dependency. Recommendation: a half-day evaluation, and if the pattern is useful we copy it into our own tooling. No budget impact, no product risk, no user-facing change."

For engineering leadership: "Dev-only tooling for a minority stack — Twig-on-Laravel rather than Blade. The benefit is diagnosis speed on template-context bugs; the cost is a require-dev dependency with a single maintainer, one star, zero dependents, and an unresolved license, plus a permanent compatibility-maintenance line item at every Twig/Symfony/PHP upgrade. I would rather own a small internal inspector than inherit an unmaintained one — the spike tells us which is cheaper. Either way this is engineering enablement, not roadmap."

For the engineering team: "Worth 30 minutes: clone it, point it at a Twig-rendering service in local, and see whether its output beats {{ dump() }} plus Xdebug for 'which template produced this div?' If it does, we reimplement the useful part internally under our own license and add a CI guard so it can never reach a non-dev environment. Don't add it to composer.json yet."