Stats guide

The Stats module stores statistical events in a persistent log as they occur, aimed at providing insight about the activity in your app like the number of received visits in a web page, page views, clicks, hits or other similar statistical data.

Setting up the Stats database table

Events are stored in the cherrycake_stats database table using a shared-memory buffer and a programmed Janitor commit task for optimal performance, resulting in a system capable of ingesting many events per second without a noticeable performance impact.

You can create the Stats table in your database by importing the stats.sql file you'll find in the Cherrycake skeleton repository, under the install/database directory.

Creating a StatsEvent

Stats events are stored as objects that extend the base StatsEvent class. You must create one StatsEvent class per each statistical data point you want to store.

Let's say you want to keep track of the number of views received by the home page of your web site app every day. To do so we'll create a new class called StatsEventHomeView in the classes/StatsEventHomeView.class.php file, like this:

<?php

namespace CherrycakeApp;

class StatsEventHomeView extends \Cherrycake\Stats\StatsEvent {
	protected $timeResolution = \Cherrycake\Stats\STATS_EVENT_TIME_RESOLUTION_DAY;
	protected $typeDescription = "Home view";
}

Note that we specified STATS_EVENT_TIME_RESOLUTION_DAY as the timeResolution for our StatsEventHomeView. This will cause this event to be counted in a daily basis, meaning only one row will be stored in the database for each different day, along containing a counter of the number of times the event has been triggered during that day.

You can specify other time resolutions as well, all of them are self-explanatory:

• STATS_EVENT_TIME_RESOLUTION_MINUTE

• STATS_EVENT_TIME_RESOLUTION_HOUR

• STATS_EVENT_TIME_RESOLUTION_DAY

• STATS_EVENT_TIME_RESOLUTION_MONTH

• STATS_EVENT_TIME_RESOLUTION_YEAR

You should choose the time resolution that better fits your needs, keeping in mind that events defined with a smaller time resolution will need more rows in the database.

If you need a precise log of events instead of the statistical approach of counting the times an event is triggered within a time frame, see the Log guide module instead.

Triggering a Stats event

In the part of your code where you want to trigger the stats event, call the Stats::trigger method like this:

$e->Stats->trigger(new StatsEventHomeView);

See this example working in the Cherrycake documentation examples site.

What's the difference between a LogEvent and a StatsEvent?

The Log module stores an object in the database for each logged event, allowing individual events to hold their own unique data, but causing the database to grow rapidly when lots of LogEvent objects are stored.

Stats, in the other hand, stores a single object in the database for all the events triggered during a certain period. This doesn't allows for individual Stats events to hold their own differentiating data because it only stores the number of times a certain event has been triggered, but makes Stats a more suitable solution to store big amounts of events, and it's an ideal solution to store statistical data of any kind.