Twigmetrics Laravel Package

Product Decisions This Supports

• Roadmap investment in the template layer. TwigMetrics turns an otherwise invisible part of the codebase (Twig templates) into scored, comparable numbers. v1.1.0's reworked Dimension Metrics makes those scores more defensible as an input to "do we refactor the design system / componentize these templates this quarter?" decisions, rather than relying on anecdote and gut feel.
• Build vs. buy (adopt). The alternative is an in-house Twig linter/metrics script that someone has to own forever. Adopting a small, focused OSS analyzer is almost always cheaper than building static analysis; this release strengthens that case by adding a reporting layer (charts) we would otherwise have had to build.
• Prioritization and ranking. Dimension scores let you rank bundles/areas/templates against each other, so a refactor backlog can be ordered by measured template debt instead of by whoever complained loudest.
• CI quality gating. Usable as a non-blocking (then blocking) check on template-heavy PRs — a "template risk score" alongside PHPStan/Psalm coverage of the PHP side.
• Stakeholder communication. The new Charts in v1.1.0 are the strategically interesting part: they turn a developer-only report into a one-page artifact that engineering managers and product leads can read. That unlocks recurring rituals (template health review, pre-refactor baseline, post-refactor before/after).
• Buying signal / risk caveat for v1.1.0 specifically: the Rework Dimension Metrics change means scores are not directly comparable to v1.0.x output. Any threshold, dashboard, or historical trend built on v1.0.x must be re-baselined. Treat this as a metric-definition change, not a bug fix — snapshot before upgrading.

When to Consider This Package

Consider it when most of these hold:

• You have a non-trivial Twig templating layer — a Symfony app, a CMS/theme layer, a design system, or a Laravel project running a Twig bridge. "Non-trivial" roughly means dozens-to-hundreds of templates with shared includes/macros.
• You already measure the PHP side (PHPStan, Psalm, phpmetrics, coverage) but have zero quantitative visibility into templates — the typical gap this fills.
• You want static, deterministic analysis: no runtime instrumentation, no production traffic, no data leaving CI. That makes it viable in regulated or privacy-sensitive environments where APM-style tooling is a procurement fight.
• You have someone willing to own baselines and threshold tuning. Metrics tools decay into noise without an owner; budget a small, explicit maintenance allocation.
• You are pre-refactor and want a defensible "before" number.

Look elsewhere, or deprioritize, when:

• Blade-only Laravel. Laravel's default templating is Blade, not Twig. If there is no Twig in the stack, this package does not apply — the honest recommendation is Blade-specific linting and custom rules, not this.
• You need runtime performance (render time, query counts, memory per request). That is Blackfire/Telescope/Debugbar territory; static metrics answer "how complex is this," not "how slow is this."
• You need a unified PHP + template metric model, vendor support, or an SLA. This is a single-maintainer OSS project; the release history here is short (v1.0.1 → v1.1.0), so bus-factor risk is real. Pin the version.
• The template surface is small. With a handful of templates, baselining and threshold tuning cost more than the insight is worth.
• You cannot tolerate churn in metric definitions. v1.1.0 just demonstrated that scores can move because the definition changed. If you need a stable index you publish externally, validate over at least one more minor release first.

Given the thin evidence base (release notes only, no hands-on trial), the responsible next step is a one-spike validation — run v1.1.0 against the highest-churn template area, confirm the charts and dimension output are trustworthy and stable, then decide.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have strong quality signals for our PHP code and essentially none for our templates, which is where a growing share of UI complexity now lives. TwigMetrics is a small, free, open-source static analyzer that scores Twig templates and, as of v1.1.0, renders those scores as charts — giving us a readable "template health" page without adding any runtime dependency, production footprint, or vendor contract. The ask is roughly one engineer-day: pilot it on our most-churned templates, produce a baseline and a chart, and decide whether it becomes a standing CI gate and a recurring input to refactor planning.

For engineering leads: It is a dev-only dependency plus a CI step — no instrumentation, no data collection, deterministic output. It complements, not replaces, PHPStan/Psalm and runtime profiling. Two things to plan for: (1) v1.1.0 reworks how Dimension Metrics are calculated, so existing scores and thresholds from v1.0.x must be re-baselined and treated as a new metric definition; (2) it is a young, single-maintainer project, so pin the version and keep the CI step non-blocking until we have two or three releases of stable numbers. If the stack is Blade-only, this does not apply and we should not spend the day.