README.rst

Bitter Documentation

1.2.0 WORK IN PROGRESS

Bitter is a simple but powerful analytics library

"Use Bitter and you have time to drink a bitter beer !"

-- Jérémy Romey

Bitter can answer following questions:

• Has user X been online today? This week? This month?
• Has user X performed action "Y"?
• How many users have been active have this month? This hour?
• How many unique users have performed action "Y" this week?
• How many % of users that were active last week are still active?
• How many % of users that were active last month are still active this month?

Bitter is very easy to use and enables you to create your own reports easily - see the Bitter Library website for more info and documentation about this project.

Installation

Use Composer to install: free-agent/bitter.

In your composer.json you should have:

{
    "require": {
        "free-agent/bitter": "1.1.*"
    }
}

Requirements

Bitter uses Redis with version >=2.6.

Note: Every key created in Redis will be prefixed by bitter:, temp keys by bitter_temp:.

Bitter uses Bitset PECL extension with version =1.0.1 for the getIds method.

Basic usage

Create a Bitter with a Redis client (Predis as example):

$redisClient = new \Predis\Client();
$bitter = new \FreeAgent\Bitter\Bitter($redisClient);

Mark user 123 as active and has played a song:

$bitter
    ->mark('active', 123)
    ->mark('song:played', 123)
;

Note: Please don't use huge ids (e.g. 2^32 or bigger) cause this will require large amounts of memory.

Pass a DateTime as third argument:

$bitter->mark('song:played', 123, new \DateTime('yesterday'));

Test if user 123 has played a song this week:

$currentWeek = new FreeAgent\Bitter\UnitOfTime\Week('song:played');

if ($bitter->in(123, $currentWeek) {
    echo 'User with id 123 has played a song this week.';
} else {
    echo 'User with id 123 has not played a song this week.';
}

How many users were active yesterday:

$yesterday = new \FreeAgent\Bitter\UnitOfTime\Day('active', new \DateTime('yesterday'));

echo $bitter->count($yesterday) . ' users were active yesterday.';

Using BitOp

How many users that were active yesterday are also active today:

$today     = new \FreeAgent\Bitter\UnitOfTime\Day('active');
$yesterday = new \FreeAgent\Bitter\UnitOfTime\Day('active', new \DateTime('yesterday'));

$count = $bitter
    ->bitOpAnd('bit_op_example', $today, $yesterday)
    ->count('bit_op_example')
;
echo $count . ' users were active yesterday and today.';

Note: The bit_op_example key will expire after 60 seconds.

Test if user 123 was active yesterday and is active today:

$today     = new \FreeAgent\Bitter\UnitOfTime\Day('active');
$yesterday = new \FreeAgent\Bitter\UnitOfTime\Day('active', new \DateTime('yesterday'));

$active = $bitter
    ->bitOpAnd('bit_op_example', $today, $yesterday)
    ->in(123, 'bit_op_example')
;
if ($active) {
    echo 'User with id 123 was active yesterday and today.';
} else {
    echo 'User with id 123 was not active yesterday and today.';
}

Note: Please look at Redis BITOP Command for performance considerations.

Custom date period stats

How many users that were active during a given date period:

$from = new \DateTime('2010-14-02 20:15:30');
$to   = new \DateTime('2012-21-12 13:30:45');

$count = $bitter
    ->bitDateRange('active', 'active_period_example', $from, $to)
    ->count('active_period_example')
;
echo $count . ' users were active from "2010-14-02 20:15:30" to "2012-21-12 13:30:45".';

Get Ids for a given key

Get Ids for a given date period:

$from = new \DateTime('2010-14-02 20:15:30');
$to   = new \DateTime('2012-21-12 13:30:45');

$ids = $bitter
    ->bitDateRange('active', 'active_period_example', $from, $to)
    ->getIds('active_period_example')
;
echo 'Ids of users that were active from "2010-14-02 20:15:30" to "2012-21-12 13:30:45":';
echo '<br />';
echo implode(', ', $ids);

Unit Tests

You can run tests with:

bin/atoum -d tests/units

Release notes

1.2.0

• Added a remove method to remove a specific temp key.
• Added a removeEvent method to remove all data of an event.
• Renamed Event to UnitOfTime in order to be more explicit.

1.1.0

• Added date period stats with bitDateRange method.

Todo

• Implements the Redis BITOP NOT Command.

Thanks

This library is a port of bitmapist (Python) by Amir Salihefendic.