Defining new backend features

As explained in the “Getting started” guide, backend features are used to cleanly utilize backend functionalities that are not provided by all Search API backends. If your contributed module wants to make use of such a functionality (for instance, some specific feature of Apache Solr) in a clean way, here is how to do it.

(Side note: For custom code that will only run on your own site(s), it is usually not necessary or helpful to define a new feature. This is more a concept for inter-module operability, to keep the contrib module ecosystem working well together, even when your module is being used with a backend plugin you weren’t even aware of.)

Defining a new feature

1. Pick an identifier for the feature. Usually, this has the format MODULE_something, or even just MODULE if it’s the main functionality of your module. For instance, the Search API module itself defines the search_api_mlt and search_api_random_sort features, while Search API Autocomplete just defines a search_api_autocomplete feature.
2. Add a new section to your module’s README.md file, titled something like “Search API backend features”. There, document this new feature. (You can refer to the above-mentioned modules’ README.md files for examples.)
3. For the documentation, just define what you want to be able to use (for instance, call a specific method on the backend plugin, or pass a specific query option, use a specific operator in conditions, …) on backends that support this feature. For instance, the search_api_autocomplete feature requires backend plugins to include a getAutocompleteSuggestions(), the behavior of which the Search API Autocomplete module specifies by providing an interface.
4. In any places in your code where you want to use the given functionality (for instance, call the method), first check whether the current search server (resp. its backend plugin) supports your feature, by calling $server->supportsFeature($feature_name).

Implementing a feature with a backend plugin

A new feature is useless without any backends implementing it, so you’ll usually want to add support for your new feature to at least one backend. In our example, where you want to use some specific Solr functionality, you would either need to get a patch committed to the Search API Solr module, or implement the feature on that module’s behalf using the DeterminingServerFeaturesEvent event.

The necessary steps for supporting a feature with a backend plugin are as follows:

1. Declare that your backend plugin supports the feature by implementing the getSupportedFeatures() method and returning an array containing at least that feature’s name.
2. Follow the instructions in the README.md defining the feature to provide all the expected functionality with your backend plugin. For instance, add the required method to it.

(When supporting a feature via the DeterminingServerFeaturesEvent event, step 2 could of course be rather tricky. This completely depends on what your feature entails exactly, though.)