Download the PHP package brandonbronisz/php-bloom without Composer

php-bloom

php-bloom is a native PHP 8 extension that provides a compact Bloom filter implementation for fast probabilistic membership checks.

Bloom filters answer one question efficiently: "have I probably seen this value before?" A negative result means the value is definitely absent. A positive result means the value might be present and should be verified against an authoritative store when false positives matter.

Requirements

• PHP >=8.0 <9.0
• PIE, for package-based installation
• Unix-like builds: phpize, php-config, a C compiler, and make
• Windows builds: PHP SDK tooling through php/php-windows-builder or an equivalent PHP Windows build environment
• Docker, only for the MySQL benchmark

Install With PIE

PIE builds and enables the extension for the target PHP installation. On Unix-like systems, make sure the PHP development tools and compiler toolchain are installed first. On Windows, PIE installs from the pre-built DLL archives published on GitHub releases.

Verify the extension is loaded:

IDE Stubs

Install the optional stubs package in projects that use php-bloom to get IDE completion, parameter hints, return types, and inline docs without requiring the extension to be loaded in the IDE environment:

Build

Load the built module directly:

Run the PHPT suite:

Build and test the extension on Windows:

Quick Start

For correctness-sensitive paths, treat positive results as a pre-check and then verify them against the real source of truth:

API

Functions

Bloom\Filter

Export And Import

Filters can be serialized to a compact binary format and loaded later:

The export format is binary-safe and starts with the BLM1 magic header.

Use Cases

Good fits:

• Suppression lists where most candidates are absent and positives are verified in MySQL, Postgres, Redis, or another authoritative store.
• Deny lists and block lists where negative checks should be very cheap.
• Cache penetration protection, where missing keys should avoid expensive downstream lookups.
• Pre-filtering large streams before doing heavier processing.
• Fast duplicate detection where occasional false positives are acceptable.
• Shipping a compact, read-mostly membership structure with export() and import().

Benchmarks

Benchmark results are workload and machine dependent. The reports below were captured locally on June 13, 2026 with PHP 8.2.30 and extension version 0.1.0.

Extension vs Pure PHP

Command:

Configuration:

• capacity: 100000
• false positive rate: 0.01
• inserts: 100000
• present lookups: 100000
• absent lookups: 100000

Report:

For this run, the filter used 958,506 bits, 7 hash rounds, and 119,814 bytes of bitset storage.

MySQL Suppression Lookup

The MySQL benchmark compares direct indexed lookups against a Bloom pre-check plus MySQL verification. The Bloom-only path is reported as a raw lookup ceiling, but it is not correctness-safe because false positives are possible.

Setup:

Command used for this report:

Configuration:

• MySQL: 8.4.9
• dataset: 100000 deterministic SHA-256 hashes
• checks per mix: 10000
• false positive rate: 0.01
• warmup queries: 100
• filter size: 117.01 KiB
• estimated false positive rate after build: 0.00721217

Report:

The benchmark shows the expected shape: the Bloom pre-check helps most when the traffic is negative-heavy. As the present rate rises, more positive Bloom results must be verified by MySQL, so the benefit narrows.

More benchmark details are in benchmarks/README.md and benchmarks/mysql/README.md.

Development

Regenerate arginfo after changing bloom.stub.php:

Clean generated build output:

Useful layout:

• bloom.c: module entry and procedural functions
• bloom_algo.c: shared hashing and position helpers
• bloom_filter.c: Bloom\Filter object implementation
• bloom.stub.php: public API declarations for arginfo generation
• tests/: PHPT test suite
• benchmarks/: extension and MySQL benchmark suites

License

MIT. See LICENSE.