README

A lightweight and dependency-free PHP implementation of the HyperLogLog probabilistic data structure for approximate cardinality estimation.

HyperLogLog allows you to estimate the number of distinct elements in very large datasets while using only a small, fixed amount of memory.

Features

🚀 Fast approximate distinct counting
📦 Zero dependencies
🔧 Configurable number of registers (counterBits)
🔐 Configurable hashing algorithm (xxh3, sha256, md5, etc.)
📊 Theoretical error rate calculation
🧮 Small and large cardinality bias corrections
✅ Strict types and fully documented source code

Requirements

PHP 8.0, 8.1, 8.2, 8.3, 8.4 and 8.5
No external dependencies

Note: The xxh3 and xxh128 hash algorithms are available only when supported by your PHP version and build. If unavailable, you can use any other algorithm returned by hash_algos(), such as sha256, sha512, or md5.

Installation

Install via Composer:

composer require hichxm/hyperloglog

Basic Usage

<?php

use Hichxm\HyperLogLog\HyperLogLog;

$hll = new HyperLogLog();

$hll->add('apple');
$hll->add('banana');
$hll->add('orange');
$hll->add('apple'); // duplicate

echo $hll->count();

The returned value is an approximation of the number of unique elements.

Constructor

new HyperLogLog(
    int $counterBits = 5,
    string $hashAlgorithm = 'xxh3'
);

Parameters

Parameter	Description
`counterBits`	Number of bits used to select registers. The number of registers is `2^counterBits`.
`hashAlgorithm`	Any hashing algorithm supported by PHP's `hash()` function.

Increasing counterBits improves accuracy while increasing memory usage.

Example:

$hll = new HyperLogLog(
    counterBits: 10,
    hashAlgorithm: 'sha256'
);

Accuracy

The theoretical standard error is:

1.04 / √m

where:

m = 2^counterBits

Example:

$error = $hll->theoreticalErrorRate($hll->getM());

Supported Hash Algorithms

Any algorithm supported by PHP can be used.

Examples include:

xxh3 (recommended when available)
xxh128
sha256
sha512
md5
sha1

You can list available algorithms using:

print_r(hash_algos());

Public API

Add an element

$hll->add('user-123');

Estimate the number of distinct values

$count = $hll->count();

Calculate the theoretical error

$error = $hll->theoreticalErrorRate($hll->getM());

Measure estimation error

$error = $hll->measureError($estimated, $actual);

When to Use HyperLogLog

HyperLogLog is well suited for:

Counting unique visitors
Counting unique IP addresses
Analytics pipelines
Large log processing
Stream processing
Database statistics
Big data applications

It is not appropriate when an exact distinct count is required.

References

https://en.wikipedia.org/wiki/HyperLogLog

License

MIT

hichxm / hyperloglog

Maintainers

Package info

Statistics

Security