Download the PHP package jolicode/elastically without Composer

Elastically, Elastica based framework

Opinionated Elastica based framework to bootstrap PHP and Elasticsearch implementations.

Main features:

• DTO are first class citizen, you send PHP object as documents, and get objects back on search results, like an ODM;
• All indexes are versioned and aliased automatically;
• Mappings are done via YAML files, PHP or custom via MappingProviderInterface;
• Analysis is separated from mappings to ease reuse;
• 100% compatibility with ruflin/elastica;
• Mapping migration capabilities with ReIndex;
• Symfony HttpClient compatible transport (optional);
• Symfony support (optional):
  • See dedicated chapter;
  • Tested with Symfony 5.4 to 7;
  • Symfony Messenger Handler support (with or without spool);

[!IMPORTANT] Require PHP 8.0+ and Elasticsearch 8+.

Works with Elasticsearch 7 as well, but is not officially supported by Elastica 8. Use with caution.

Version 2+ does not work with OpenSearch anymore due to restrictions added by Elastic on their client.

You can check the upgrade documents.

Installation

Demo

[!TIP] If you are using Symfony, you can move to the Symfony chapter

Quick example of what the library do on top of Elastica:

[!NOTE] scheduleIndex is here called with "beers" index because the index was already created before. If you are creating a new index and want to index documents into it, you should pass the Index object directly.

mappings/beers_mapping.yaml

Configuration

This library add custom configurations on top of Elastica's:

Factory::CONFIG_MAPPINGS_DIRECTORY (required with default configuration)

The directory Elastically is going to look for YAML.

When creating a foobar index, a foobar_mapping.yaml file is expected.

If an analyzers.yaml file is present, all the indices will get it.

Factory::CONFIG_INDEX_CLASS_MAPPING (required)

An array of index name to class FQN.

Factory::CONFIG_MAPPINGS_PROVIDER

An instance of MappingProviderInterface.

If this option is not defined, the factory will fall back to YamlProvider and will use Factory::CONFIG_MAPPINGS_DIRECTORY option.

There are two providers available in Elastically: YamlProvider and PhpProvider.

Factory::CONFIG_SERIALIZER (optional)

A SerializerInterface compatible object that will be used on indexation.

Default to Symfony Serializer with Object Normalizer.

A faster alternative is to use Jane to generate plain PHP Normalizer, see below. Also, we recommend customization to handle things like Date.

Factory::CONFIG_DENORMALIZER (optional)

A DenormalizerInterface compatible object that will be used on search results to build your objects back.

If this option is not defined, the factory will fall back to Factory::CONFIG_SERIALIZER option.

Factory::CONFIG_SERIALIZER_CONTEXT_BUILDER (optional)

An instance of ContextBuilderInterface that build a serializer context from a class name.

If it is not defined, Elastically, will use a StaticContextBuilder with the configuration from Factory::CONFIG_SERIALIZER_CONTEXT_PER_CLASS.

Factory::CONFIG_SERIALIZER_CONTEXT_PER_CLASS (optional)

Allow to specify the Serializer context for normalization and denormalization.

Default to [].

Factory::CONFIG_BULK_SIZE (optional)

When running indexation of lots of documents, this setting allow you to fine-tune the number of document threshold.

Default to 100.

Factory::CONFIG_INDEX_PREFIX (optional)

Add a prefix to all indexes and aliases created via Elastically.

Default to null.

Usage in Symfony

Configuration

You'll need to add the bundle in bundles.php:

Then configure the bundle:

Finally, inject one of those service (autowirable) in you code where you need it:

Advanced Configuration

Multiple Connections and Autowiring

If you define multiple connections, you can define a default one. This will be useful for autowiring:

To use class for other connection, you can use Autowirable Types. To discover them, run:

Use a Custom Serializer Context Builder

Use a Custom Mapping provider

Using HttpClient as Transport

You can also use the Symfony HttpClient for all Elastica communications:

See the official documentation on how to get a PSR-18 client.

Reference

You can run the following command to get the default configuration reference:

Using Messenger for async indexing

Elastically ships with a default Message and Handler for Symfony Messenger.

Register the message in your configuration:

The IndexationRequestHandler service depends on an implementation of JoliCode\Elastically\Messenger\DocumentExchangerInterface, which isn't provided by this library. You must provide a service that implements this interface, so you can plug your database or any other source of truth.

Then from your code you have to call:

And then consume the messages:

Grouping IndexationRequest in a spool

Sending multiple IndexationRequest during the same Symfony Request is not always appropriate, it will trigger multiple Bulk operations. Elastically provides a Kernel listener to group all the IndexationRequest in a single MultipleIndexationRequest message.

To use this mechanism, we send the IndexationRequest in a memory transport to be consumed and grouped in a really async transport:

You also need to register the subscriber:

Using Jane to build PHP DTO and fast Normalizers

Install JanePHP json-schema tools to build your own DTO and Normalizers. All you have to do is setting the Jane-completed Serializer on the Factory:

[!CAUTION] Elastically is not compatible with Jane < 6.

To be done

• some "todo" in the code
• optional Doctrine connector
• extra commands to monitor, update mapping, reindex... Commonly implemented tasks
• optional Symfony integration:
  • web debug toolbar!
• scripts / commands for common tasks:
  • auto-reindex when the mapping change, handle the aliases and everything
  • micro monitoring for cluster / indexes
  • health-check method

Sponsors

Open Source time sponsored by JoliCode.