README

English | 中文

A comprehensive Symfony bundle for tracking UTM (Urchin Tracking Module) parameters
and conversion events. This bundle provides automatic UTM parameter detection,
session management, and conversion tracking for web applications.

Features
Dependencies
Installation
Quick Start
Configuration
Usage
Advanced Usage
EasyAdmin Integration
Events
Storage Strategies
API Reference
Testing
Contributing
License

Features

Automatic UTM Parameter Detection: Automatically extracts UTM parameters from incoming requests
Session Management: Manages UTM sessions with configurable lifetime and expiration
Conversion Tracking: Track conversion events with UTM attribution
Multiple Storage Strategies: Support for database and session-based storage
EasyAdmin Integration: Pre-built admin controllers for managing UTM data
Flexible Configuration: Support for custom UTM parameters and validation rules
Event-Driven Architecture: Dispatches events for UTM conversions and sessions
Parameter Validation: Built-in validation with XSS protection and length limits
User Attribution: Automatic user identification and anonymous session tracking

Dependencies

PHP 8.1 or higher
Symfony 6.4 or higher
Doctrine ORM 3.0 or higher
EasyAdmin Bundle 4.0 or higher

Installation

Install the bundle via Composer:

composer require tourze/symfony-utm-bundle

Quick Start

1. Enable the Bundle

Add the bundle to your config/bundles.php file:

return [
    // ...
    Tourze\UtmBundle\UtmBundle::class => ['all' => true],
];

2. Configure Database

Run the following commands to set up the database tables:

php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate

3. Basic Usage

The bundle automatically tracks UTM parameters from URLs like:

https://example.com/landing-page?utm_source=google&utm_medium=cpc&utm_campaign=summer_sale

Track conversions in your controllers:

use Tourze\UtmBundle\Service\UtmConversionTracker;

class OrderController extends AbstractController
{
    public function __construct(
        private UtmConversionTracker $conversionTracker
    ) {}

    public function complete(): Response
    {
        // Track order completion conversion
        $this->conversionTracker->track('order_complete', 99.99, [
            'order_id' => 12345,
            'items_count' => 3
        ]);

        return $this->render('order/complete.html.twig');
    }
}

Configuration

Create a configuration file at config/packages/utm.yaml:

utm:
  # Storage strategy: 'database' or 'session'
  storage_strategy: 'database'
  
  # Session configuration
  session:
    lifetime: 3600  # Session lifetime in seconds
    
  # Parameter validation
  validation:
    max_length: 255     # Maximum parameter length
    sanitize: true      # Enable XSS protection
    
  # Additional UTM parameters to track
  additional_parameters:
    - utm_id
    - utm_custom

Usage

Manual UTM Parameter Extraction

use Tourze\UtmBundle\Service\UtmParametersExtractor;
use Symfony\Component\HttpFoundation\Request;

class MyController extends AbstractController
{
    public function __construct(
        private UtmParametersExtractor $extractor
    ) {}

    public function landing(Request $request): Response
    {
        $utmParams = $this->extractor->extract($request);
        
        if ($utmParams->hasAnyParameter()) {
            $source = $utmParams->getSource();
            $medium = $utmParams->getMedium();
            $campaign = $utmParams->getCampaign();
            
            // Use UTM data for analytics
        }

        return $this->render('landing.html.twig');
    }
}

Session Management

use Tourze\UtmBundle\Service\UtmSessionManager;

class AnalyticsController extends AbstractController
{
    public function __construct(
        private UtmSessionManager $sessionManager
    ) {}

    public function dashboard(): Response
    {
        $currentSession = $this->sessionManager->getCurrentSession();
        
        if ($currentSession) {
            $parameters = $currentSession->getParameters();
            $userIdentifier = $currentSession->getUserIdentifier();
            $metadata = $currentSession->getMetadata();
        }

        return $this->render('analytics/dashboard.html.twig');
    }
}

Advanced Usage

Custom Storage Strategy

Implement your own storage strategy:

use Tourze\UtmBundle\Service\Storage\UtmStorageStrategyInterface;
use Tourze\UtmBundle\Entity\UtmSession;
use Tourze\UtmBundle\Dto\UtmParametersDto;

class RedisStorageStrategy implements UtmStorageStrategyInterface
{
    public function store(UtmParametersDto $parameters, string $sessionId): UtmSession
    {
        // Custom Redis implementation
    }

    public function retrieve(string $sessionId): ?UtmSession
    {
        // Custom Redis retrieval
    }
}

Event Listeners

Listen to UTM events:

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Tourze\UtmBundle\Event\UtmConversionEvent;

class UtmAnalyticsSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            UtmConversionEvent::NAME => 'onConversion',
        ];
    }

    public function onConversion(UtmConversionEvent $event): void
    {
        $conversion = $event->getConversion();
        $eventName = $conversion->getEventName();
        $value = $conversion->getValue();
        
        // Send data to analytics platform
    }
}

EasyAdmin Integration

The bundle provides pre-built EasyAdmin controllers for managing UTM data. Add to your dashboard:

use EasyCorp\Bundle\EasyAdminBundle\Config\Dashboard;
use EasyCorp\Bundle\EasyAdminBundle\Config\MenuItem;
use Tourze\UtmBundle\Controller\Admin\UtmParametersCrudController;
use Tourze\UtmBundle\Controller\Admin\UtmSessionCrudController;
use Tourze\UtmBundle\Controller\Admin\UtmConversionCrudController;

class DashboardController extends AbstractDashboardController
{
    public function configureMenuItems(): iterable
    {
        yield MenuItem::section('UTM Analytics');
        yield MenuItem::linkToCrud('UTM Parameters', 'fas fa-link', UtmParameters::class)
            ->setController(UtmParametersCrudController::class);
        yield MenuItem::linkToCrud('UTM Sessions', 'fas fa-users', UtmSession::class)
            ->setController(UtmSessionCrudController::class);
        yield MenuItem::linkToCrud('UTM Conversions', 'fas fa-chart-line', UtmConversion::class)
            ->setController(UtmConversionCrudController::class);
    }
}

Events

The bundle dispatches the following events:

UtmConversionEvent::NAME: Dispatched when a conversion is tracked

Storage Strategies

Database Strategy (Default)

Stores UTM data in database tables using Doctrine ORM.

Session Strategy

Stores UTM data in PHP sessions for simpler setups without persistent storage.

API Reference

UtmConversionTracker

track(string $eventName, float $value = 0.0, array $metadata = []): UtmConversion

UtmParametersExtractor

extract(Request $request): UtmParametersDto

UtmSessionManager

getCurrentSession(): ?UtmSession
createSession(UtmParametersDto $parameters): UtmSession

UtmContextManager

getCurrentParameters(): ?UtmParameters
getCurrentSession(): ?UtmSession

Testing

Run the test suite:

vendor/bin/phpunit packages/symfony-utm-bundle/tests

Run static analysis:

vendor/bin/phpstan analyse packages/symfony-utm-bundle

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

Please ensure your code follows PSR-12 coding standards and includes appropriate tests.

License

This bundle is released under the MIT License. See LICENSE file for details.

tourze / symfony-utm-bundle

Maintainers

Details