Product Decisions This Supports
- Whether to keep server-side page tracking in-house or adopt a bundle. This patch matters because it fixes a silent instrumentation failure: when the Twig
seo_tracking() helper was called without custom dimensions, the rendered dimensions="[]" was rejected by the Stimulus controller before any page hit was sent. Users saw no error; dashboards simply undercounted. Any decision that relies on page-level analytics (content performance, funnel conversion, launch measurement) is only as trustworthy as this path.
- Data-integrity triage in the roadmap. Bugs like this compete with feature work. The PM case for prioritizing 1.7.2 is that a one-line-shaped fix restores correctness for a whole class of pages (all pages without custom dimensions), while the fix itself carries near-zero blast radius.
- Build vs buy for analytics instrumentation. A Twig helper plus a Stimulus controller is a deliberately thin integration. That is a genuine alternative to a tag manager or a heavier client SDK when the requirement is "record page hits, optionally with dimensions" rather than "full experimentation and attribution stack."
- Upgrade decisions with an operational, not functional, cost. The release is a patch, requires no Doctrine migration or backfill, and changes no public API or controller contract. The decision reduces to "recompile the asset map and clear cache in the normal release train" — cheap enough to ride the next deploy, but still a deploy-coupled step that must be scheduled.
- Use cases this supports now: server-rendered content and marketing pages, pages where dimensions are optional or absent, and applications that already pass custom dimensions (their normalization and payload behavior are unchanged).
- A stack-fit caveat worth deciding on explicitly. Despite being framed as a Laravel/PHP package, the artifact is a Symfony bundle: Twig helper, Symfony console command, Stimulus controller, Doctrine compatibility matrix. For a Laravel product, this is not a drop-in; adoption implies either a Symfony service in the estate or a port. That should be settled before it appears on a roadmap.
When to Consider This Package
Consider it when:
- The application is Symfony-based with Twig-rendered pages (the helper and
asset-map:compile step assume this).
- The tracking requirement is bounded: record page hits, with dimensions that may be absent or application-defined.
- You want no schema churn — this release explicitly requires no migration or backfill, and existing custom dimensions and stored data stay compatible.
- You need to close a known data gap: pages without custom dimensions were generating no hits on 1.7.1 and earlier.
- You value a small, auditable surface over a vendor SDK — the public API and JavaScript controller are unchanged here.
Look elsewhere when:
- The stack is Laravel-native. The Twig/Stimulus/Doctrine assumptions do not map cleanly, and you would be buying a port, not a package.
- You need client-side SPA or single-page-navigation tracking, which this server-rendered helper model does not address.
- You need a broader analytics capability — experimentation, attribution, warehouse/ETL, consent management, or vendor-managed tag orchestration. This is instrumentation, not an analytics platform.
- Dimensions are mandatory in your data contract. The release makes empty dimensions valid (
{}), which is the right fix but means downstream consumers must tolerate absent dimensions rather than assume presence.
- You cannot reliably run the asset-map compile and cache clear as part of releases; the fix is inert until the rebuilt asset map ships.
How to Pitch It (Stakeholders)
To executives: This is a low-risk patch that restores tracking on any page that doesn't declare custom dimensions. Until now those pages were silently recording nothing, so reporting has been understating traffic. The upgrade changes no public interfaces, needs no database migration or data backfill, and ships with a regression test. Cost is a routine deploy step: recompile assets, clear cache, release as usual.
To engineering: One behavioral fix — an omitted dimensions map now renders as the JSON object {} instead of [], which the Stimulus controller's Object-typed value can accept. Non-empty dimensions keep the same normalization, validation, and payload path. No controller, configuration, or public API changes; the PHP, Symfony, JavaScript, and database compatibility matrix is unchanged. A regression test pins the empty-object output. Upgrade via composer require zhortein/seo-tracking-bundle:^1.7.2 then php bin/console asset-map:compile, and clear application cache through the normal release process.
To flag up front: Confirm the ecosystem fit before committing. The package is a Symfony bundle (Twig helper, Symfony console command, Stimulus controller), not a Laravel package. If the target application is Laravel, treat this as an evaluation of a port or a separate Symfony service rather than an install.