PHPackages                             iperamuna/laravel-redis-bloom - 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. iperamuna/laravel-redis-bloom

ActiveLibrary[Caching](/categories/caching)

iperamuna/laravel-redis-bloom
=============================

RedisBloom wrapper with auto-rotation, diagnostics, and metrics for Laravel

v1.0.0(1mo ago)01↓100%MITPHPPHP ^8.2CI passing

Since Apr 29Pushed 1mo agoCompare

[ Source](https://github.com/iperamuna/laravel-redis-bloom)[ Packagist](https://packagist.org/packages/iperamuna/laravel-redis-bloom)[ Docs](https://github.com/iperamuna/laravel-redis-bloom)[ RSS](/packages/iperamuna-laravel-redis-bloom/feed)WikiDiscussions main Synced 1w ago

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

Laravel Redis Bloom
===================

[](#laravel-redis-bloom)

 [![Laravel Redis Bloom Banner](https://raw.githubusercontent.com/iperamuna/laravel-redis-bloom/main/art/banner.png)](https://raw.githubusercontent.com/iperamuna/laravel-redis-bloom/main/art/banner.png)

[![Latest Version on Packagist](https://camo.githubusercontent.com/7d50b2367c52f1b715c22fc6e254ff7b53a1e5a0100554e9ed1b9bbc6242fe2c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f69706572616d756e612f6c61726176656c2d72656469732d626c6f6f6d2e7376673f7374796c653d666f722d7468652d626164676526636f6c6f723d626c7565)](https://packagist.org/packages/iperamuna/laravel-redis-bloom)[![Total Downloads](https://camo.githubusercontent.com/dba0d4a74b8b23ee11c02b9e2018b282a3a260a1a918836db7604a5c28fb55bc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f69706572616d756e612f6c61726176656c2d72656469732d626c6f6f6d2e7376673f7374796c653d666f722d7468652d626164676526636f6c6f723d677265656e)](https://packagist.org/packages/iperamuna/laravel-redis-bloom)[![Software License](https://camo.githubusercontent.com/9897f4467850972a38c7db9a4d38280b8fcdac0ada00e9c8c0a72ecfa8551653/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666f722d7468652d6261646765)](LICENSE)[![Build Status](https://camo.githubusercontent.com/a7be0183be05486ec8461757a059905becdee6cec6f9866b6f51faf9ef63353c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f69706572616d756e612f6c61726176656c2d72656469732d626c6f6f6d2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e267374796c653d666f722d7468652d6261646765)](https://github.com/iperamuna/laravel-redis-bloom/actions)[![Laravel Compatibility](https://camo.githubusercontent.com/e57b1508a878882cd32b051d0c523704d335a1e353fdc6d657cf44b7a67fcbf1/68747470733a2f2f62616467652e6c61726176656c2e636c6f75642f62616467652f69706572616d756e612f6c61726176656c2d72656469732d626c6f6f6d3f7374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/iperamuna/laravel-redis-bloom)

**Laravel Redis Bloom** is an industrial-grade probabilistic infrastructure layer for Laravel. It provides a highly optimized, developer-friendly wrapper around the RedisBloom module, enabling sub-millisecond membership checks at massive scale with near-zero memory overhead.

Whether you are deduplicating billion-row datasets, protecting signup APIs from spam, or implementing high-speed caching logic, this package provides the tools to do it with confidence.

---

🧐 The Problem: Scaling Membership Checks
----------------------------------------

[](#-the-problem-scaling-membership-checks)

As your data grows, checking if a value (like an email, IP, or ID) already exists becomes an expensive operation. Traditional approaches hit a wall:

- **Database Lookups**: Querying a 100M+ row table for every request introduces latency and puts massive pressure on your primary database.
- **In-Memory Sets (Redis Sets/Hashes)**: Storing millions of unique strings in Redis consumes significant RAM, leading to high infrastructure costs and "Out of Memory" crashes.
- **The "Exists" Bottleneck**: In high-traffic systems (API protection, deduplication, scrapers), you need a way to say **"No, this definitely doesn't exist"** in constant time without wasting memory.

🧠 The Solution: Probabilistic Efficiency
----------------------------------------

[](#-the-solution-probabilistic-efficiency)

**Laravel Redis Bloom** leverages Bloom Filters—a probabilistic data structure that is incredibly space-efficient.

- **Near-Zero Memory**: You can track 1 million items with less than 2MB of RAM.
- **Sub-Millisecond Speed**: Checks are performed in $O(k)$ time (where $k$ is the number of hash functions), independent of the number of items stored.
- **The Guarantee**: A Bloom filter can tell you with **100% certainty** if an item is *not* in the set. If it says it *is* in the set, there is a tiny, configurable chance of a false positive—which is where our built-in **Truth Verification** comes in.

---

🔥 Key Architectural Features
----------------------------

[](#-key-architectural-features)

- 🚀 **Native RedisBloom Power**: First-class support for `BF.ADD`, `BF.EXISTS`, and `BF.RESERVE` commands.
- 🔄 **Intelligent Auto-Rotation**: Never worry about capacity again. The system automatically version-controls and rotates filters when full, ensuring continuous availability.
- 📊 **Observability & Metrics**: Built-in tracking for hits, misses, and false-positive rates to fine-tune your probabilistic models.
- 🩺 **System Diagnostics**: A comprehensive `bloom:doctor` command that analyzes your OS, Redis version, and Bloom module status to provide actionable fixes.
- 📦 **Bulk Ingestion Engine**: High-speed Artisan command to hydrate Bloom filters from your existing database tables using chunked processing.
- 🛡️ **Defensive Guard Logic**: Graceful fallbacks and OS-aware error messages that guide you through setup on macOS, Linux, or Windows.
- 🧩 **Laravel Native Integration**: Includes custom Validation Rules, Route Middleware, and a Filament Dashboard widget out of the box.

---

🛠 Installation
--------------

[](#-installation)

### 1. Requirements

[](#1-requirements)

- **PHP**: 8.2 or higher
- **Laravel**: 11.x, 12.x, or 13.x
- **Redis**: 4.0+ with the [RedisBloom module](https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/) installed.

### 2. Composer

[](#2-composer)

```
composer require iperamuna/laravel-redis-bloom
```

### 3. Publish Configuration

[](#3-publish-configuration)

```
php artisan vendor:publish --tag=bloom-config
```

### 4. Run System Check

[](#4-run-system-check)

```
php artisan bloom:doctor
```

---

⚙️ Configuration
----------------

[](#️-configuration)

Define your specialized filters in `config/bloom.php`. You can tune the error rate and capacity per filter if needed, or use the global defaults.

```
return [
    'error_rate' => 0.001, // 0.1% false positive rate
    'capacity'   => 1000000, // Initial capacity of 1 million items
    'redis_connection' => 'default', // Redis connection name from database.php

    'filters' => [
        'emails' => 'bf:users:emails',
        'ips'    => 'bf:security:blocked_ips',
        'phones' => 'bf:customers:phones',
    ],

    'rotation_keep_versions' => 3, // Keep last 3 rotated versions for safety
];
```

Tip

**Automatic Prefixing**: This package automatically detects and honors the `prefix` defined in your `config/database.php`. Your Bloom keys will be correctly namespaced (e.g., `laravel_database_bf:emails`).

---

🚀 Advanced Usage
----------------

[](#-advanced-usage)

### 🧠 The Fluent API

[](#-the-fluent-api)

The `Bloom` facade provides a clean, chainable interface for interacting with your filters.

```
use Iperamuna\LaravelRedisBloom\Facades\Bloom;

// Single entry ingestion
Bloom::filter('emails')->add('founder@example.com');

// High-speed membership check
if (Bloom::filter('emails')->exists('founder@example.com')) {
    // This value probably exists (Probabilistic result)
}

// Bulk ingestion (Pipelined for performance)
Bloom::filter('ips')->addMany([
    '127.0.0.1',
    '192.168.1.1',
    '10.0.0.1'
]);
```

### 🛡️ Smart Validation (Truth Verification)

[](#️-smart-validation-truth-verification)

Bloom filters are probabilistic. While a `false` result is 100% certain, a `true` result is "probably exists." We provide a `check` method to handle the "truth" verification via a fallback closure.

```
// Check Bloom first, then verify against the database only if Bloom says "maybe"
$exists = Bloom::filter('emails')->check($email, function ($email) {
    return \App\Models\User::where('email', $email)->exists();
});
```

### ✅ Clean Laravel Validation

[](#-clean-laravel-validation)

Use the custom rule in your Form Requests or controllers for ultra-fast duplicate detection.

```
use Iperamuna\LaravelRedisBloom\Rules\BloomRule;

$request->validate([
    // Standard mode: Fails if Bloom says "maybe exists"
    'email' => ['required', 'email', new BloomRule('emails')],

    // Strict mode: Fail immediately with specific "Bloom detected" message
    'phone' => ['required', new BloomRule('phones', strict: true)],

    // String syntax support
    'ip' => 'required|bloom:ips',
]);
```

### 🚦 API Guard Middleware

[](#-api-guard-middleware)

Protect your high-traffic endpoints from duplicate submissions or known spam entries without hitting your database.

```
// Route definition
Route::middleware('bloom:ips,ip_address')->post('/api/report', ...);
```

---

🧰 Management & Monitoring
-----------------------------

[](#-management--monitoring)

### 🩺 System Diagnostics (The Doctor)

[](#-system-diagnostics-the-doctor)

Setup can be tricky. Our doctor analyzes your environment and gives you the exact commands to run for your specific OS.

```
php artisan bloom:doctor
```

### 📈 Real-time Statistics

[](#-real-time-statistics)

Monitor the health and efficiency of your filters.

```
php artisan bloom:stats emails
```

### 📥 Bulk Hydration

[](#-bulk-hydration)

Hydrate a new Bloom filter from your existing production data in seconds.

```
# Ingest all user emails into the 'emails' filter
php artisan bloom:fill emails "App\Models\User" email --chunk=5000
```

---

🧪 Testing
---------

[](#-testing)

We use [Pest](https://pestphp.com/) to ensure 100% reliability of the core rotation and metrics logic.

```
composer test
```

📄 License
---------

[](#-license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

✨ Credits
---------

[](#-credits)

Developed with ❤️ by [Indunil Peramuna](https://iperamuna.com). Check out my [GitHub](https://github.com/iperamuna) for more high-performance Laravel tools.

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance91

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

Unknown

Total

1

Last Release

41d ago

### Community

Maintainers

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

---

Top Contributors

[![iperamuna](https://avatars.githubusercontent.com/u/3013395?v=4)](https://github.com/iperamuna "iperamuna (14 commits)")

---

Tags

laravelredisbloomprobabilisticredisbloom

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/iperamuna-laravel-redis-bloom/health.svg)

```
[![Health](https://phpackages.com/badges/iperamuna-laravel-redis-bloom/health.svg)](https://phpackages.com/packages/iperamuna-laravel-redis-bloom)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3325.1M337](/packages/psalm-plugin-laravel)[spatie/laravel-responsecache

Speed up a Laravel application by caching the entire response

2.8k8.7M64](/packages/spatie-laravel-responsecache)[propaganistas/laravel-disposable-email

Disposable email validator

6012.9M7](/packages/propaganistas-laravel-disposable-email)[awssat/laravel-visits

Laravel Redis visits counter for Eloquent models

975169.8k2](/packages/awssat-laravel-visits)[api-platform/laravel

API Platform support for Laravel

59156.3k10](/packages/api-platform-laravel)[namoshek/laravel-redis-sentinel

An extension of Laravels Redis driver which supports connecting to a Redis master through Redis Sentinel.

39764.5k](/packages/namoshek-laravel-redis-sentinel)

PHPackages © 2026

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