Matomo Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony 8 Mandate (PR #909): Confirmed as a hard requirement with no rollback path. No new features introduced; this remains a critical blocker for projects on Symfony <8.0. Legacy projects must either:
  • Upgrade Symfony to 8.x (recommended but risky).
  • Fork the bundle (last resort).
• SonataAdmin Integration: Unchanged. Tight coupling to SonataAdmin’s block system persists, limiting utility for non-Sonata projects. No updates to block compatibility or new integration patterns.
• Matomo API Abstraction: No changes to Matomo version support. High risk for users on Matomo 5.x due to:
  • Lack of explicit validation or documentation for Matomo 5.x compatibility.
  • Potential API deprecations in newer Matomo versions (e.g., v4.x → v5.x).
• Event-Driven Hooks (PR #908):
  • Updated to PHPUnit 13 with no functional changes to the event system itself.
  • Key risks:
    • Deprecated assertion methods (e.g., assertInternalType → assertIs*) may break existing tests.
    • Symfony 8’s event system updates (e.g., KernelEvents constants) could introduce edge cases if leveraged in custom listeners.
• Frontend Dependencies (PR #911):
  • Updated globals@16 and symfony/phpunit-bridge@8 introduce no breaking changes to core functionality but may impact:
    • JavaScript-based Matomo tracking (e.g., matomo.js compatibility) due to dependency updates.
    • SonataAdmin block rendering if relying on custom frontend assets or asset pipelines (e.g., Webpack Encore, Vite).
  • No new frontend features added; purely dependency updates.
• New Dependencies:
  • symfony/phpunit-bridge@8: May require CI/CD adjustments (e.g., test suite configuration) but no core functionality impact.
  • globals@16: Unlikely to affect core logic but could alter environment variable handling in CI/CD pipelines (e.g., .env parsing).

Integration Feasibility

• Symfony 8 Dependency: Critical blocking factor for projects on Symfony <8.0. Workarounds remain:
  • Downgrade: Impossible (hard dependency).
  • Upgrade Symfony: Recommended but requires extensive testing (e.g., DI system, event listeners, HTTP client).
  • Fork the Bundle: Only viable for legacy projects unwilling to upgrade.
• Configuration: No structural changes to nucleos_matomo.yaml, but Symfony 8’s autoconfigure system may still require adjustments:
  • Explicit service definitions for custom Matomo clients or event listeners.
  • Environment variable resolution (e.g., %env(MATOMO_TOKEN)% vs. Symfony 8’s %env(resolve:MATOMO_TOKEN)%).
• Sonata Block System: Unchanged, but Symfony 8’s BlockService updates may necessitate:
  • Reconfiguration of custom blocks (e.g., service tags or container awareness).
  • Validation of block rendering logic for Symfony 8’s updated event system.
• Frontend Updates (PR #911):
  • No breaking changes to core tracking logic, but potential compatibility issues for:
    • Hybrid tracking setups (HTTP API + JavaScript).
    • Custom SonataAdmin blocks with embedded JS or asset dependencies.
  • No new frontend APIs or features introduced.

Technical Risk

• Symfony 8 Mandate: High risk for legacy projects due to:
  • Dependency Injection: Symfony 8’s autoconfigure: true defaults may break custom services or third-party integrations.
  • Event System: Updated KernelEvents or dispatcher behavior (e.g., new constants or listener signatures).
  • HTTP Client: Matomo API calls may fail if relying on deprecated HttpClient methods (e.g., v6 → v8).
• PHPUnit 13 (PR #908): Medium risk for test suites using:
  • Deprecated assertion methods (e.g., assertEquals → assertSame).
  • Legacy TestCase inheritance patterns or custom test bootstrapping.
• Frontend Dependencies (PR #911): Low-to-medium risk for:
  • JavaScript tracking compatibility (e.g., matomo.js version conflicts).
  • SonataAdmin blocks with custom frontend logic or asset pipelines.
• Matomo Version Lock: Unchanged high risk—no release notes suggest Matomo 5.x support or validation.
• New Dependencies:
  • symfony/phpunit-bridge@8: May introduce test suite compatibility issues (e.g., TestCase bootstrapping or assertion changes).
  • globals@16: Unlikely to impact core functionality but could affect CI/CD (e.g., environment variable resolution or .env parsing).

Key Questions

1. What is the current Symfony version?
   • If <8.0, integration is blocked without upgrading or forking.
2. Are there plans to upgrade Symfony to 8+?
   • If no, this release cannot be adopted without workarounds.
3. Does the project use JavaScript-based Matomo tracking (e.g., matomo.js)?
   • Frontend dependency updates (PR #911) may require validation for hybrid setups.
4. Is Matomo 5.x in use?
   • No release notes suggest support; manual compatibility testing required.
5. How are event listeners implemented?
   • PHPUnit 13 updates may break existing tests (e.g., assertion methods or TestCase inheritance).
6. Are there custom Sonata blocks or event subscribers?
   • Symfony 8’s BlockService and event system changes may require updates.
7. What PHPUnit version is used in CI?
   • PHPUnit 13 may fail legacy test suites (e.g., self::bootKernel() or deprecated assertions).
8. Are there custom frontend integrations (e.g., Webpack Encore, Vite)?
   • Updated dependencies (PR #911) may require validation for asset pipelines.
9. How is the Matomo API client configured?
   • Symfony 8’s HttpClient changes may affect API call reliability or error handling.
10. Are there any custom environment variables or config overrides?
    • globals@16 may alter how environment variables are processed in Symfony 8’s context.
11. Does the project use Symfony’s HttpClient for Matomo API calls?
    • Symfony 8’s HttpClient (v8+) may introduce breaking changes (e.g., middleware handling, response parsing).
12. Are there any custom EventSubscriber classes for Matomo events?
    • Symfony 8’s event system updates (e.g., KernelEvents constants) may require refactoring.

Integration Approach

Stack Fit

• Symfony 8: Now required. Projects must align with:
  • Dependency Injection: Symfony 8’s autoconfigure defaults (e.g., autowire: true, public_methods: false).
  • HTTP Client: Updated HttpClientInterface (v8+) for Matomo API calls (e.g., middleware, response handling).
  • Event System: New KernelEvents constants or dispatcher behavior (e.g., TERMINATE event changes).
  • PHPUnit: Updated to v13 for test suites (assertion methods, TestCase bootstrapping).
• PHP 8.0+: Likely still required; no changes noted.
• Matomo API: Unchanged; no new features in this release.
• SonataAdmin: Critical dependency remains. No new block types or integrations.
• Frontend: Updated dependencies (PR #911) may require testing for:
  • JavaScript tracking compatibility (e.g., matomo.js version conflicts).
  • SonataAdmin block rendering (custom JS components or asset pipelines like Webpack Encore or Vite).

Migration Path

1. Pre-Integration:
   • Symfony Version Check:

     composer show symfony/http-kernel | grep version
     

   • Upgrade Symfony to 8.x (if needed) in a staging environment:

     composer require symfony/*:^8.0 --update-with-dependencies
     

   • Audit event listeners, Sonata blocks, and frontend integrations for compatibility with:
     • Symfony 8’s DI system (e.g., autowire, bind).
     • PHPUnit 13 assertion changes.
     • Symfony 8’s HttpClient (e.g., middleware, response parsing).
2. Bundle Installation:

   composer require nucleos/matomo-bundle:^4.4
   

   • Update config/packages/nucleos_matomo.yaml for Symfony 8’s config system:

     # config/packages/nucleos_matomo.yaml
     nucleos_matomo: