Piwik Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation (if still needed for legacy projects):

   composer require core23/piwik-bundle
   

   Note: Per the README, this is deprecated—use core23/MatomoBundle instead.

2. Configuration: Add to config/packages/core23_piwik.yaml (or equivalent):

   core23_piwik:
       tracker_url: 'https://your-matomo-instance.com/piwik.php'
       site_id: 1
       debug: '%kernel.debug%'
   

3. First Use Case: Inject the PiwikBlockService into a controller or service:

   use Core23\PiwikBundle\Block\PiwikBlockService;
   
   public function __construct(private PiwikBlockService $piwik)
   {
   }
   
   public function index()
   {
       return $this->piwik->getTrackingCode();
   }
   

   Render the output in a Twig template:

   {{ app.service('core23_piwik.block').getTrackingCode() }}
   

Implementation Patterns

Common Workflows

1. Dynamic Tracking Code Injection: Use the block service to inject Matomo tracking code into layouts or specific pages:

   // In a base controller or event subscriber
   $trackingCode = $this->piwik->getTrackingCode();
   $view->add('piwik_tracking', $trackingCode);
   

2. Conditional Tracking: Disable tracking in non-production environments:

   # config/packages/core23_piwik.yaml
   core23_piwik:
       enabled: '%env(bool:PIWIK_ENABLED)%'
   

3. Sonata Admin Integration: Extend the SonataBlockBundle to include Piwik tracking:

   # config/packages/sonata_block.yaml
   sonata_block:
       blocks:
           piwik:
               type: core23_piwik.block
               contexts: [admin]
   

4. Event-Based Tracking: Trigger tracking via events (e.g., KernelEvents::RESPONSE):

   public function onKernelResponse(ResponseEvent $event)
   {
       if ($this->piwik->isEnabled()) {
           $event->getResponse()->headers->add(
               'X-Piwik-Tracking',
               $this->piwik->getTrackingCode()
           );
       }
   }
   

Integration Tips

• Twig Integration: Register the block service as a Twig extension for global access:

  // src/Twig/AppExtension.php
  public function getFunctions()
  {
      return [
          new \Twig\TwigFunction('piwik_tracking', [$this->piwik, 'getTrackingCode']),
      ];
  }
  

  Usage in Twig:

  {{ piwik_tracking() }}
  

• Caching: Cache the tracking code if your Matomo instance is static:

  $trackingCode = $this->piwik->getTrackingCode();
  Cache::remember('piwik_tracking_code', 3600, fn() => $trackingCode);
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • The bundle is unmaintained (last release: 2017). Use core23/MatomoBundle for new projects.
   • If stuck with this bundle, fork and update dependencies (e.g., sonata-project/admin-bundle).

2. Configuration Overrides:

   • Ensure tracker_url and site_id are correctly set. Invalid values may break tracking silently.
   • Debug mode (debug: true) logs errors but may expose sensitive data in production.

3. Sonata Admin Conflicts:

   • If using Sonata Admin, ensure the block is registered after Sonata’s blocks are loaded:

     sonata_block:
         blocks:
             piwik:
                 type: core23_piwik.block
                 contexts: [admin]
                 position: 500  # High priority to avoid overlap
     

4. JavaScript Conflicts:

   • The tracking code may conflict with other JS libraries. Use defer or wrap in DOMContentLoaded:

     <script defer>{{ piwik_tracking() }}</script>
     

Debugging

• Check Tracking Code Output: Inspect the rendered HTML to verify the tracking snippet is present:

  {{ dump(app.service('core23_piwik.block').getTrackingCode()) }}
  

  Expected output: A <script> tag with piwik.js or similar.

• Log Errors: Enable debug mode in config to surface issues:

  core23_piwik:
      debug: true
  

  Check var/log/dev.log for errors like:

  [PiwikBlockService] Failed to fetch tracker URL: InvalidArgumentException
  

Extension Points

1. Custom Tracking Parameters: Extend the service to add custom variables:

   // src/Service/CustomPiwikService.php
   class CustomPiwikService extends PiwikBlockService
   {
       public function getTrackingCode()
       {
           $code = parent::getTrackingCode();
           return str_replace(
               '</script>',
               '_paq.push(["setCustomVar", 1, "UserType", "Premium", "visit"]);</script>',
               $code
           );
       }
   }
   

   Override the service in config/services.yaml:

   services:
       Core23\PiwikBundle\Block\PiwikBlockService: '@app.custom_piwik_service'
   

2. Async Loading: Modify the tracking code to load asynchronously:

   public function getTrackingCode()
   {
       $code = parent::getTrackingCode();
       return str_replace(
           '<script>',
           '<script async>',
           $code
       );
   }
   

3. Environment-Specific URLs: Use Symfony’s parameter bag to switch URLs by environment:

   core23_piwik:
       tracker_url: '%env(PIWIK_TRACKER_URL_%kernel.environment%)%'
   

   Define in .env:

   PIWIK_TRACKER_URL_dev=https://dev-matomo.example.com
   PIWIK_TRACKER_URL_prod=https://analytics.example.com