milesjohnson

StatsBurner is a lightweight script that plugs into Feedburners Awareness API to grab statistics for your feeds. The class is really easy and straight forward, but there are a few key variables that you will see a lot that I would like to talk about. For all my examples I will be using the feed for the Starcraft 2 Armory: http://feeds.feedburner.com/starcraft.

$feedURI
The $feedURI would be the slug used in your Feedburner URL. For instance, the slug in the URL above would be "starcraft". The slug is what you would pass as the first argument for most of the methods within this class.

$dateType
The $dateType variable would be a string containing the type of date you are passing, the following are valid: m, d, y. Additionally, you can use the pre-built class constants to achieve the same effect. The type you pass determines how lengthy in time should the API grab statistics for. For example, if you pass TYPE_MONTH (m), the API will grab all statistics for 1 month (if $dateOffset is 1).

$dateOffset
The $dateOffset defines the ranges and length of dates used in the API call. If the $dateType is TYPE_DAY and the $dateOffset is 3, it will only grab statistics for three days.

$dateDiscrete
The $dateDiscrete variables allows you to specify multiple date ranges to be used, basically allowing you to select certain dates specifically. The variable should be passed an array with the index being the date you want to grab and the value should be a pipe (|) separated value depicting the $dateType and $dateOffset.

$discrete = array(
	'2009-01-01' => 'm|1',
	'2008-07-01' => 'd|14'
);

In the example above, we will be grabbing all dates from December 1st 2008 - January 1st 2009 as well as dates from June 16th 2008 - July 1st 2008. Furthermore, dates may overlap BUT will not be counted towards the final statistics if the $allowDupeDates property is set to false.

Important! Do note that dates go backwards in time depending on the offset. So if you passed a date of June 1st 2006 with an offset of 1 month, the actual date will be May 1st - June 1st, NOT June 1st - July 1st.

Using cURL
Another way you can speed up the HTTP requests to the Awareness API is by using cURL (Enabled by default). Most PHP installations come pre-installed with cURL, but if yours does not you can simply install it. To use cURL, simply enable it before you do your getStats() call. However if cURL is not installed, the remote request should still work.

StatsBurner::$useCURL = true;

Duplicate dates within statistics
By default the script does not allow duplicate or overlapping dates within the final statistics. If overlapping dates are allowed, it means that the returned averages will be incorrect because its adding fake data! If for some odd reason you want to allow duplicate dates, simply turn it on.

StatsBurner::$allowDupeDates = true;

The most basic of methods to grab your statistics is to use the getStats() method. This method simply grabs the Awareness API XML and passes it into a simple_xml object. The object is then parsed into an array for your use. The getStats() method takes four arguments: $feedUri, $dateType, $dateOffset, $dateDiscrete. By default, the method will grab all statistics for the previous month.

$stats = StatsBurner::getStats('starcraft');

If you would like to grab statistics for only the last 7 days, the following code will suffice.

$stats = StatsBurner::getStats('starcraft', StatsBurner::TYPE_DAY, 7);

Now if you would like to grab certain dates and date ranges on top of the previous month (or custom date), you would use the discrete dates variable. As explained in the previous chapter, the $dateDiscrete should be an array of dates and type|offset.

$stats = StatsBurner::getStats('starcraft', StatsBurner::TYPE_DAY, 1, array(
	'2009-01-01' => 'm|1',
	'2008-07-01' => 'm|1'
));

If you would like to grab certain discrete dates, but not grab the previous dates statistics, just pass null to $dateType and $dateOffset. The example below is the array format returned from these methods.

Array (
    [id] => t4frmvjinetsgepjjci8m5f5i8
    [uri] => starcraft
    [api] => https://feedburner.google.com/api/awareness/1.0/GetFeedData?uri=starcraft&dates=2009-09-05,2009-10-05
    [circulation] => 1003
    [hits] => 6682
    [downloads] => 0
    [reach] => 174
    [dates] => 2009-09-05,2009-10-05
)

// Array returned will have a different dates index if using discrete dates
Array (
    [id] => t4frmvjinetsgepjjci8m5f5i8
    ...
    [dates] => Array (
            [0] => 2009-10-04,2009-10-05
            [1] => 2008-12-01,2009-01-01
            [2] => 2008-06-01,2008-07-01
	)
)

One major fallback of using getStats() is that it needs to do a remote HTTP request to Feedburners Awareness API on each page view. This can get quite slow and cumbersome, and in rare cases the API could be completely down (so you would not get a returned array). To cut down the number of API requests within each HTTP request, StatsBurner comes built in with a way to store a local XML file of the API for that request. It is best to run a cron job that builds this XML at intervals, instead of hitting the API directly.

Before you can store the XML files, you need to define the location of each XML as well as the feed URI (slug). You can do this by using the addXML() method. The first argument should be the slug and the second argument should be a path to the XML file (It must be relative to your servers root directory, $_SERVER['DOCUMENT_ROOT']).

StatsBurner::addXml('starcraft', '/library/xml/stats.xml');

once you have define the slug and its destination, you can store the XML by using the the buildXml() method. Its arguments work in the same manner as getStats(), but instead of returning an array, it creates an XML file.

StatsBurner::buildXml('starcraft');

Now that your XML has been created, you can use the getStatsFromXml() method instead of getStats(). In both cases, the same information will be returned, albeit the local XML might be out of sync depending on how long your cron intervals are.

$stats = StatsBurner::getStatsFromXml('starcraft');