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.

faulker / bitter-laravel

Maintainers

Details