PHPackages                             jithujose/bitter - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Caching](/categories/caching)
4. /
5. jithujose/bitter

ActiveLibrary[Caching](/categories/caching)

jithujose/bitter
================

Bitter is a simple but powerful analytics library

1.1.1(12y ago)012MITPHPPHP >=5.3.3

Since Nov 28Pushed 9y agoCompare

[ Source](https://github.com/jithujose/Bitter)[ Packagist](https://packagist.org/packages/jithujose/bitter)[ Docs](https://github.com/jeremyFreeAgent/Bitter)[ RSS](/packages/jithujose-bitter/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (2)Versions (6)Used By (0)

Bitter Documentation
====================

[](#bitter-documentation)

[![https://secure.travis-ci.org/jeremyFreeAgent/Bitter.png?branch=master](https://camo.githubusercontent.com/c452e9d8ec8b197b07f9c056ed38086b1623cea8176966fb9147fde057c18eb0/68747470733a2f2f7365637572652e7472617669732d63692e6f72672f6a6572656d79467265654167656e742f4269747465722e706e673f6272616e63683d6d6173746572)](http://travis-ci.org/jeremyFreeAgent/Bitter)**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](http://bitter.free-agent.fr/) website for more info and documentation about this project.

Installation
------------

[](#installation)

Use [Composer](https://github.com/composer/composer/) to install: `free-agent/bitter`.

In your composer.json you should have:

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

### Requirements

[](#requirements)

Bitter uses [Redis](http://redis.io) 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](http://pecl.php.net/package/Bitset) with version **=1.0.1** for the `getIds` method.

Basic usage
-----------

[](#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
-----------

[](#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](http://redis.io/commands/bitop) for performance considerations.

Custom date period stats
------------------------

[](#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-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 '';
echo implode(', ', $ids);
```

Unit Tests
----------

[](#unit-tests)

You can run tests with:

```
bin/atoum -d tests/units
```

Release notes
-------------

[](#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
----

[](#todo)

- Implements the [Redis BITOP NOT Command](http://redis.io/commands/bitop).

Thanks
------

[](#thanks)

This library is a port of [bitmapist](https://github.com/Doist/bitmapist/) (Python) by [Amir Salihefendic](http://amix.dk/).

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity5

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 91.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~98 days

Total

4

Last Release

4615d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ad54761513858d9ec2e463152fea703191115bfc12f09df157b07efb95a95242?d=identicon)[jithujose](/maintainers/jithujose)

---

Top Contributors

[![jeremyFreeAgent](https://avatars.githubusercontent.com/u/176363?v=4)](https://github.com/jeremyFreeAgent "jeremyFreeAgent (75 commits)")[![stephpy](https://avatars.githubusercontent.com/u/232744?v=4)](https://github.com/stephpy "stephpy (4 commits)")[![tonypiper](https://avatars.githubusercontent.com/u/206124?v=4)](https://github.com/tonypiper "tonypiper (3 commits)")

---

Tags

redisanalyticsbitter

### Embed Badge

![Health badge](/badges/jithujose-bitter/health.svg)

```
[![Health](https://phpackages.com/badges/jithujose-bitter/health.svg)](https://phpackages.com/packages/jithujose-bitter)
```

###  Alternatives

[predis/predis

A flexible and feature-complete Redis/Valkey client for PHP.

7.8k305.7M2.4k](/packages/predis-predis)[snc/redis-bundle

A Redis bundle for Symfony

1.0k39.4M67](/packages/snc-redis-bundle)[clue/redis-protocol

A streaming Redis protocol (RESP) parser and serializer written in pure PHP.

5311.0M13](/packages/clue-redis-protocol)[cache/redis-adapter

A PSR-6 cache implementation using Redis (PhpRedis). This implementation supports tags

523.9M27](/packages/cache-redis-adapter)[rtcamp/nginx-helper

Cleans nginx's fastcgi/proxy cache or redis-cache whenever a post is edited/published. Also provides cloudflare edge cache purging with Cache-Tags.

23817.0k1](/packages/rtcamp-nginx-helper)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)