Visitor Tracker Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require beast/visitor-tracker-bundle
   

   Add to config/bundles.php if not auto-discovered:

   return [
       // ...
       Beast\VisitorTrackerBundle\VisitorTrackerBundle::class => ['all' => true],
   ];
   

2. Enable Tracking Configure in config/packages/visitor_tracker.yaml:

   visitor_tracker:
       enabled: true
       anonymize_ip: true  # Recommended for GDPR compliance
       geo_lookup: false   # Enable if you need country/city data
   

3. First Use Case: Debug a Slow Request Trigger a request, then run:

   php bin/console visitor:tracker:list --limit=5
   

   Output will show request metadata, duration, and memory usage.

Implementation Patterns

Core Workflows

1. Development Debugging

   • Pattern: Use visitor:tracker:show <id> to inspect a specific request.
   • Example:

     php bin/console visitor:tracker:show 12345
     

     Reveals IP, user agent, route, and performance metrics.

2. CLI-Driven Analytics

   • Pattern: Aggregate data for insights:

     # Top routes by traffic
     php bin/console visitor:tracker:routes --limit=10
     
     # Detect 5xx errors
     php bin/console visitor:tracker:errors --status=5xx
     
     # UTM campaign analysis
     php bin/console visitor:tracker:utm --campaign=summer-sale
     

3. Integration with Symfony Events

   • Pattern: Extend tracking with custom data via event listeners.
   • Example: Log a user’s subscription status:

     // src/EventListener/CustomTrackerListener.php
     namespace App\EventListener;
     
     use Beast\VisitorTrackerBundle\Event\TrackVisitorEvent;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     
     class CustomTrackerListener implements EventSubscriberInterface
     {
         public static function getSubscribedEvents()
         {
             return [
                 TrackVisitorEvent::NAME => 'onTrackVisitor',
             ];
         }
     
         public function onTrackVisitor(TrackVisitorEvent $event)
         {
             $event->getVisitor()->setMetadata('subscription', 'premium');
         }
     }
     

4. GeoIP Enrichment (Optional)

   • Pattern: Enable geo lookup in config and use in CLI:

     visitor_tracker:
         geo_lookup: true
         geo_service: 'maxmind'  # or 'ip-api'
     

     Then filter by country:

     php bin/console visitor:tracker:list --country=US
     

Gotchas and Tips

Pitfalls

1. Performance Overhead

   • Issue: Tracking adds ~5–10ms per request. Disable in production if unused:

     visitor_tracker:
         enabled: false  # Set to false for production
     

   • Workaround: Use visitor:tracker:purge to clear old logs periodically.

2. GeoIP Service Dependencies

   • Issue: Geo lookup requires external APIs (e.g., MaxMind DB). If misconfigured, CLI commands may fail.
   • Fix: Install the correct service (e.g., composer require geoip2/geoip2) and update config:

     visitor_tracker:
         geo_service: 'maxmind'
         geo_database: '%kernel.project_dir%/var/GeoLite2-City.mmdb'
     

3. Anonymization Conflicts

   • Issue: If anonymize_ip: false, stored IPs may violate GDPR/privacy laws.
   • Tip: Always enable anonymization in production:

     visitor_tracker:
         anonymize_ip: true
     

4. Log Rotation

   • Issue: Log files grow unbounded. CLI commands may slow with large datasets.
   • Solution: Implement a cron job to purge old logs:

     php bin/console visitor:tracker:purge --older-than=30days
     

Debugging Tips

1. Verify Tracking Check if the bundle is active:

   php bin/console debug:config visitor_tracker
   

   Look for enabled: true.

2. Inspect Visitor Data Use visitor:tracker:show to debug a specific request. Example output:

   ID: 12345
   IP: 192.0.2.1 (anonymized)
   User Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
   Route: app.homepage
   Duration: 123ms
   Memory: 2.1MB
   Metadata: {"subscription": "premium"}
   

3. Custom Metadata Serialization

   • Issue: Complex metadata (e.g., arrays) may not serialize correctly.
   • Fix: Implement a custom serializer for Visitor class or use JSON strings:

     $event->getVisitor()->setMetadata('tags', json_encode(['newsletter', 'vip']));
     

Extension Points

1. Add Custom Fields Extend the Visitor entity (override in a custom bundle):

   // src/Entity/CustomVisitor.php
   namespace App\Entity;
   
   use Beast\VisitorTrackerBundle\Entity\Visitor;
   
   class CustomVisitor extends Visitor
   {
       private $customField;
   
       // Add getters/setters and update mapping in config.
   }
   

2. Override CLI Commands Replace or extend commands by creating a custom command that calls the original:

   // src/Command/CustomTrackerCommand.php
   use Beast\VisitorTrackerBundle\Command\ListTrackerCommand;
   
   class CustomTrackerCommand extends ListTrackerCommand
   {
       protected function configure()
       {
           $this->setName('app:visitor:custom-list');
           parent::configure();
       }
   }
   

3. Hook into Tracker Events Subscribe to TrackVisitorEvent for real-time modifications:

   // src/EventSubscriber/TrackerSubscriber.php
   use Beast\VisitorTrackerBundle\Event\TrackVisitorEvent;
   
   class TrackerSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [TrackVisitorEvent::NAME => 'onTrack'];
       }
   
       public function onTrack(TrackVisitorEvent $event)
       {
           if ($event->getVisitor()->isBot()) {
               $event->setMetadata('bot_type', 'known');
           }
       }
   }
   

4. Change Log Storage Override the default logger to use a database or external service:

   visitor_tracker:
       logger: 'monolog.logger.visitor'  # Custom logger name
   

   Then configure the logger in monolog.yaml.