Laravel Tagmanager Laravel Package

Getting Started

• Install with Composer: composer require label84/laravel-tagmanager.
• Publish the config if you need to customize templates or defaults: php artisan vendor:publish --provider="Label84\TagManager\TagManagerServiceProvider" --tag=config
• Register your tags once, typically in AppServiceProvider::boot() (or a dedicated TagServiceProvider if you prefer):

  use Label84\TagManager\Facades\TagManager;
  
  public function boot(): void
  {
      TagManager::add('google-analytics', config('services.google.analytics_id'));
      TagManager::add('google-tag-manager', config('services.google.tag_manager_id'));
  }
  

• Render the tags in your layout, splitting head and body snippets:

  <head>
      {!! TagManager::head() !!}
  </head>
  <body>
      {!! TagManager::body() !!}
  </body>
  

• First use case to validate: add a single Google Analytics tag, load a page, and confirm the snippet appears in <head> and the noscript/body portion renders after <body>.

Implementation Patterns

• Config-driven IDs. Keep tag IDs in config/services.php or config/tagmanager.php and pull them from .env. This avoids hardcoding UA-…/GTM-… IDs in service providers and lets you swap per environment (e.g. no analytics in local and testing).
• Environment gating. Wrap TagManager::add() in an environment check:

  if (app()->isProduction()) {
      TagManager::add('google-analytics', $id);
  }
  

• Per-request tags via middleware. If tags depend on the request (e.g. user consent, tenant, locale), add them in a middleware registered after StartSession so session/consent state is available before the layout renders.
• Consent-aware rendering. Use the merge() method to inject additional configuration (e.g. anonymize_ip, consent mode values) into an already-registered tag rather than duplicating add() calls:

  TagManager::add('google-analytics', $id);
  TagManager::merge('google-analytics', ['anonymize_ip' => true]);
  

  Since v1.5.3, merge() correctly accepts arrays, so you can pass nested config structures without wrapping workarounds.
• Multiple tags, one layout. head() and body() aggregate every registered tag. Keep the render calls in a single base layout rather than scattering them across partials to avoid double-loading scripts.
• Testing. In feature tests, it's often simplest to assert against the rendered response (assertSee('GTM-', false)) or temporarily disable registration in your TestCase::setUp() to keep snapshots stable. If the package ships a fake/disable switch in your version, prefer that over asserting on raw snippet output.
• Composable templates. If you need a tag type not shipped by the package, extend the config's tag templates and register a custom key rather than editing package views.

Gotchas and Tips

• Escape output correctly. The snippets are HTML, so use {!! TagManager::head() !!} / {!! TagManager::body() !!}. Using {{ }} will HTML-encode the scripts and silently break tracking.
• Don’t double-register. add() calls in boot() run on every request; if you also call add() in a controller or middleware for the same key you can end up with duplicate or unexpected entries. Pick one place per tag.
• merge() behavior (v1.5.3). Prior to 1.5.3, merge() mishandled array payloads. If you’re pinned to ≤1.5.2 and passing arrays, the merge silently produced incorrect config — upgrade to v1.5.3 or wrap arrays explicitly. This is a patch release with no API changes, so upgrading is low risk.
• Config cache. After publishing/editing config/tagmanager.php, run php artisan config:clear (or config:cache in deploy). Stale cached config is a common cause of “my tag isn’t showing up” in production.
• Environment leakage. Without gating, a staging deploy will happily send hits to a production GA property. Gate by environment or use distinct property IDs per environment.
• Head ordering. Keep the render call as early in <head> as practical; GTM/GA expect the container snippet before other scripts for reliable pageview timing.
• CSP. If you enforce a Content-Security-Policy, remember the rendered snippets require script-src allowances for googletagmanager.com / google-analytics.com and img-src for the GA pixel — otherwise tracking fails silently in the browser console.
• Debugging. If tags are missing, check in this order: config cache, service provider registration, environment gating, and Blade escaping. Inspecting TagManager state isn't directly supported, so log the resolved ID inside the provider when narrowing issues.