Probabilistic Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package, so start by confirming how much of it you can use unchanged in a Laravel app.

1. composer require the bundle (and its pouya1364/probabilistic-php dependency).
2. Read the bundle's DependencyInjection/Configuration.php and *Extension.php first — that is the authoritative list of supported config keys and the only real "docs" at v0.1.0.
3. Locate two classes before writing any code: the ProbabilisticRegistry (your entry point for named instances) and the per-instance autowired service classes (the typed wrappers for each filter/sketch type).
4. Translate the bundle's YAML tree into config/probabilistic.php and register the registry as a singleton in AppServiceProvider (see Gotchas — Symfony autowiring will not happen for you).
5. First use case: a Bloom filter for cheap negative lookups, e.g. "has this email already been invited?" — check the filter before hitting the database, accept the small false-positive rate, never treat a hit as proof.

First working call should look roughly like: resolve the registry, get('name') (or inject the specific instance service), then add()/has() on a Bloom, or add()/count() on a HyperLogLog. Verify with the probabilistic:list console command (via php bin/console, or register it as an Artisan command if you want artisan probabilistic:list).

Implementation Patterns

Name instances by purpose, not by type. Config-driven naming is the whole value proposition:

signup_email_bloom      -> BloomFilter
invite_dedup_bloom      -> BloomFilter
daily_unique_visitors   -> HyperLogLog
top_products_sketch     -> CountMinSketch
session_dedup_cuckoo    -> CuckooFilter

One instance per bounded use case keeps sizing and error rates honest and makes probabilistic:list a useful inventory of your probabilistic state.

Prefer the registry for dynamic access, typed services for fixed dependencies. Use ProbabilisticRegistry when the instance name is a variable (tenant ID, per-plan config); inject the concrete per-instance service when a class always needs the same filter — it keeps signatures explicit and testable.

Wrap it in your own thin service. Do not let ProbabilisticRegistry leak across your codebase. A single App\Support\Probabilistic wrapper (or a facade) gives you one place to swap the Symfony-coupled implementation, add logging, and stub it in tests.

Integrate at the edges of the request lifecycle:

• Middleware: dedup keys before controller dispatch.
• Form requests / validators: Bloom check as a fast reject only.
• Jobs and listeners: HyperLogLog add() for analytics counters instead of INSERT ... ON CONFLICT.
• Scheduled commands: reset/rotate sketches on your own cadence — the package will not rotate them for you.

Environment-sized config. Bloom filter size and hash count, HLL precision, and Count-Min width/depth belong in config with conservative defaults in config/probabilistic.php, overridable per environment. Treat these as capacity planning, not tuning knobs — changing them invalidates existing state.

Test against a real instance, not a mock. Mocks of a Bloom filter will lie to you about false positives. Build a tiny helper that constructs a fresh in-memory instance per test and assert on behavior ("rejects definitely-absent key"), not exact internals.

Gotchas and Tips

• Symfony bundle ≠ Laravel package. There is no ProbabilisticServiceProvider, no facade, no publishable config in a Laravel sense. Expect to write a binding yourself and to copy the config tree rather than vendor:publish it.
• Autowiring does not carry over. "Per-instance autowired services" works in Symfony's container. In Laravel you either hand-bind each named instance behind an interface, or go through the registry. Budget for this; it is the main integration cost.
• State is almost certainly not persisted for you. Bloom/Cuckoo/Count-Min/HLL are in-memory data structures. If the registry is rebuilt per request, your filter resets every request and the package becomes decorative. You need a deliberate strategy — long-running worker (Octane/queue worker), Redis-backed storage, or periodic snapshot/restore. Check probabilistic-php for whether serialization helpers exist; if not, serialize the raw structure yourself and watch size.
• A hit is a maybe; a miss is a no. For Bloom filters, has() === false is authoritative, true is not. Never gate a refund, a delete, or a security check on a positive. Cuckoo filters have the same property plus possible insertion failure — handle the failure path rather than assuming add() always succeeds.
• Counting Bloom counters overflow. Counter width is fixed; popular keys can saturate and then behave like a plain Bloom filter. Same class of problem for Count-Min sketches, which only ever overestimate. Both are fine for "approximately top-N," wrong for billing.
• HLL precision is a one-way door. Precision determines memory and standard error, and you cannot merge sketches built with different precision. Pin it in config and treat changes as a migration.
• Hash stability across deploys. Filter contents are only meaningful under the same hash function and seed. Rolling back code or changing the seed invalidates persisted state — version your snapshots or accept a cold start.
• Debugging: probabilistic:list is your first tool to confirm which instances actually got registered — a typo'd name fails at lookup time, not at boot. For Laravel, register it as an Artisan command early; otherwise you are SSH-ing into bin/console.
• v0.1.0 means unstable. Config key names, service IDs, and constructor signatures can move in a 0.x minor. Pin the version in composer.json, and keep the Symfony-specific surface confined to your one wrapper class so an upstream API change is a single-file fix.
• Extension point to watch: if you need persistence or a Redis-backed store, the registry (or the bundle extension) is the seam to subclass or decorate — not the individual filter classes.