Matomo Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require aldaflux/matomo-bundle
   

   Ensure Aldaflux\MatomoBundle\AldafluxMatomoBundle is registered in config/bundles.php.

2. Configure the Bundle Add the required settings to config/packages/aldaflux_matomo.yaml:

   aldaflux_matomo:
       default:
           site: 'https://matomo.mysite.org/'  # Your Matomo instance URL
           token_auth: 'YOUR_MATOMO_TOKEN'     # Auth token from Matomo (User > Login > API)
   

3. First Use Case: Track a Page View Inject the MatomoTracker service in a controller or service:

   use Aldaflux\MatomoBundle\Service\MatomoTracker;
   
   public function index(MatomoTracker $tracker)
   {
       $tracker->trackPageView('/home'); // Track a page view
   }
   

Implementation Patterns

Core Workflows

1. Tracking Events Use MatomoTracker to log custom events (e.g., button clicks, form submissions):

   $tracker->trackEvent('Category', 'Action', 'Name', 1); // Value is optional
   

2. Tracking E-Commerce For e-commerce tracking, use the trackEcommerce method:

   $tracker->trackEcommerce(
       'purchase',
       [
           ['sku' => '123', 'name' => 'Product A', 'price' => 19.99, 'quantity' => 2],
       ]
   );
   

3. Dynamic Configuration Override the default Matomo site/token per environment or route:

   # config/packages/aldaflux_matomo.yaml
   aldaflux_matomo:
       sites:
           analytics:
               site: 'https://analytics.mysite.org/'
               token_auth: 'TOKEN_A'
           staging:
               site: 'https://staging.matomo.org/'
               token_auth: 'TOKEN_B'
   

   Then inject the MatomoTracker with a specific site:

   $tracker = $container->get('aldaflux_matomo.tracker.analytics');
   

4. Middleware for Automatic Tracking Create a middleware to track page views automatically:

   use Aldaflux\MatomoBundle\Service\MatomoTracker;
   use Symfony\Component\HttpFoundation\Request;
   use Symfony\Component\HttpFoundation\Response;
   
   public function handle(Request $request, Response $response, callable $next): Response
   {
       $tracker = $this->container->get(MatomoTracker::class);
       $tracker->trackPageView($request->getUri());
   
       return $next($request);
   }
   

Gotchas and Tips

Pitfalls

1. Token Security

   • Never commit token_auth to version control. Use environment variables or Symfony’s %env%:

     token_auth: '%env(MATOMO_TOKEN)%'
     

   • Restrict Matomo API tokens to read-only or specific actions (e.g., View access only).

2. Rate Limiting

   • Matomo may throttle requests if too many are sent in a short time. Implement a delay or queue (e.g., Symfony Messenger) for high-traffic actions.
   • Example: Use sleep(1) after bulk tracking in tests/dev.

3. Asynchronous Tracking

   • Synchronous tracking can slow down responses. For production, consider:
     • Offloading tracking to a queue (e.g., symfony/messenger).
     • Using Matomo’s asynchronous tracking API (if supported by the bundle).

4. Dependency Conflicts

   • The bundle requires symfony/ux-chartjs (unrelated to Matomo). Ensure your project doesn’t conflict with its dependencies (e.g., Chart.js versions).

Debugging

1. Enable Debug Logging Add to config/packages/dev/aldaflux_matomo.yaml:

   aldaflux_matomo:
       debug: true
   

   Logs will appear in var/log/dev.log.

2. Validate Token/API Access If tracking fails, verify:

   • The token has the correct permissions in Matomo (User > Login > API).
   • The Matomo site URL is correct (e.g., https://matomo.mysite.org/ vs. https://matomo.mysite.org/matomo).

3. HTTP Errors Check the bundle’s MatomoClient for HTTP errors (e.g., 403 Forbidden). Wrap calls in a try-catch:

   try {
       $tracker->trackPageView('/page');
   } catch (\Exception $e) {
       // Log or handle gracefully
   }
   

Extension Points

1. Custom Tracker Services Extend the MatomoTracker to add domain-specific methods:

   use Aldaflux\MatomoBundle\Service\MatomoTracker;
   
   class CustomMatomoTracker extends MatomoTracker
   {
       public function trackUserSignup(string $email): void
       {
           $this->trackEvent('User', 'Signup', $email);
       }
   }
   

   Register it as a service in config/services.yaml:

   services:
       App\Service\CustomMatomoTracker:
           arguments:
               $client: '@aldaflux_matomo.client.default'
   

2. Event Listeners Trigger tracking on Symfony events (e.g., KernelExceptionEvent for errors):

   use Aldaflux\MatomoBundle\Service\MatomoTracker;
   use Symfony\Component\HttpKernel\Event\ExceptionEvent;
   
   public function onKernelException(ExceptionEvent $event, MatomoTracker $tracker)
   {
       $tracker->trackEvent('Error', 'Exception', $event->getThrowable()->getMessage());
   }
   

3. Testing Mock the MatomoTracker in tests to avoid real API calls:

   $this->mockBuilder()
        ->getContainer()
        ->andReturnSelf()
        ->get('aldaflux_matomo.tracker.default')
        ->andReturn($this->createMock(MatomoTracker::class));