{"id":16674315,"url":"https://github.com/averias/phpredis-bloom","last_synced_at":"2025-08-25T00:34:50.182Z","repository":{"id":55393003,"uuid":"222575426","full_name":"averias/phpredis-bloom","owner":"averias","description":"PHP client for RedisBloom module","archived":false,"fork":false,"pushed_at":"2021-05-28T10:07:36.000Z","size":230,"stargazers_count":21,"open_issues_count":4,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-23T20:05:37.871Z","etag":null,"topics":["bloom-filter","count-min-sketch","cuckoo-filter","php","redis","redisbloom","top-k"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/averias.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-11-19T00:52:44.000Z","updated_at":"2023-08-21T06:57:59.000Z","dependencies_parsed_at":"2022-08-14T23:20:09.661Z","dependency_job_id":null,"html_url":"https://github.com/averias/phpredis-bloom","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/averias%2Fphpredis-bloom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/averias%2Fphpredis-bloom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/averias%2Fphpredis-bloom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/averias%2Fphpredis-bloom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/averias","download_url":"https://codeload.github.com/averias/phpredis-bloom/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244848521,"owners_count":20520535,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bloom-filter","count-min-sketch","cuckoo-filter","php","redis","redisbloom","top-k"],"created_at":"2024-10-12T12:30:13.674Z","updated_at":"2025-03-21T18:31:22.592Z","avatar_url":"https://github.com/averias.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Test Coverage](https://api.codeclimate.com/v1/badges/63a3119e2bbbd693b63a/test_coverage)](https://codeclimate.com/github/averias/phpredis-bloom/test_coverage)\n[![Maintainability](https://api.codeclimate.com/v1/badges/63a3119e2bbbd693b63a/maintainability)](https://codeclimate.com/github/averias/phpredis-bloom/maintainability)\n[![Build Status](https://travis-ci.org/averias/phpredis-bloom.svg?branch=master)](https://travis-ci.org/averias/phpredis-bloom)\n[![Packagist Version](https://img.shields.io/packagist/v/averias/phpredis-bloom.svg)](https://packagist.org/packages/averias/phpredis-bloom)\n[![GitHub](https://img.shields.io/github/license/averias/phpredis-bloom.svg)](https://github.com/averias/phpredis-bloom)\n\n\u003cimg src=\"docs/PhpRedisBloomLogo250x300.png\" alt=\"PhpRedisBloom\" align=\"right\" /\u003e\n\n# PhpRedisBloom\nPHP client for [RedisLab/RedisBloom Module](https://oss.redislabs.com/redisbloom/), an extension of Redis core for \nprobabilistic data structures.\n\n## Table of content\n\n- [Intro](#intro)\n- [Requirements](#requirements)\n- [Usage](#usage)\n    - [Clients](#clients)\n    - [Items](#items)\n    - [Why having a RedisBloomClient and classes for each RedisBloom data types?](#why-having-a-redisbloomclient-and-classes-for-each-redisbloom-data-types)\n    - [Automatic connection, disconnection and reconnection](#automatic-connection-disconnection-and-reconnection)\n    - [Code Sample](#code-sample)\n- [Commands](#commands)\n    - [PhpRedisBloom commands](#phpredisbloom-commands)\n    - [Phpredis commands](#phpredis-commands)\n    - [Raw commands](#raw-commands)\n- [Tests](#tests)\n    - [On a local Redis server 4.0+ with RedisBloom module and Redis extension 5 installed](#on-a-local-redis-server-40-with-redisbloom-module-and-redis-extension-5-installed)\n    - [Docker](#docker)\n- [Examples](#examples)\n- [License](#license)\n\n## Intro\nPhpRedisBloom provides the full set of commands for `RedisBloom Module` and it's built on top of [phpredis](https://github.com/phpredis/phpredis) \nand use it as Redis client, so you can also take advantage of some of the features included in `phpredis` as Redis client.\n\n## Requirements\n- Redis server 4.0+ version (Redis Modules are only available from Redis 4.0+)\n- RedisBloom Module installed on Redis server as specified in [Building and running](https://oss.redislabs.com/redisbloom/Quick_Start/#building-and-running)\n- PHP 7.2+ with PHP Redis extension 5 installed\n\n## Usage\n\n### Clients\nThere are 2 ways to execute PhpRedisBloom commands:\n\n**Executing commands by using RedisBloomClient**\n\n```php\nuse Averias\\RedisBloom\\Factory\\RedisBloomFactory;\n\n// instantiate a RedisBloomClient from RedisBloomFactory with default connection options\n$factory = new RedisBloomFactory();\n$client = $factory-\u003ecreateClient();\n\n// then you can execute whatever redis bloom command for each of the 4 data types\n$result = $client-\u003ebloomFilterAdd('filter-key', 'item-15');\n\n```\n\n**Executing commands by using RedisBloom data types classes (Bloom Filter, Cuckoo Filter, Count-Min Sketch and Top-K)**\n\n```php\n// example for BloomFilter data types class\nuse Averias\\RedisBloom\\Factory\\RedisBloomFactory;\n\n// instantiate a BloomFilter class from RedisBloomFactory with default connection options\n$factory = new RedisBloomFactory();\n$bloomFilter = $factory-\u003ecreateBloomFilter('filter-key');\n\n// then you can execute whatever Bloom Filter command on 'filter-key' filter\n// adding one item to Bloom Filter 'filter-key'\n$result = $bloomFilter-\u003eadd('item1'); // returns true\n\n// adding 2 items more to Bloom Filter 'filter-key'\n$result = $bloomFilter-\u003emultiAdd('item2', 15); // returns and array [true, true]\n\n// checking if item 'item1' exists in 'filter-key' Bloom Filter\n$result = $bloomFilter-\u003eexists('item1'); // returns true\n\n// adding one item more\n$result = $bloomFilter-\u003eadd(17.2); // returns true\n\n// checking if a list items exist in 'filter-key' Bloom Filter\n$result = $bloomFilter-\u003emultiExists('item1', 15, 'foo'); // returns and array [true, true, false] since 'foo' doesn't exists \n```\n\n\n### Items\nThe only allowed item values to add or insert in the 4 data structure are string, integers, and float, but notice \nthat all items are stored as strings, so adding the integer 13 or the string `13` will end in the same result.\nFor those data structures that allow inserting repeated items (like Cuckoo Filter) it will increase the count of that \nitem or will fail in the second insertion in case of structures that do not allow inserting repeated items.\n\nSame behavior for floats, inserting first a float like 17.2 and then insert its representation as string `17.2` will \nthrow an exception in the second insertion in Bloom Filters which doesn't allow repeated items and in case of other \nstructures like Cuckoo Filter, Count-Min Sketch and Top-k will increase the counter to 2 after the second insertion.\n\nYou can take a look to [examples/inserting-numbers.php](https://github.com/averias/phpredis-bloom/blob/master/examples/inserting-numbers.php) \nto see an example of this behavior.\n\n\n### Why having a RedisBloomClient and classes for each RedisBloom data types?\n\n- RedisBloomClient allows you execute whatever RedisBloom command (Bloom Filter, Cuckoo Filter, Mins-Sketch and Top-K \ncommands) over different filters and also to execute Redis commands and raw Redis commands. So it is a client for general \npurposes and it is recommended when you need to manage different filters and keys or even when you want to execute \nnormal Redis commands\n- RedisBloom data types classes (Bloom Filter, Cuckoo Filter, Mins-Sketch and Top-K classes) just execute commands \nthat belongs to that data type and over just one filter. They are useful when you need to manage just one filter. \n\n\n### Automatic connection, disconnection and reconnection\n\nRedisBloomClient and Redis Bloom data types automatically connect Redis after creation, you can disconnect them from the \nRedis instance by calling its `disconnect` method:\n\n`$client-\u003edisconnect()`\n\nor \n\n`$bloomFilter-\u003edisconnect()`\n\nwhich will return true or false depending on the disconnection was possible.\n\nAfter one successful disconnection the client or data type object will reconnect automatically if you reuse the object \nfor sending more commands (see example below) \n\n\n### Code Sample\n\nThe following code snippet show how to instantiate RedisBloom clients and BloomFilter data type with different \nconnection configurations\n \n```php\n\u003c?php\n\nuse Averias\\RedisBloom\\Enum\\Connection;\nuse Averias\\RedisBloom\\Factory\\RedisBloomFactory;\n\nrequire(dirname(__DIR__).'/vendor/autoload.php');\n\nconst EXAMPLE_FILTER = 'example-filter';\n\n/**\n * Default connection params:\n * [\n *     'host' =\u003e '127.0.0.1',\n *     'port' =\u003e 6379,\n *     'timeout' =\u003e 0.0, // seconds\n *     'retryInterval' =\u003e 15 // milliseconds\n *     'readTimeout' =\u003e 2, // seconds\n *     'persistenceId' =\u003e null // string for persistent connections, null for no persistent ones\n *     'database' =\u003e 0 // Redis database index [0..15]\n * ]\n *\n * you can create a factory with default connection by not passing any param in the constructor\n * $defaultFactory = new RedisBloomFactory();\n */\n\n// create a factory with default connection but pointing to database 15\n$factoryDB15 = new RedisBloomFactory([Connection::DATABASE =\u003e 15]);\n\n// it creates a RedisBloomClient with same default connection configuration as specified in factory above\n$clientDB15 = $factoryDB15-\u003ecreateClient();\n\n// using the same factory you can create a BloomFilter object pointing \n// to database 14 and filter name = 'example-filter'\n$bloomFilterDB14 = $factoryDB15-\u003ecreateBloomFilter(EXAMPLE_FILTER, [Connection::DATABASE =\u003e 14]);\n\n// add 'item-15' to 'example-filter' bloom filter on database 15\n$clientDB15-\u003ebloomFilterAdd(EXAMPLE_FILTER, 'item-15');\n\n// add 'item-14' to 'example-filter' bloom filter on database 14\n$bloomFilterDB14-\u003eadd('item-14');\n\n// disconnect\n$bloomFilterDB14-\u003edisconnect();\n\n// create another RedisBloomClient pointing to database 14\n$clientDB14 = $factoryDB15-\u003ecreateClient([Connection::DATABASE =\u003e 14]);\n\n$result = $clientDB15-\u003ebloomFilterExists(EXAMPLE_FILTER, 'database15'); //true\n$result = $clientDB15-\u003ebloomFilterExists(EXAMPLE_FILTER, 'database14'); // false\n\n$result = $clientDB14-\u003ebloomFilterExists(EXAMPLE_FILTER, 'database15'); // false\n$result = $clientDB14-\u003ebloomFilterExists(EXAMPLE_FILTER, 'database14'); // true\n\n// delete bloom filter on database 15\n$clientDB15-\u003eexecuteRawCommand('DEL', EXAMPLE_FILTER);\n\n// delete bloom filter on database 14\n$clientDB14-\u003edel(EXAMPLE_FILTER);\n\n// disconnect\n\n$clientDB15-\u003edisconnect();\n$clientDB14-\u003edisconnect();\n\n// automatic reconnection\n$bloomFilterDB14-\u003eadd('reconnected');\n$exist = $bloomFilterDB14-\u003eexists('reconnected'); //true\n$bloomFilterDB14-\u003edisconnect();\n\n```\n\n## Commands\n#### PhpRedisBloom commands\n\nPhpredis-bloom provides all the commands for the four RedisBloom data types, please follow the links below for a \ndetailed info for each one:\n\n- [Bloom Filter](https://github.com/averias/phpredis-bloom/blob/master/docs/BLOOM-FILTER-COMMANDS.md)\n- [Cuckoo Filter](https://github.com/averias/phpredis-bloom/blob/master/docs/CUCKOO-FILTER-COMMANDS.md)\n- [Count-Min-Sketch](https://github.com/averias/phpredis-bloom/blob/master/docs/COUNT-MIN-SKETCH-COMMANDS.md)\n- [Top-K](https://github.com/averias/phpredis-bloom/blob/master/docs/TOP-K-COMMANDS.md)\n\n#### Phpredis commands\n\nYou can send Redis commands as specified in [phpredis documentation](https://github.com/phpredis/phpredis#table-of-contents)\n\n#### Raw commands\nYou can send whatever you want to Redis by using `RedisBloomClient::executeRawCommand`:\n\n```php\nuse Averias\\RedisBloom\\Enum\\BloomCommands;\n\n// raw Redis Bloom command\n$client-\u003eexecuteRawCommand(BloomCommands::BF_ADD, 'filter-name', 'value');\n\n// raw Redis command\n$client-\u003eexecuteRawCommand('hget', 'hash-key', 'foo');\n``` \n\n## Tests\n### On a local Redis server 4.0+ with RedisBloom module and Redis extension 5 installed\nFrom console run the following command from the root directory of this project:\n\n`./vendor/bin/phpunit`\n\nif you don't have configured your local Redis server in 127.0.0.1:6379 you can set REDIS_TEST_SERVER, REDIS_TEST_PORT \nand REDIS_TEST_DATABASE in `./phpunit.xml` file with your local Redis host, port and database before running the above \ncommand.\n  \n### Docker\nHaving Docker installed, run the following command in the root directory of this project:\n\n`bash run-tests-docker.sh`\n\nby running the above bash script, two docker services will be built, one with PHP 7.2 with xdebug and redis extensions\nenabled and another with the image of `redislab\\rebloom:2.0.3` (Redis server 5 with RedisBloom module installed). \nThen the tests will run inside `phpredis-bloom` docker service container and finally both container will be stopped.\n\n## Examples\n- [Factory](https://github.com/averias/phpredis-bloom/blob/master/examples/factory.php)\n- [BF copy](https://github.com/averias/phpredis-bloom/blob/master/examples/bloom-filter-copy.php)\n- [CMS increment](https://github.com/averias/phpredis-bloom/blob/master/examples/count-min-sketch-increment-by.php)\n- [CMS Merge](https://github.com/averias/phpredis-bloom/blob/master/examples/count-min-sketch-merge.php)\n\n## License\nPhpRedisBloom code is distributed under MIT license, see [LICENSE](https://github.com/averias/phpredis-bloom/blob/master/LICENSE) \nfile\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faverias%2Fphpredis-bloom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faverias%2Fphpredis-bloom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faverias%2Fphpredis-bloom/lists"}