Snowplow PHP Tracker 0.4.0 released

We are pleased to announce a new release of the Snowplow PHP Tracker.

Version 0.4.0 adds support for the dvce_sent_tstamp as well as setting the true_tstamp using the optional timestamp argument. It also switches the event_id into UUID version 4 and updates the payload_data JSON schema to its latest version. In addition it fixes a bug affecting the FileEmitter.

This release removes features deprecated in PHP 8, resulting in removing errcontext from the custom error handler (many thanks to @angsmugmug for raising this issue and contributing the fix) and in making the items argument optional in trackEcommerceTransaction. It also removes the dependency to the rmccue/requests library, which was replaced by the standard inbuilt cURL library.

Finally it adds security monitoring by Snyk through GitHub Actions.

Read on below for:

1. Support for the dvce_sent_tstamp 
2. Setting the true_tstamp of an event
3. Switching to UUID version 4 for event_id
4. Bug fix in FileEmitter
5. Items argument optional in trackEcommerceTransaction
6. Installation and upgrading
7. Documentation and help

1. Support for the dvce_sent_tstamp

The PHP Tracker now also supports the dvce_sent_tstamp (Github issue #56). This is the timestamp that captures the device’s clock when the event was sent to the collector and it is being used to accurately calculate the derived_tstamp, which is the recommended timestamp to use in your analytics.

For more information you can read Snowplow’s understanding of time and the Date/time parameters section in the Snowplow Tracker Protocol.

2. Setting the true_tstamp of an event

The true_tstamp is the exact timestamp of when the event occurred that is set by the user using the optional timestamp argument in all tracking methods. This timestamp argument should be provided as a Unix timestamp in milliseconds.

By default, the PHP Tracker generates the dvce_created_tstamp and adds it to event payload. As described in GitHub issue #59, before version 0.4.0, the PHP Tracker was incorrectly setting the dvce_created_tstamp through the optional timestamp argument. With the latest release, the optional timestamp argument correctly sets the true_tstamp and adds it to the event payload, besides the autogenerated dvce_created_tstamp.

For example:

$tracker->trackPageView("www.example.com", NULL, NULL, NULL, 1615276492062);

As also mentioned in the documentation, the optional timestamp argument should be in milliseconds. For example, if you are using PHP’s time(), which returns the current Unix timestamp in seconds:

$tracker->trackPageView("www.example.com", NULL, NULL, NULL, time() * 1000);

3. Switching to UUID version 4 for event_id

Before version 0.4.0, the PHP Tracker was generating a version 1, time-based UUID for the event_id’s. With this release (GitHub issue #94), through the ramsey/uuid library, the event_id is a random, RFC 4122 version 4 UUID.

4. Bug fix in FileEmitter

As described in GitHub issue #81, the FileEmitter was making use of chdir(). This was problematic for production environments, as it was changing PHP’s current directory. In the 0.4.0 release, the use of the chdir function was completely removed.

5. Items argument optional in trackEcommerceTransaction

When declaring a function or a method, adding a required parameter after optional parameters is deprecated since PHP 8.0. This was affecting the trackEcommerceTransaction tracking method (GitHub issue #97), which had $items as a required parameter after optional parameters in its signature. Since an ecommerce transaction does not have to include any items, we made this parameter optional, with an empty array as its default value. This is a non-breaking change that does not affect any users of this method.

6. Installation and upgrading

Through Composer, you can add the Snowplow PHP Tracker version 0.4.0 to your project by including it in your composer.json file as a dependency.

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

7. Documentation and help

For help on integrating the tracker please have a look at the setup guide. Information about how to use the tracker can be found in the PHP Tracker documentation. If you have any questions or run into any problems, please visit our Discourse forum.

You can find the full release notes on GitHub as Snowplow PHP Tracker v0.4.0 release.

Please raise any bugs in the PHP Tracker’s issues on GitHub.