README

Symfony integration for pouya1364/probabilistic-php. Define Bloom filters, Counting Bloom filters, Cuckoo filters, Count-Min sketches, and HyperLogLogs once in configuration, then access them anywhere in your application as named, pre-configured services.

For the algorithms themselves — accuracy guarantees, memory characteristics, and the maths behind each structure — see the core probabilistic-php library. This bundle is only the framework wiring.

Requirements

• PHP 8.2+
• Symfony 6.4, 7.x, or 8.x

Installation

composer require pouya1364/probabilistic-bundle

If you use Symfony Flex the bundle is registered automatically. Otherwise enable it in config/bundles.php:

return [
    // ...
    ProbabilisticBundle\ProbabilisticBundle::class => ['all' => true],
];

Configuration

Create config/packages/probabilistic.yaml. Every structure type holds any number of independently-sized, named instances — a real app typically needs several Bloom filters for different purposes, each configured differently.

probabilistic:
    bloom_filters:
        emails_seen:
            expected_items: 100000
            false_positive_rate: 0.01

    counting_bloom_filters:
        active_sessions:
            expected_items: 50000
            false_positive_rate: 0.01

    cuckoo_filters:
        rate_limited_ips:
            expected_items: 100000

    count_min_sketches:
        page_view_counts:
            width: 2000
            depth: 5

    hyperloglogs:
        unique_visitors:
            precision: 14

Configuration reference

Why expected_items and not expectedItems?

The configuration keys are written in snake_case to match Symfony's configuration conventions (the same style as false_positive_rate, framework.http_method_override, and so on). The underlying probabilistic-php factories, however, take camelCase named arguments — BloomFilter::create(expectedItems: …, falsePositiveRate: …).

The bundle bridges the two: it accepts your snake_case YAML and translates each key to its camelCase equivalent internally, right before constructing the structure. You write idiomatic Symfony config; the library still receives exactly the argument names it expects. You never have to think about the conversion — this note exists only so the difference isn't surprising if you compare your YAML against the library's method signatures.

Usage

Option 1 — the registry

Inject ProbabilisticBundle\Registry\ProbabilisticRegistry (autowired) and ask it for instances by name. Each instance is built lazily on first access and reused for the rest of the request.

use ProbabilisticBundle\Registry\ProbabilisticRegistry;

final class SignupService
{
    public function __construct(
        private readonly ProbabilisticRegistry $probabilistic,
    ) {
    }

    public function isProbablyDuplicate(string $email): bool
    {
        $seen = $this->probabilistic->bloomFilter('emails_seen');

        if ($seen->mightContain($email)) {
            return true;
        }

        $seen->add($email);

        return false;
    }
}

Available registry methods, each taking the instance name (defaulting to 'default'):

Asking for a name that isn't configured throws ProbabilisticBundle\Registry\UnknownInstanceException.

Option 2 — direct named-service autowiring

Every configured instance is also registered as its own service, named probabilistic.<type>.<name>, so you can wire a single specific structure straight into a service without going through the registry:

use Probabilistic\HyperLogLog;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

final class VisitorStats
{
    public function __construct(
        #[Autowire(service: 'probabilistic.hyperloglog.unique_visitors')]
        private readonly HyperLogLog $uniqueVisitors,
    ) {
    }

    public function record(string $visitorId): void
    {
        $this->uniqueVisitors->add($visitorId);
    }

    public function estimatedUniqueVisitors(): int
    {
        return $this->uniqueVisitors->estimate();
    }
}

The service ids follow the singular form of each group:

Both approaches return the same shared instance for a given name within a request, so mixing them is fine.

Console

List everything that is configured, grouped by structure type:

php bin/console probabilistic:list

License

MIT. See LICENSE.