Analytics Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add to composer.json:

   composer require beloop/analytics-bundle
   

   Enable in config/bundles.php:

   Beloop\AnalyticsBundle\BeloopAnalyticsBundle::class => ['all' => true],
   

2. First Use Case Track a user event via the AnalyticsService:

   use Beloop\AnalyticsBundle\Analytics\AnalyticsService;
   
   class SomeController extends AbstractController
   {
       public function trackEvent(AnalyticsService $analytics): Response
       {
           $analytics->track('user_login', ['user_id' => 123]);
           return new Response('Event tracked');
       }
   }
   

3. Configuration Check config/packages/beloop_analytics.yaml for default providers (e.g., GoogleAnalytics, Mixpanel). Override as needed:

   beloop_analytics:
       providers:
           google: ~ # Disabled by default
           mixpanel: ~ # Disabled by default
   

Implementation Patterns

Core Workflows

1. Event Tracking

   • Basic Tracking: Use AnalyticsService::track() for standard events.

     $analytics->track('course_completed', ['course_id' => 42, 'duration' => 3600]);
     

   • User Context: Attach user metadata via middleware or service binding:

     $analytics->setUserContext(['id' => $user->id, 'email' => $user->email]);
     

2. Provider Integration

   • Enable Providers: Activate in config (e.g., google: true).
   • Custom Providers: Implement AnalyticsProviderInterface:

     class CustomProvider implements AnalyticsProviderInterface
     {
         public function track(string $event, array $properties): void
         {
             // Custom logic (e.g., API call)
         }
     }
     

     Register via dependency injection:

     services:
         Beloop\AnalyticsBundle\Analytics\AnalyticsService:
             arguments:
                 $providers: ['@custom_provider']
     

3. Batch Processing

   • Use AnalyticsService::flush() to send queued events (useful for offline scenarios).

Integration Tips

• Symfony Events: Listen to kernel events (e.g., kernel.request) to auto-track routes:

  $analytics->track('page_view', ['route' => $request->get('_route')]);
  

• Twig Integration: Pass analytics data to templates:

  {{ dump(app('analytics').userContext) }}
  

• Testing: Mock AnalyticsService in tests:

  $this->mock(AnalyticsService::class)->shouldReceive('track')->once();
  

Gotchas and Tips

Pitfalls

1. Archived Package

   • No active maintenance; use at your own risk. Fork if critical for your project.
   • Mitigation: Cache the bundle locally or set up a private Packagist repo.

2. Provider Configuration

   • Providers (e.g., google) are disabled by default. Explicitly enable in config.
   • Debugging: Check var/log/dev.log for provider errors (e.g., API key issues).

3. Event Naming

   • Avoid reserved words (e.g., user, page) to prevent conflicts with provider schemas.

4. Performance

   • Heavy event tracking can impact response times. Use batching (flush()) for bulk operations.

Debugging

• Enable Logging: Set BeloopAnalyticsBundle to dev mode in config/packages/dev/beloop_analytics.yaml:

  beloop_analytics:
      debug: true
  

• Provider-Specific Errors: Check provider docs (e.g., Google Analytics API limits).

Extension Points

1. Custom Event Transformers Override AnalyticsService to modify events before sending:

   class CustomAnalyticsService extends AnalyticsService
   {
       protected function transformEvent(string $event, array $properties): array
       {
           $properties['app_version'] = '1.0.0';
           return parent::transformEvent($event, $properties);
       }
   }
   

2. Async Tracking Use Symfony Messenger to decouple tracking:

   $message = new TrackEvent('user_signup', ['user_id' => 123]);
   $this->messageBus->dispatch($message);
   

   (Requires custom handler implementation.)

3. Environment-Specific Providers Dynamically enable providers based on environment:

   beloop_analytics:
       providers:
           google: '%env(bool:GOOGLE_ANALYTICS_ENABLED)%'