Snowplow PHP Tracker 0.2.0 released

05 January 2015  •  Joshua Beemster

We are pleased to announce the release of the second version of the Snowplow PHP Tracker. The tracker now supports a variety of synchronous, asynchronous and out-of-band event emitters for GET and POST requests.

Please note that version 0.2.0 of the PHP Tracker is dependent upon Snowplow 0.9.14; for more information please refer to the technical documentation.

This release post will cover the following topics:

  1. New emitters explained
  2. New client passthrough functions
  3. Debug mode added
  4. Upgrading
  5. Getting help

There are now four different emitters available for use with the PHP Tracker, all of which fully support Snowplow’s event collectors via GET and POSTrequests:

  1. The Sync or synchronous emitter is a carry-over from version 0.1.0 and has not changed
  2. The Socket emitter is a new emitter with the ability to write Requests directly to a HTTP socket; this has delivered a drastic speed improvement over Sync. However, it is still synchronous and blocking in its operation
  3. The Curl emitter provides a ‘nearly’ asynchronous Request emitter, in that we can send multiple requests simultaneously. This emitter shines in GET operation as by nature we can only include one event per GET request; this operates much faster than even the Socket emitter
  4. The File emitter delivers a non-blocking out-of-band emitter. This works by spawning a background worker process which consumes log files containing events generated by the Tracker. It uses the same approach as the Curl Emitter but it does not halt the main script from executing and we can have as many as our host machine allows; it depends on writing log files to disk

More information on the PHP Tracker’s new emitters can be found in the wiki.

This release also adds with it four new functions to let you “pass through” information from your end client (i.e. the user’s web browser) with your events. You can now set:

  • The clients’s ip address: $subject->setIpAddress("127.0.0.1")

  • The useragent: $subject->setUseragent("Agent Smith")

  • The network user id: $subject->setNetworkUserId("123")

  • The domain user id: $subject->setDomainUserId("abc")

All of these pieces of information will be passed with every subsequent event sent from the Tracker instance.

The emitters included with the PHP Tracker now come with debug mode. This mode sets up local logging for any errors encountered by the emitters, such as an invalid host or the inability to establish a socket connection to the collector.

On any failure, debug mode will record the error along with the payload that was meant to be sent. To enable debug mode, all you need to do is append a true boolean to the end of the emitter constructor like so:

$emitter = new SyncEmitter("d3rkrsqld9gmqf.cloudfront.net", "http", "POST", 50, true);

All debug files will be logged at this address: project_root\vendor\snowplow-tracker\debug\sync-events-[[random number]].log.

If the Tracker is unable to create the log files it will begin printing all debug information to the console.

For more information on debugging please consult the wiki.

The Snowplow PHP Tracker is published to Packagist, the central repository for Composer PHP packages. To add the latest version to your project, add it as a requirement in your composer.json file:

{
    "require": {
        "snowplow/snowplow-tracker": "0.2.0"
    }
}

Then simply run composer update from the root of your project to install it.

Some useful resources:

The Snowplow PHP Tracker is still young, so do please raise an issue if you find any bugs. And if you have an idea for a new feature or need help getting set up, get in touch!