Twigmetrics Laravel Package

Technical Evaluation

Architecture fit. twigmetrics is a Twig template-metrics tool, not a Laravel-first package. Laravel's default view layer is Blade, so fit against a stock Laravel app is poor unless the team already runs Twig via a bridge (e.g. twigbridge) or the real target is a Symfony/Twig codebase being assessed alongside Laravel services. Architecturally it is a dev-time/static-analysis tool: it sits outside the request path, adds no service provider or container coupling, and cannot affect production runtime. That keeps architectural risk low even if domain fit is questionable.

Integration feasibility. Installing is trivial (composer require --dev). Producing value is not: it needs a wired command, a defined template path, and a CI job that emits a report artifact. The v1.1.0 "Add Charts" change implies HTML/visual output, and it is unconfirmed whether that output is self-contained or pulls JS/CSS from a CDN — a real blocker for air-gapped CI.

Technical risk. v1.1.0 is only the second tagged release, from a single maintainer, off a three-PR history. Bus factor is 1, and there is no evidence yet of a BC policy or a thick test suite. The "Rework Dimension Metrics" item is the specific concern: it changes how metrics are calculated inside a minor release, which means any baseline captured on v1.0.x may not be comparable to v1.1.0 output. Security/production risk is near zero (dev-only); churn risk is moderate-to-high.

Key questions.

• Does it operate on Blade at all, or is Twig a hard requirement?
• Is the chart output standalone HTML, or does it require network assets?
• Are metric dimension definitions versioned/documented, and is the rework a rename, a formula change, or both?
• What are the PHP and Twig version constraints, and do they conflict with our runtime?
• License and stewardship: hobby project or funded? Any stated support expectation?

Integration Approach

Stack fit. Composer-native, so it drops into any PHP 8.x/Laravel repo as a dev dependency. The decision point is not installation but the view layer. If we are Blade-only, the honest answer is to run this as a standalone CI-side tool against Twig templates in the repos that have them, rather than introducing a Twig bridge into a Laravel app purely to satisfy a metrics tool — that would be a large architectural commitment bought for a small reporting benefit.

Migration path. None required; the tool is additive and touches no application code. Introduce it on a scratch branch, point it at the template directory, and capture a baseline report. Do not gate CI on thresholds in the first pass — the metric rework in this very release shows the numbers are not yet stable enough to fail builds on.

Compatibility. Pin ^1.1 with a committed composer.lock, and verify the PHP constraint against our runtime before merging. Given that a minor release reworked metric definitions, treat every 1.x bump as potentially output-changing and diff the report rather than trusting semver.

Sequencing.

1. Spike in a throwaway branch; answer the Blade-vs-Twig question first — it is a go/no-go.
2. If Twig-only and we are Blade-only, stop and evaluate alternatives; do not adopt a bridge for this.
3. Otherwise, generate a baseline report and review the output with the team that owns the templates.
4. Add as an advisory (non-blocking) CI step publishing an artifact.
5. Revisit threshold enforcement only after two or three further upstream releases show metric definitions settling.

Operational Impact

Maintenance. Dev-only, so blast radius is confined to CI and developer machines. The recurring cost is upgrade review, not runtime upkeep — each minor bump needs a report diff until the metric schema stabilises.

Support. Single maintainer, small project, no vendor relationship. Assume best-effort upstream response and budget for the possibility of vendoring a patch or forking. Name an internal owner for tracking releases so this does not silently rot in composer.json.

Scaling. Report cost scales with template count and file size; fine for typical repos, worth watching on monorepos with thousands of templates. Chart output adds artifact size — set retention limits on the CI artifact store.

Failure modes.

• Metric-definition drift silently invalidating historical comparisons (already observed once, at v1.1.0).
• Chart rendering failing in headless/air-gapped CI due to missing extensions or external assets.
• PHP/Twig constraint conflicts with the host application.
• Upstream abandonment leaving us pinned to an unmaintained dev dependency.
• Team misinterpretation: dimension metrics read as quality gates before anyone has calibrated what "good" looks like for our templates.

Ramp-up. Low to run the command, moderate to interpret dimension metrics and set defensible thresholds. Budget roughly a day for the spike plus a short internal write-up, and treat the first two sprints of output as calibration rather than signal.