README

1.0.0 WORK IN PROGRESS

Bitter Laravel is a simple but powerful analytics library for Laravel

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

• Jérémy Romey and Winter Faulk

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?

Requirements

Note I have only used this on Laravel 5.1, but it should work with other versions.

• PHP 7+
• Redis (v2.6 or grater)
• Carbon

Installation

Composer

Add the following to your composer.json or run composer require faulker/bitter-laravel:

{
    "require": {
        "faulker/bitter-laravel": "1.*"
    }
}

Laravel

Add the following to the config/app.php file:

'providers' => [
    Faulker\Bitter\BitterServiceProvider::class,
    ...
],
'aliases' => [   
    'Bitter' => Faulker\Bitter\Facade\Bitter::class,
    ...
]

Then run php artisan vendor:publish --provider="Faulker\Bitter\BitterServiceProvider" --tag="config"

Config

Config file config/bitter.php holds some basic configuration info for the library.

Default config file

return [
    'connection' => 'default',
    'expire'     => 60,
    'key'        => [
        'prefix' => 'bitter:',
        'temp_prefix' => 'bitter_temp:',
    ],
];

• connection: The redis database connection to use that is located in the config/database.php.
• expire: The number of seconds a temp Redis key should last.
• prefix: The Redis prefix to use for data being stored in Redis.
• temp_prefix: The temp prefix to use for all temp data being stored in Redis.

Basic usage

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 and slow the process down.

Pass a DateTime as third argument:

Bitter::mark('song:played', 123, Carbon::yesterday());

Test if user 123 has played a song this week:

$currentWeek = 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 = Bitter::unitOfTime('day', 'active', Carbon::yesterday());

echo Bitter::count($yesterday) . ' users were active yesterday.';

Using BitOp

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

$today     = Bitter::UnitOfTime('day', 'active');
$yesterday = Bitter::UnitOfTime('day', 'active', Carbon::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     = Bitter::UnitOfTime('day', 'active');
$yesterday = Bitter::UnitOfTime('day', 'active', Carbon::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 = Carbon::parse('2016-02-14');
$to   = Carbon::parse('2016-12-21');


$count = Bitter::bitDateRange('active', 'active_period_example', $from, $to)
               ->count('active_period_example');
               
echo $count . ' users were active from "2016-02-14" to "2016-12-21".';

Get Ids for a given key

Get Ids for a given date period:

$from = Carbon::parse('2016-02-14');
$to   = Carbon::parse('2016-12-21');


$ids = Bitter::bitDateRange('active', 'active_period_example', $from, $to)
             ->getIds('active_period_example');
             
echo 'Ids of users that were active from "2016-02-14" to "2016-12-21":';
echo '<br />';
echo implode(', ', $ids);

Release notes

Todo

• Clean up datetime code and make it more user friendly
• Add more Laravel friendly features, such as the ability to tie in with Eloquent

Thanks

This library is a branch of jeremyFreeAgent/Bitter which is a port of bitmapist (Python) by Amir Salihefendic.