README

MacFJA/redisearch-integration is a small library to ease usage of MacFJA/redisearch which is a RediSearch client.

Installation

composer require macfja/redisearch-integration

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

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

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

Annotation	PHP 8 Attribute	Scope	Default
`@Index`	`#[Index]`	Class	Class name (with namespace)
`@DocumentId`	`#[DocumentId]`	Property or Method	Randomly 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(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 (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([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([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([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([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([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

A JSON mapping file can contain several class mapping. The JSON should respect the Schema.

[
  {
    "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

A XML mapping file can contain several class mapping. The JSON should respect the XSD Schema.

<?xml version="1.0" encoding="UTF-8" ?>
<redis-search xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://github.com/MacFJA/php-redisearch-integration/blob/main/src/Xml/schema.xsd">
    <class name="MyApp\Model\Integration\Product" indexname="product">
        <id type="property">id</id>
        <stops-words>
            <word>the</word>
            <word>a</word>
            <word>an</word>
            <word>this</word>
        </stops-words>
        <fields>
            <text-field>firstname</text-field>
            <text-field getter="getManufacturerName">firstname</text-field>
            <numeric-field getter="getFinalPrice">price</numeric-field>
            <tag-field property="colors" separator="|">color</tag-field>
            <geo-field property="manufacturerAddress">manufacturer_address</geo-field>
        </fields>
        <suggestions>
            <property name="name" />
            <property name="colors" group="color" />
            <getter name="getManufacturerName" />
        </suggestions>
    </class>
</redis-search>

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

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

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

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

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

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 for more information.

License

The MIT License (MIT). Please see License File for more information.

macfja / redisearch-integration

Maintainers

Details

README

Installation

Usage

Entity Mapping

Annotation and Attribute Mapping

The `Index` mapping

The `DocumentId` mapping

The `TextField` mapping

The `NumericField` mapping

The `TagField` mapping

The `GeoField` mapping

The `Suggestion` mapping

JSON Mapping

XML Mapping

The interface mapping

Events

The `Before` group

The `After` group

Contributing

License

macfja / redisearch-integration

Maintainers

Details

README

Installation

Usage

Entity Mapping

Annotation and Attribute Mapping

The Index mapping

The DocumentId mapping

The TextField mapping

The NumericField mapping

The TagField mapping

The GeoField mapping

The Suggestion mapping

JSON Mapping

XML Mapping

The interface mapping

Events

The Before group

The After group

Contributing

License

The `Index` mapping

The `DocumentId` mapping

The `TextField` mapping

The `NumericField` mapping

The `TagField` mapping

The `GeoField` mapping

The `Suggestion` mapping

The `Before` group

The `After` group