Matomo Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Laravel Compatibility: The package is a Symfony Bundle, not a Laravel package. While Laravel and Symfony share some PHP/Composer dependencies, this bundle is not natively compatible with Laravel’s architecture (e.g., no AppKernel.php, reliance on Symfony’s dependency injection container, and Twig integration). A Laravel TPM would need to either:

  • Abandon the bundle in favor of a Laravel-native solution (e.g., manually embedding Matomo JS or using a Laravel-compatible package like spatie/laravel-analytics).
  • Adapt the bundle via a Symfony bridge (e.g., symfony/ux-live-component or a custom wrapper) or rewrite core functionality (e.g., Twig functions as Blade directives).

• Core Functionality Alignment:

  • The bundle’s primary value (dynamic Matomo tracking code injection) is achievable in Laravel via:
    • Blade directives (@matomo).
    • Service providers to generate tracking scripts.
    • Middleware for environment-based toggling (dev/prod).
  • No unique Laravel advantage is gained; the bundle adds no architectural benefits over manual implementation.

Integration Feasibility

• Low Feasibility for Laravel:

  • Symfony-Specific Dependencies: Relies on Symfony’s ContainerInterface, Twig, and Bundle system. Laravel’s ServiceProvider/Facade pattern cannot directly consume this.
  • Configuration Format: Uses Symfony’s config.yml; Laravel prefers config/matomo.php or environment variables.
  • Twig Integration: Laravel uses Blade, requiring translation of Twig functions (e.g., {{ piwik_code() }} → @matomo).

• Workarounds:

  • Option 1: Manual Implementation (Recommended):
    • Add Matomo JS to resources/views/layouts/app.blade.php via a Blade directive.
    • Use Laravel’s config('matomo.enabled') to toggle tracking.
    • Example:

      @if(config('matomo.enabled'))
          <script>var _paq = window._paq = window._paq || []; ... </script>
      @endif
      

  • Option 2: Symfony Bridge (High Effort):
    • Install Symfony’s HttpKernel in Laravel (overkill for tracking).
    • Create a custom MatomoServiceProvider to replicate the bundle’s logic.

Technical Risk

• High Risk of Misalignment:
  • Bundle Assumptions: Assumes Symfony’s event system, Twig auto-escaping, and kernel bootstrapping. Laravel’s ecosystem (e.g., Illuminate\Foundation\Application) will reject these dependencies.
  • Maintenance Overhead: Any adaptation would require forking the bundle or building a parallel Laravel package, duplicating effort.
• Dependency Risks:
  • The bundle’s last update is 2017 (per GitHub activity). Matomo’s API may have changed, risking broken tracking code.
  • No Laravel-specific testing or community support.

Key Questions for the TPM

1. Why Symfony?
   • Is there a strategic need to unify with Symfony projects? If not, prioritize Laravel-native solutions.
2. Matomo API Version Support
   • Does the bundle’s hardcoded tracking script align with the current Matomo API? Test against Matomo’s latest JS snippet.
3. Alternatives Assessment
   • Compare effort vs. value of:
     • Manual Blade implementation (low effort, full control).
     • spatie/laravel-analytics (if supporting multiple analytics tools).
     • Commercial Laravel packages (e.g., Laravel Analytics).
4. Dev/Prod Toggle
   • How will the team enforce tracking disabled in APP_ENV=local? Middleware or config-based?
5. Performance Impact
   • Will the tracking script block page rendering? Consider async loading or lazy-loading the script.

Integration Approach

Stack Fit

• Laravel Incompatibility:

  • The bundle is not a drop-in solution for Laravel. Key mismatches:
    • Dependency Injection: Symfony’s ContainerBuilder vs. Laravel’s Illuminate\Container.
    • Templating: Twig vs. Blade (syntax, auto-escaping, directives).
    • Configuration: YAML vs. PHP arrays/environment variables.
  • Mitigation: Treat as a reference implementation for manual Laravel code, not a reusable component.

• Compatible Alternatives:

  Feature	webfactory/piwik-bundle	Manual Laravel	spatie/laravel-analytics
  Matomo Tracking	✅ (Twig)	✅ (Blade)	✅ (Supports Matomo)
  Dev/Prod Toggle	✅ (Config)	✅ (Config)	✅ (Config)
  Async Loading	❌	✅	✅
  Multi-Tool Support	❌	❌	✅ (Google, Mixpanel)

Migration Path

1. Assessment Phase (1 day):

   • Audit current Matomo integration (if any).
   • Test the bundle’s tracking script against Matomo’s latest API.
   • Document deviations from Laravel’s stack (e.g., Twig → Blade).

2. Implementation Path A: Manual Laravel (Recommended):

   • Step 1: Add config (config/matomo.php):

     return [
         'enabled' => env('MATOMO_ENABLED', false),
         'site_id' => env('MATOMO_SITE_ID'),
         'url' => env('MATOMO_URL'),
     ];
     

   • Step 2: Create a Blade directive (app/Providers/AppServiceProvider.php):

     Blade::directive('matomo', function () {
         if (config('matomo.enabled')) {
             return <<<EOD
             <script>
                 var _paq = window._paq = window._paq || [];
                 _paq.push(['trackPageView']);
                 _paq.push(['enableLinkTracking']);
                 (function() {
                     var u="//".concat(window.location.hostname).concat(config('matomo.url'));
                     _paq.push(['setTrackerUrl', u+'matomo.php']);
                     _paq.push(['setSiteId', config('matomo.site_id')]);
                     var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
                     g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
                 })();
             </script>
             EOD;
         }
     });
     

   • Step 3: Use in layout:

     @matomo
     

   • Step 4: Add middleware to disable in local env (optional):

     public function handle($request, Closure $next) {
         config(['matomo.enabled' => app()->environment('local') ? false : true]);
         return $next($request);
     }
     

3. Implementation Path B: Symfony Bridge (Not Recommended):

   • Install Symfony’s HttpKernel and Twig as Laravel dependencies (bloat).
   • Create a custom MatomoBundle that wraps the original bundle’s logic.
   • Risk: High coupling; future Laravel updates may break compatibility.

Compatibility

• Environment Variables:
  • The bundle uses hardcoded config.yml values. Laravel prefers .env variables (e.g., MATOMO_SITE_ID=1).
  • Fix: Modify the bundle’s DependencyInjection/Configuration.php to support environment variables (if adapting).
• Twig to Blade:
  • Replace {{ piwik_code() }} with @matomo and ensure Blade’s escaping rules match Twig’s.
• Matomo API Changes:
  • The bundle’s JS snippet may be outdated. Validate against Matomo’s current tracking code.

Sequencing

1. Phase 1: Spike (2 days)

   • Implement manual Blade solution.
   • Test in staging with real Matomo instance.
   • Compare performance (e.g., page load time) vs. bundle’s output.

2. Phase 2: Integration (3 days)

   • Add middleware/config toggles.
   • Document edge cases (e.g., tracking on SPAs, single-page apps).

3. Phase 3: Deprecation (Optional)

   • If using the bundle indirectly (e.g., via Symfony microservice), plan for eventual migration to Laravel-native code.

Operational Impact

Maintenance

• Manual Implementation:
  • Pros:
    • Full control over tracking code (easy to update for Matomo API changes).
    • No external dependencies beyond Matomo’s JS.
    • Aligns