Skip to content

Commit e3ecc8f

Browse files
averiasaverias
committed
finished documentation for Bloom Filters and some refactoring
1 parent 10a7d39 commit e3ecc8f

File tree

75 files changed

+1840
-117
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

75 files changed

+1840
-117
lines changed

‎README.md

+170
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Phpredis-Bloom
2+
RedisBloom for PHP
3+
4+
## Intro
5+
Phpredis-Bloom provides the full set of commands for [RedisBloom Module](https://oss.redislabs.com/redisbloom/).
6+
It's built on top of the [phpredis](https://github.com/phpredis/phpredis) and use it as Redis client,
7+
so you can also take advantage of some of the features included in `phpredis` as Redis client.
8+
9+
## Requirements
10+
- Redis server 4.0+ version (Redis Modules are only available from Redis 4.0+)
11+
- RedisBloom Module installed on Redis server as specified in [Building and running](https://oss.redislabs.com/redisbloom/Quick_Start/#building-and-running)
12+
- PHP 7.2+ with PHP Redis extension 5 installed
13+
14+
## Usage
15+
16+
There are 2 ways to execute Phpredis-bloom commands:
17+
18+
`Executing commands by using RedisBloomClient`
19+
```
20+
use Averias\RedisBloom\Factory\RedisBloomFactory;
21+
22+
// instantiate a RedisBloomClient from RedisBloomFactory with default connection options
23+
$factory = new RedisBloomFactory();
24+
$client = $factory->createClient();
25+
26+
// then you can execute whatever redis bloom command for each of the 4 data types
27+
$result = $client->bloomFilterAdd('filter-key', 'item-15');
28+
29+
```
30+
31+
`Executing Bloom Filter commands by using BloomFilter datatype`
32+
33+
```
34+
use Averias\RedisBloom\Factory\RedisBloomFactory;
35+
36+
// instantiate a BloomFilter class from RedisBloomFactory with default connection options
37+
$factory = new RedisBloomFactory();
38+
$bloomFilter = $factory->createBloomFilter('filter-key');
39+
40+
// then you can execute whatever Bloom Filter command on 'filter-key' filter
41+
// adding one item to Bloom Filter 'filter-key'
42+
$result = $bloomFilter->add('item1'); // returns true
43+
44+
// adding 2 items more to Bloom Filter 'filter-key'
45+
$result = $bloomFilter->multiAdd('item2', 15); // returns and array [true, true]
46+
47+
// checking if item 'item1' exists in 'filter-key' Bloom Filter
48+
$result = $bloomFilter->exists('item1'); // returns true
49+
50+
// adding one item more
51+
$result = $bloomFilter->add(17.2); // returns true
52+
53+
// checking if a list items exist in 'filter-key' Bloom Filter
54+
$result = $bloomFilter->multiExists('item1', 15, 'foo'); // returns and array [true, true, false] since 'foo' doesn't exists
55+
```
56+
57+
### Example
58+
59+
The following code snippet show how to instantiate RedisBloom clients and BloomFilter data type with different
60+
connection configurations
61+
62+
```
63+
<?php
64+
65+
use Averias\RedisBloom\Enum\Connection;
66+
use Averias\RedisBloom\Factory\RedisBloomFactory;
67+
68+
require(dirname(__DIR__).'/vendor/autoload.php');
69+
70+
const EXAMPLE_FILTER = 'example-filter';
71+
72+
/**
73+
* Default connection params:
74+
* [
75+
* 'host' => '127.0.0.1',
76+
* 'port' => 6379,
77+
* 'timeout' => 0.0, // seconds
78+
* 'retryInterval' => 15 // milliseconds
79+
* 'readTimeout' => 2, // seconds
80+
* 'persistenceId' => null // string for persistent connections, null for no persistent ones
81+
* 'database' => 0 // Redis database index [0..15]
82+
* ]
83+
*
84+
* you can create a factory with default connection configuration by not passing any param in the constructor
85+
* $defaultFactory = new RedisBloomFactory();
86+
*/
87+
88+
// create a factory with default connection configuration but pointing to database 15
89+
$factoryDB15 = new RedisBloomFactory([Connection::DATABASE => 15]);
90+
91+
// it creates a RedisBloomClient with same default connection configuration as specified in factory above
92+
$clientDB15 = $factoryDB15->createClient();
93+
94+
// using the same factory you can create a BloomFilter object pointing to database 14 and filter name = 'example-filter'
95+
$bloomFilterDB14 = $factoryDB15->createBloomFilter(EXAMPLE_FILTER, [Connection::DATABASE => 14]);
96+
97+
// add 'item-15' to 'example-filter' bloom filter on database 15
98+
$clientDB15->bloomFilterAdd(EXAMPLE_FILTER, 'item-15');
99+
100+
// add 'item-14' to 'example-filter' bloom filter on database 14
101+
$bloomFilterDB14->add('item-14');
102+
103+
// create another RedisBloomClient pointing to database 14
104+
$clientDB14 = $factoryDB15->createClient([Connection::DATABASE => 14]);
105+
106+
$result = $clientDB15->bloomFilterExists(EXAMPLE_FILTER, 'database15'); //true
107+
$result = $clientDB15->bloomFilterExists(EXAMPLE_FILTER, 'database14'); // false
108+
109+
$result = $clientDB14->bloomFilterExists(EXAMPLE_FILTER, 'database15'); // false
110+
$result = $clientDB14->bloomFilterExists(EXAMPLE_FILTER, 'database14'); // true
111+
112+
// delete bloom filter on database 15
113+
$clientDB15->executeRawCommand('DEL', EXAMPLE_FILTER);
114+
115+
// delete bloom filter on database 14
116+
$clientDB14->del(EXAMPLE_FILTER);
117+
118+
```
119+
120+
## Commands
121+
#### Phpredis-Bloom commands
122+
123+
Phpredis-bloom provides all the commands for the four RedisBloom data types, please follow the links below for a
124+
detailed info for each one:
125+
126+
- [Bloom Filter](https://github.com/averias/phpredis-bloom/blob/master/docs/BLOOM-FILTER-COMMANDS.md)
127+
- Cuckoo Filter (still under development)
128+
- Mins-Sketch (still under development)
129+
- Top-K (still under development)
130+
131+
#### Phpredis commands
132+
133+
You can send Redis commands as specified in [phpredis documentation](https://github.com/phpredis/phpredis#table-of-contents)
134+
135+
#### Raw commands
136+
You can send whatever you want to Redis by using `RedisBloomClient::executeRawCommand`:
137+
```
138+
// raw Redis Bloom command
139+
$client->executeRawCommand(BloomCommands::BF_ADD, 'filter-name', 'value');
140+
141+
// raw Redis command
142+
$client->executeRawCommand('hget, 'hash-key', 'foo');
143+
```
144+
145+
## Tests
146+
#### On a local Redis server 4.0+ with RedisBloom module and Redis extension 5 installed
147+
From console run the following command from the root directory of this project:
148+
149+
`./vendor/bin/phpunit`
150+
151+
if you don't have configured your local Redis server in 127.0.0.1:6379 you can set REDIS_TEST_SERVER, REDIS_TEST_PORT
152+
and REDIS_TEST_DATABASE in `./phpunit.xml` file with your local Redis host, port and database before running the above
153+
command.
154+
155+
#### Docker
156+
Having Docker installed, run the following command in the root directory of this project:
157+
158+
`bash run-tests-docker.sh`
159+
160+
by running the above bash script, two docker services will be built, one with PHP 7.2 with xdebug and redis extensions
161+
enabled and another with the image of `redislab\rebloom:2.0.3` (Redis server 5 with RedisBloom module installed).
162+
Then the tests will run inside `phpredis-bloom` docker service container and finally both container will be stopped.
163+
164+
## Examples
165+
- [Factory](https://github.com/averias/phpredis-bloom/blob/master/examples/factory.php)
166+
- [Scan](https://github.com/averias/phpredis-bloom/blob/master/examples/scan.php)
167+
168+
## License
169+
Phpredis-Bloom code is distributed under MIT license, see [LICENSE](https://github.com/averias/phpredis-bloom/blob/master/LICENSE)
170+
file

‎docker-compose.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,6 @@ services:
88
context: .
99
volumes:
1010
- .:/app
11-
redisjson:
11+
redisbloom:
1212
container_name: redislab-rebloom
1313
image: redislabs/rebloom:2.0.3

‎docker-tests/docker-containers.sh

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
#!/bin/sh
2+
3+
yel=$'\e[1;33m'
4+
end=$'\e[0m'
5+
6+
docker-compose up --build -d
7+
docker exec -i phpredis-bloom bash < ./docker-tests/docker-tests.sh
8+
printf "\n${yel}*** Stopping containers... ***${end}\n\n"
9+
docker stop redislab-rebloom
10+
docker stop phpredis-bloom

‎docker-tests/docker-tests.sh

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#!/bin/sh
2+
3+
blu=$'\e[1;34m'
4+
end=$'\e[0m'
5+
6+
printf "\n${blu}*** Running test against Redis 5 + RedisBloom module docker service ***${end}\n\n"
7+
./vendor/bin/phpunit --configuration ./docker-tests/phpunit_docker.xml

‎docker-tests/phpunit_docker.xml

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<phpunit backupGlobals="false"
3+
backupStaticAttributes="false"
4+
bootstrap="../vendor/autoload.php"
5+
colors="true"
6+
convertErrorsToExceptions="true"
7+
convertNoticesToExceptions="true"
8+
convertWarningsToExceptions="true"
9+
processIsolation="false"
10+
stopOnError="true"
11+
stopOnFailure="true"
12+
verbose="true"
13+
>
14+
<testsuites>
15+
<testsuite name="PHP RedisBloom Integration Tests">
16+
<directory suffix="Test.php" >../tests/Integration/</directory>
17+
</testsuite>
18+
<testsuite name="PHP RedisBloom Unit Tests">
19+
<directory suffix="Test.php">../tests/Unit</directory>
20+
</testsuite>
21+
</testsuites>
22+
<filter>
23+
<whitelist processUncoveredFilesFromWhitelist="true">
24+
<directory suffix=".php">../src/</directory>
25+
<exclude>
26+
<directory>../src/RedisBloomClient/Exception</directory>
27+
<directory>../src/RedisBloomClient/Enum</directory>
28+
<directory suffix="Interface.php">./src/</directory>
29+
</exclude>
30+
</whitelist>
31+
</filter>
32+
<logging>
33+
<log type="coverage-html" target="../build/coverage" />
34+
</logging>
35+
<php>
36+
<const name="REDIS_TEST_SERVER" value="redislab-rebloom" />
37+
<const name="REDIS_TEST_PORT" value="6379" />
38+
<const name="REDIS_TEST_DATABASE" value="15" />
39+
</php>
40+
</phpunit>

0 commit comments

Comments
 (0)