PHPackages                             macfja/redisearch-integration - 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. macfja/redisearch-integration

ActiveLibrary[Caching](/categories/caching)

macfja/redisearch-integration
=============================

Helper tools to integrate RediSearch in PHP project

2.0.0(4y ago)021.9k↓26.9%[2 issues](https://github.com/MacFJA/php-redisearch-integration/issues)[1 PRs](https://github.com/MacFJA/php-redisearch-integration/pulls)MITPHPPHP ^7.2 || ^8.0

Since Jan 24Pushed 4y ago1 watchersCompare

[ Source](https://github.com/MacFJA/php-redisearch-integration)[ Packagist](https://packagist.org/packages/macfja/redisearch-integration)[ RSS](/packages/macfja-redisearch-integration/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (17)Versions (5)Used By (0)

PHP RediSearch Integration
==========================

[](#php-redisearch-integration)

[MacFJA/redisearch-integration](https://packagist.org/packages/macfja/redisearch-integration) is a small library to ease usage of [MacFJA/redisearch](https://packagist.org/packages/macfja/redisearch) which is a RediSearch client.

Installation
------------

[](#installation)

```
composer require macfja/redisearch-integration

```

Usage
-----

[](#usage)

You will mainly use `ObjectManager` (`\MacFJA\RediSearch\Integration\ObjectManager`) and `ObjectRepository` (`\MacFJA\RediSearch\Integration\ObjectRepository`).

This 2 interfaces are bundle into the `ObjectWorker` (`\MacFJA\RediSearch\Integration\ObkectWorker`) class, to ease usage. *(If you are using a good Injection dependency, you will only need the interface)*

```
use MacFJA\RediSearch\Integration\CompositeProvider;
use MacFJA\RediSearch\Integration\ObjectWorker;
use MacFJA\RediSearch\Redis\Client\ClientFacade;

$jsonProvider = new JsonProvider();
$jsonProvider->addJson(__DIR__.'/mappings.json');
$provider = new CompositeProvider(); // Annotation, Attribute, class implementation
$provider->addProvider($jsonProvider); // Add JSON as provider source

$client = (new ClientFacade())->getClient(/* .. */);

$manager = new ObjectWorker($client, $provider);
// ...
$manager->createIndex(\MyApp\Model\Product::class);
// $manager->flush(); If you need the index to create directly
// ...
$entity = \MyApp\Model\Product();
$manager->persist($entity); // Add object in search and build suggestions
$manager->flush();
// ...
$searchResult = $client->execute(
    $manager->getSearchCommand(\MyApp\Model\Product::class)
        ->setQuery((new MacFJA\RediSearch\Query\Builder())->addNumericFacet('price', 0, 15)->render())
        ->setLimit(0, 12)
);
// ...
$suggestions = $manager->getSuggestions(\MyApp\Model\Product::class, 'shoe');
```

Entity Mapping
--------------

[](#entity-mapping)

There are 5 ways to map a PHP class to RediSearch object.

- With annotations (similar to Doctrine ORM)
- With PHP 8 attributes
- With JSON definition
- With XML definition
- By implementing an interface

### Annotation and Attribute Mapping

[](#annotation-and-attribute-mapping)

A class is considered as valid if it had at least one field mapping

AnnotationPHP 8 AttributeScopeDefault`@Index``#[Index]`ClassClass name (with namespace)`@DocumentId``#[DocumentId]`Property or MethodRandomly generate value`@TextField``#[TextField]`Property or Method*None*`@NumericField``#[NumericField]`Property or Method*None*`@TagField``#[TagField]`Property or Method*None*`@GeoField``#[GeoField]`Property or Method*None*`@Suggestion``#[Suggestion]`Property or Method*None*Annotation and PHP 8 attribute mapping are parsed by respectively `\MacFJA\RediSearch\Integration\Annotation\AnnotationProvider` and `\MacFJA\RediSearch\Integration\Attribute\AttributeProvider`.

#### The `Index` mapping

[](#the-index-mapping)

The `@Index(name, [prefix], [stopsWords])` (or `#[Index(name, [prefix], [stopsWords])]` for PHP 8 attribute) allow you to specify the index where the class will be put.

If the mapping is missing, the Full Class Qualifier Name (namespace + classname) will be used as index name, not prefix will be used and default StopsWorlds will be used.

#### The `DocumentId` mapping

[](#the-documentid-mapping)

The `@DocumentId` (or `#[DocumentId]` for PHP 8 attribute) allow you to specify which hash should be used to identify the document in Redis. The mapping can be set on a property, or on a method that can be call without any parameter.

If the mapping is missing, a random hash will be generated.

#### The `TextField` mapping

[](#the-textfield-mapping)

The `@TextField([name], [noStem], [weight], [phonetic], [sortable], [noIndex], [unNormalized])` (or `#[TextField([name], [noStem], [weight], [phonetic], [sortable], [noIndex], [unNormalized])]` for PHP 8 attribute) allow you to add a text in the search engine. The mapping can be set on a property, or on a method that can be call without any parameter.

- The `name` parameter is used to specify the name of the data in RediSearch. If missing the property name will be used, or the name of the method base on getter rule (`get`/`is`).
- The `noStem` parameter is a boolean used to indicate if the data should use stemming or not.
- The `weight` parameter is a float used to indicate if the weight the data have in result ordering.
- The `phonetic` parameter is a string used to indicate the language to use for phonetic search.
- The `sortable` parameter is a boolean used to indicate if the data can be used to sort result.
- The `noIndex` parameter is a boolean used to indicate if the data should be searchable or not.
- The `unNormalized` parameter is a boolean used to indicate if the data should be searchable or not.

#### The `NumericField` mapping

[](#the-numericfield-mapping)

The `@NumericField([name], [sortable], [noIndex], [unNormalized])` (or `#[NumericField([name], [sortable], [noIndex], [unNormalized])]` for PHP 8 attribute) allow you to add a number in the search engine. The mapping can be set on a property, or on a method that can be call without any parameter.

- The `name` parameter is used to specify the name of the data in RediSearch. If missing the property name will be used, or the name of the method base on getter rule (`get`/`is`).
- The `sortable` parameter is a boolean used to indicate if the data can be used to sort result.
- The `noIndex` parameter is a boolean used to indicate if the data should be searchable or not.
- The `unNormalized` parameter is a boolean used to indicate if the data should be searchable or not.

#### The `TagField` mapping

[](#the-tagfield-mapping)

The `@TagField([name], [separator], [sortable], [noIndex], [unNormalized])` (or `#[TagField([name], [separator], [sortable], [noIndex], [unNormalized])]` for PHP 8 attribute) allow you to add a text in the search engine. The mapping can be set on a property, or on a method that can be call without any parameter.

- The `name` parameter is used to specify the name of the data in RediSearch. If missing the property name will be used, or the name of the method base on getter rule (`get`/`is`).
- The `separator` parameter is a string used to indicate char to use to separate values.
- The `sortable` parameter is a boolean used to indicate if the data can be used to sort result.
- The `noIndex` parameter is a boolean used to indicate if the data should be searchable or not.
- The `unNormalized` parameter is a boolean used to indicate if the data should be searchable or not.

The data link to `TagField` can be a scalar data, or a simple array (one dimension) of scalar

#### The `GeoField` mapping

[](#the-geofield-mapping)

The `@GeoField([name], [noIndex], [sortable], [unNormalized])` (or `#[GeoField([name], [noIndex], [sortable], [unNormalized])]` for PHP 8 attribute) allow you to add a geographic (coordinate) in the search engine. The mapping can be set on a property, or on a method that can be call without any parameter.

- The `name` parameter is used to specify the name of the data in RediSearch. If missing the property name will be used, or the name of the method base on getter rule (`get`/`is`).
- The `noIndex` parameter is a boolean used to indicate if the data should be searchable or not.
- The `unNormalized` parameter is a boolean used to indicate if the data should be searchable or not.

#### The `Suggestion` mapping

[](#the-suggestion-mapping)

The `@Suggestion([group], [score], [increment], [payload])` (or `#[GeoField([group], [score], [increment], [payload])]` for PHP 8 attribute) allow you to add a geographic (coordinate) in the search engine. The mapping can be set on a property, or on a method that can be call without any parameter.

- The `group` parameter is used to specify the name of the suggestion registry in RediSearch. If missing the name is `'suggestion'`.
- The `score` parameter is a float used to indicate *priority* of the value in the suggestion. If missing the score is set to `1.0`.
- The `increment` parameter is a boolean used to indicate is the score of the current suggestion should be added to an already existing suggestion with the same value. If missing, score are not added.
- The `payload` parameter is a string used to add additional data to the suggestion (not used in the suggestion engine). If missing no payload is attach to the suggestion.

### JSON Mapping

[](#json-mapping)

A JSON mapping file can contain several class mapping. The JSON should respect the [Schema](src/Json/schema.json).

```
[
  {
    "class": "\\MyApp\\Model\\Product",
    "index": "product",
    "stop-words": ["the", "a", "an", "this"],
    "fields": {
      "name": {"property": "name", "type": "text"},
      "manufacturer": {"getter": "getManufacturerName", "type": "text"},
      "price": {"getter": "getFinalPrice", "type": "numeric"},
      "colors": {"property": "colors", "type": "tag", "separator": "|"},
      "manufacturer_address": {"property": "manufacturerAddress", "type": "geo"}
    },
    "suggestions": [
      {"property": "name"},
      {"property": "colors", "group": "color"},
      {"getter": "getManufacturerName"}
    ]
  }
]
```

To enable JSON mapping you must use a `\MacFJA\RediSearch\Integration\Json\JsonProvider`. The JSON PHP extension must also be installed.

The JSON file must be given to the `\MacFJA\RediSearch\Integration\Json\JsonProvider::addJson` method.

(The `JsonProvider` can be added to a `CompositeProvider`)

### XML Mapping

[](#xml-mapping)

A XML mapping file can contain several class mapping. The JSON should respect the [XSD Schema](src/Xml/schema.xsd).

```

        id

            the
            a
            an
            this

            firstname
            firstname
            price
            color
            manufacturer_address

```

To enable XML mapping you must use a `\MacFJA\RediSearch\Integration\Xml\XmlProvider`. The SimpleXML PHP extension must also be installed.

The XML file must be given to the `\MacFJA\RediSearch\Integration\Xml\XmlProvider::addXml` method.

(The `XmlProvider` can be added to a `CompositeProvider`)

### The interface mapping

[](#the-interface-mapping)

You can create your own mapping by implementing the `\MacFJA\RediSearch\Integration\Mapping` interface, and add the class to the `SimpleProvider`.

(The `SimpleProvider` can be added to a `CompositeProvider`)

Events
------

[](#events)

The `ObjectWorker` emit several events to allow you to alter its behavior.

Event have separate into two main group: **Before** and **After** group. With the **Before** group you can change configurations before interacting with Redis. The **After** allow you to do more action with results.

### The `Before` group

[](#the-before-group)

*In **bold** parameters that can be changed.*

Event name`ObjectWorker` method (Associated Interface)Available parameters`AddingDocumentToSearchEvent``persist` and `persistSearch` (`ObjectManager`)**`data`**, **`documentId`**, `instance` *(r/o)*`AddingSuggestionEvent``persist` and `persistSuggestions` (`ObjectManager`)**`suggestionMapping`**, `instance` *(r/o)*`CreatingIndexEvent``createIndex` (`ObjectManager`)**`builder`**, `classname` *(r/o)*`GettingSuggestionsEvent``getSuggestions` (`ObjectRepository`)`classname` *(r/o)*, **`prefix`**, **`fuzzy`**, **`withScores`**, **`withPayloads`**, **`max`**, **`inGroup`**`GettingFacetsEvent``getFacets` (`ObjectRepository`)`classname` *(r/o)*, **`query`**, **`fields`**`RemovingDocumentFromSearchEvent``remove` (`ObjectManager`)`instance` *(r/o)*, **`documentId`**### The `After` group

[](#the-after-group)

*In **bold** parameters that can be changed.*

Event name`ObjectWork` method (Associated Interface)Available parameters`AddingDocumentToSearchEvent``persist` and `persistSearch` (`ObjectManager`)`data` *(r/o)*, `documentId` *(r/o)*, `instance` *(r/o)*, `update` *(r/o)*`AddingSuggestionEvent``persist` and `persistSuggestions` (`ObjectManager`)`group` *(r/o)*, `suggestion` *(r/o)*, `score` *(r/o)*, `increment` *(r/o)*, `payload` *(r/o)*, `instance` *(r/o)*`CreatingIndexEvent``createIndex` (`ObjectManager`)`succeed` *(r/o)*, `classname` *(r/o)*`GettingAggregateEvent``getAggregateCommand` (`ObjectRepository`)**`aggregate`**, `classname` *(r/o)*`GettingFacetsEvent``getFacets` (`ObjectRepository`)`classname` *(r/o)*, `query` *(r/o)*, `fields` *(r/o)*, **`facets`**`GettingSearchEvent``getSearchCommand` (`ObjectRepository`)**`search`**, `classname` *(r/o)*`GettingSuggestionsEvent``getSuggestions` (`ObjectRepository`)`classname` *(r/o)*, `prefix` *(r/o)*, `fuzzy` *(r/o)*, `withScores` *(r/o)*, `withPayloads` *(r/o)*, `max` *(r/o)*, `inGroup` *(r/o)*, **`suggestions`**`RemovingDocumentFromSearchEvent``remove` (`ObjectManager`)`instance` *(r/o)*, `documentId` *(r/o)*, `succeed` *(r/o)*Contributing
------------

[](#contributing)

You can contribute to the library. To do so, you have Github issues to:

- ask your questions
- suggest new mapping provider
- request any change (typo, bad code, etc.)
- and much more...

You also have PR to:

- add a new mapping provider
- suggest a correction
- and much more...

See [CONTRIBUTING](CONTRIBUTING.md) for more information.

License
-------

[](#license)

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

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity26

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity61

Established project with proven stability

 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

Every ~147 days

Total

3

Last Release

1646d ago

Major Versions

1.x-dev → 2.0.02021-11-14

PHP version history (2 changes)1.0.0PHP ^7.3 || ^8.0

2.0.0PHP ^7.2 || ^8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1475671?v=4)[MacFJA](/maintainers/MacFJA)[@MacFJA](https://github.com/MacFJA)

---

Top Contributors

[![MacFJA](https://avatars.githubusercontent.com/u/1475671?v=4)](https://github.com/MacFJA "MacFJA (3 commits)")

---

Tags

redisearchredisearch-phpredissearch engineredisearchsuggestion

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Psalm

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/macfja-redisearch-integration/health.svg)

```
[![Health](https://phpackages.com/badges/macfja-redisearch-integration/health.svg)](https://phpackages.com/packages/macfja-redisearch-integration)
```

###  Alternatives

[predis/predis

A flexible and feature-complete Redis/Valkey client for PHP.

7.8k305.7M2.4k](/packages/predis-predis)[macfja/redisearch

PHP Client for RediSearch

67154.9k1](/packages/macfja-redisearch)[snc/redis-bundle

A Redis bundle for Symfony

1.0k39.4M67](/packages/snc-redis-bundle)[clue/redis-protocol

A streaming Redis protocol (RESP) parser and serializer written in pure PHP.

5211.0M13](/packages/clue-redis-protocol)[devgeniem/redipress

RediPress

3432.6k](/packages/devgeniem-redipress)[rtcamp/nginx-helper

Cleans nginx's fastcgi/proxy cache or redis-cache whenever a post is edited/published. Also provides cloudflare edge cache purging with Cache-Tags.

23517.0k1](/packages/rtcamp-nginx-helper)

PHPackages © 2026

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