Helper tools to integrate RediSearch in PHP project
MIT License
MacFJA/redisearch-integration is a small library to ease usage of MacFJA/redisearch which is a RediSearch client.
composer require macfja/redisearch-integration
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');
There are 5 ways to map a PHP class to RediSearch object.
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
.
Index
mappingThe @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.
DocumentId
mappingThe @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.
TextField
mappingThe @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.
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
).noStem
parameter is a boolean used to indicate if the data should use stemming or not.weight
parameter is a float used to indicate if the weight the data have in result ordering.phonetic
parameter is a string used to indicate the language to use for phonetic search.sortable
parameter is a boolean used to indicate if the data can be used to sort result.noIndex
parameter is a boolean used to indicate if the data should be searchable or not.unNormalized
parameter is a boolean used to indicate if the data should be searchable or not.NumericField
mappingThe @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.
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
).sortable
parameter is a boolean used to indicate if the data can be used to sort result.noIndex
parameter is a boolean used to indicate if the data should be searchable or not.unNormalized
parameter is a boolean used to indicate if the data should be searchable or not.TagField
mappingThe @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.
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
).separator
parameter is a string used to indicate char to use to separate values.sortable
parameter is a boolean used to indicate if the data can be used to sort result.noIndex
parameter is a boolean used to indicate if the data should be searchable or not.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
GeoField
mappingThe @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.
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
).noIndex
parameter is a boolean used to indicate if the data should be searchable or not.unNormalized
parameter is a boolean used to indicate if the data should be searchable or not.Suggestion
mappingThe @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.
group
parameter is used to specify the name of the suggestion registry in RediSearch. If missing the name is 'suggestion'
.score
parameter is a float used to indicate priority of the value in the suggestion. If missing the score is set to 1.0
.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.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.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
)
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
)
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
)
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.
Before
groupIn 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
|
After
groupIn 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)
|
You can contribute to the library. To do so, you have Github issues to:
You also have PR to:
See CONTRIBUTING for more information.
The MIT License (MIT). Please see License File for more information.