Download the PHP package tijmenwierenga/snowplow-tracker without Composer

Snowplow Tracker

An alternative to the original Snowplow Tracker.

This Tracker provides:

• an object-oriented API for event tracking
• extension points in order to integrate your own domain logic
• abstractions to swap dependencies

Installation

With composer:

Setup

The Snowplow Tracker is instantiable by providing an emitter and optionally additional configuration. Currently, only a single emitter is available: the HttpClientEmitter.

HttpClientEmitter

The HttpClientEmitter sends the payload to a collector over HTTP. If you want to use this emitter a PSR-7, PSR-17 and PSR-18 compliant implementation needs to be installed.

Popular PSR-18 compliant HTTP Clients are:

• symfony/http-client
• guzzlehttp/guzzle

Popular PSR-7 compliant libraries are:

• guzzlehttp/psr7
• nyholm/psr7

By default, the php-http/discovery will discover the installed HTTP Client and Request Factory so no additional configuration is required. If you wish to configure your HTTP client yourself you can pass in your own. Same goes for the Request Factory.

With auto-discovery:

Without auto-discovery (with Symfony's HTTP client):

Tracker configuration

In order to customize the tracker's configuration you can pass an additional configuration object:

Handling failures

Whenever emitting an event fails, you don't want to lose the data. Therefore, a TijmenWierenga\SnowplowTracker\Emitters\FallbackStrategy exists in order to help you recover from failures.

The FallbackStrategy is called whenever the TijmenWierenga\SnowplowTracker\Emitters\FailedToEmit exception is raised. By default, a void fallback strategy is used, which means nothing happens when an event failed emitting. It's advised to implement an own implementation that stores the failed payloads in order to attempt to send the failed events at a later time.

Configure the fallback strategy as a constructor argument for the Tracker:

If a FailedToEmit exception is raised, the Tracker will rethrow the exception after calling the fallback strategy. This could potentially lead to client-facing errors which may be undesirable. This behaviour can be changed by setting the $throwOnError constructor argument for the Tracker:

Please note that without a sufficient fallback strategy, ignoring exceptions will lead to data loss without anyone noticing.

Usage

Tracking events is done by calling the track() method on the Tracker instance: This library implements 6 type of events.

Pageviews

Page pings

Ecommerce transactions

Transaction items

Structured events

Unstructured events

The Snowplow Tracker protocol

All events extend from a base event class which implements all properties currently available in the Snowplow Tracker Protocol. These properties are publicly available in every event. The example below shows how to add a userId to an event to identify a user:

Custom context

Sometimes you want to add additional context to an event. Custom contexts are self-describing JSON schema's which can be implemented by creating a class that implements TijmenWierenga\SnowplowTracker\Events\Schemable. The example below shows an implementation of the existing Timing JSON Schema as defined by Snowplow Analytics.

As an example, let's include context about the page load in a pageview event:

Middleware

Middlewares provides a way to act on events that are tracked. Every piece of middleware is a callable that receives the event as an argument and must return the (modified) event to the next piece of middleware:

This is incredibly useful when you want to add contextual information to every event. As an example, middleware is added that adds the userId of the currently authenticated user to the event.

In the example above both events will now have a userId attached.