The Snowplow PHP Tracker is a library for sending analytics events to Snowplow collectors. It provides a robust event tracking system with multiple emitter strategies, configurable payloads, and comprehensive event types. The tracker follows an object-oriented architecture with clear separation between event construction, payload management, and event transmission.
# Install dependencies
docker-compose run --rm snowplow composer.phar install
# Run test suite
docker-compose run --rm snowplow script/tests.sh
# Run specific PHPUnit tests
php vendor/bin/phpunit
# Run tests with coverage
php vendor/bin/phpunit --coverage-clover=build/logs/clover.xml
The tracker uses a layered architecture with three core components:
- Tracker: Main interface for tracking events, manages Subject and Emitters
- Subject: Contains user/session information attached to events
- Emitters: Responsible for sending events to collectors with different strategies
Tracker
: Event tracking orchestration and APIPayload
: Event data structure and encodingSubject
: User context and session informationEmitter
: Base class for event transmission strategiesConstants
: Configuration constants and defaults
// ✅ Each class has single responsibility
$subject = new Subject();
$emitter = new SyncEmitter($uri);
$tracker = new Tracker($emitter, $subject);
// ✅ Different emitter strategies
new SyncEmitter($uri); // Synchronous sending
new CurlEmitter($uri); // Async with curl
new SocketEmitter($uri); // Socket-based
// ✅ Events built through Payload objects
$payload = new Payload($timestamp);
$payload->add("e", "pv");
- Core Classes:
Tracker.php
, Subject.php
, Payload.php
, Emitter.php
- Configuration:
Constants.php
- Central configuration
- Purpose: Main tracker functionality
- Implementations: Various emitter strategies (Curl, Socket, Sync, File)
- Retry Management:
RetryRequestManager.php
- Purpose: Handle event transmission to collectors
- Unit Tests:
ClassInitTests/
- Class initialization tests
- Emitter Tests:
EmitterTests/
- Emitter-specific tests
- Integration:
IntegrationTest.php
- End-to-end testing
// ✅ Correct namespace usage
namespace Snowplow\Tracker;
use Snowplow\Tracker\Emitters\CurlEmitter;
// ✅ External dependencies first
use Ramsey\Uuid\Uuid;
use ErrorException;
// Then internal dependencies
use Snowplow\Tracker\Emitter;
// ✅ Track page view
$tracker->trackPageView($page_url, $page_title);
// ✅ Track structured event
$tracker->trackStructEvent($category, $action, $label);
// ✅ Configure emitter with buffer
$emitter = new CurlEmitter(
$uri,
"https", // protocol
"POST", // type
50 // buffer_size
);
// ✅ Set user context
$subject = new Subject();
$subject->setUserId("user123");
$subject->setPlatform("web");
// ✅ Payload with base64 encoding
$payload->addJson($data, true, "ue_px", "ue_pr");
// ✅ Add standard fields
$payload->add("e", "pv"); // Event type
$payload->add("url", $url); // Page URL
// ✅ Structured event fields
array(
"e" => "se", // Event type
"se_ca" => $cat, // Category
"se_ac" => $action // Action
)
// ❌ Not flushing buffer
$tracker->trackPageView($url);
// ✅ Force flush when needed
$tracker->flushEmitters();
// ❌ Wrong timestamp format
$tracker->trackPageView($url, null, null, time());
// ✅ Use milliseconds
$tracker->trackPageView($url, null, null, time() * 1000);
// ❌ Raw context array
$context = ["user" => "123"];
// ✅ Properly structured context
$context = [
["schema" => "iglu:...", "data" => ["user" => "123"]]
];
// ❌ Single emitter as array element
$tracker = new Tracker([$emitter], $subject);
// ✅ Single emitter or array
$tracker = new Tracker($emitter, $subject);
// Or multiple: new Tracker([$e1, $e2], $subject);
snowplow-php-tracker/
├── src/
│ ├── Constants.php # Configuration constants
│ ├── Tracker.php # Main tracker class
│ ├── Subject.php # User context
│ ├── Payload.php # Event payload
│ ├── Emitter.php # Base emitter
│ └── Emitters/
│ ├── CurlEmitter.php
│ ├── SyncEmitter.php
│ ├── SocketEmitter.php
│ └── FileEmitter.php
├── tests/
│ ├── bootstrap.php
│ ├── ClassInitTests/
│ ├── EmitterTests/
│ └── IntegrationTest.php
├── composer.json
├── phpunit.xml
└── docker-compose.yml
- SyncEmitter: Simple, blocking requests
- CurlEmitter: Async, high-volume, batching
- SocketEmitter: Persistent connection
- FileEmitter: Background processing with workers
e
: Event type (required)tv
: Tracker version (auto-added)tna
: Namespace (optional)aid
: App ID (optional)dtm
: Device timestamp (auto-added)
// ✅ Test with mock collector
$emitter = new SyncEmitter("localhost", "http", "POST", 1, true);
$tracker = new Tracker($emitter, new Subject());
When adding or updating content in this document, please follow these guidelines:
- CLAUDE.md must not exceed 40KB (currently ~19KB)
- Check file size after updates:
wc -c CLAUDE.md
- Remove outdated content if approaching the limit
- Keep all code examples 4 lines or fewer
- Focus on the essential pattern, not complete implementations
- Use
// ❌
and // ✅
to clearly show wrong vs right approaches
- Add new patterns to existing sections when possible
- Create new sections sparingly to maintain structure
- Update the architectural principles section for major changes
- Ensure examples follow current codebase conventions
- Test any new patterns in actual code before documenting
- Verify imports and syntax are correct for the codebase
- Keep language concise and actionable
- Focus on "what" and "how", minimize "why" explanations
- Directory-specific CLAUDE.md files can be created for specialized modules
- Follow the same structure and guidelines as this root CLAUDE.md
- Keep them focused on directory-specific patterns and conventions
- Maximum 20KB per directory-specific CLAUDE.md file
When editing files in this repository, always check for CLAUDE.md guidance:
- Look for CLAUDE.md in the same directory as the file being edited
- If not found, check parent directories recursively up to project root
- Follow the patterns and conventions described in the applicable CLAUDE.md
- Prioritize directory-specific guidance over root-level guidance when conflicts exist