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 being an array depicting the $dateType and $dateOffset.

$discrete = array(
	'2009-01-01' => array('type' => Statsburner::TYPE_MONTH, 'offset' => 1),
	'2008-07-01' => array('type' => Statsburner::TYPE_DAY, 'offset' => 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.

The most basic of methods to grab your statistics is to use the getFeedData() 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. By default, the method will grab all statistics for the previous month.

$feed = new Statsburner('starcraft');
$stats = $feed->getFeedData();

If you would like to grab statistics for only the last 7 days (if it was Jan 14th), the following code will suffice.

$stats = $feed->getFeedData(array(
	'2011-01-07' => array('type' => StatsBurner::TYPE_DAY, 'offset' => '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 = $feed->getFeedData(array(
	// November 1st 2010 - December 1st 2010
	'2010-11-01',
 
	// January 1st - February 1st 2011
	'2011-01-01' => Statsburner::TYPE_MONTH,
 
	// February 26th 2010
	'2011-02-26' => array('type' => Statsburner::TYPE_DAY, 'offset' => 0),
 
	// June 1st - August 1st 2010
	'2010-06-01' => array('type' => Statsburner::TYPE_MONTH, 'offset' => 2)
));

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
	)
)

Item Data
To grab statistics on item views and clickthrough data, use getItemData(). This method also takes an array of date ranges as the first argument. It also takes a second argument of the ID of the item you want to fetch (optional).

$stats = $feed->getItemData();

Syndication Data
To grab statistics on referrals and feed clickthrough data, use getResyndicationData(). This method also takes an array of date ranges as the first argument. It also takes a second argument of the ID of the item you want to fetch (optional).

$stats = $feed->getResyndicationData();

By default Statsburner will cache all feed requests into a folder relative to the classes location. All feeds are cached by default for 1 hour but this could be changed by using setCaching(), which also changes the path. The duration uses strtotime() for time parsing.

// Default cache location and 5 minute duration
$feed->setCaching(dirname(__FILE__) .'/cache/', '+5 minutes');

You can also delete old cache by using flush(). It takes 1 argument which is the timestamp of expiration length.

$feed->flush('-60 days'); // Delete cache older than 60 days