New Feature: search with boolean operators

[moraleida]

Description of the Change

Introduces a new feature to allow using Boolean Search Operators such as + | - () * ~N in search queries.

This is an optional feature and should be disabled when first introduced. Users can opt-in to the feature globally using the ElasticPress Features dashboard, or on individual queries by setting $wp_query->ep_boolean_operators = true.

When activated, the feature hooks into ep_formatted_args_query and replaces the default multi_match queries with Elasticsearch native simple_query_string queries.

Syntax

• + signifies AND operation
• | signifies OR operation
• - negates a single token
• " wraps a number of tokens to signify a phrase for searching
• * at the end of a term signifies a prefix query
• ( and ) signify precedence
• ~N after a word signifies edit distance (fuzziness)
• ~N after a phrase signifies slop amount

To use one of these characters literally, escape it with a preceding backslash ().

This implementation also detects the use of uppercase AND, OR and NOT queries and replaces them with their proper counterparts: +, | and - when preparing the ES query. If no boolean operators are found in the search text, the feature is not activated and the query continues as a regular ElasticPress query.

Benefits

simple_query_string queries are transformed internally into match_phrase queries. This allows for easier control of phrase matches using "google-like" queries (such as using quotes for phrases), as well as for more "academic-like" queries to be used in museums, libraries, or just to allow more control, while still allowing for the power of match queries to find partial results, fuzziness and slop, among other features.

Includes direct filters to change the most important top-level parameters as well as a catch-all filter allowing the query to be freely modified.

Possible Drawbacks

None. This feature is opt-in and will be inactive unless explicitly required.

Checklist:

• I have read the CONTRIBUTING document.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my change.
• All new and existing tests passed.

Applicable Issues

Fixes: #2039

Changelog Entry

Added: Feature - Search with Boolean Operators

[mckdemps]

We are integrating that code on ElasticPress Labs and it will be published on the main plugin at a later point.

[Rahmon]

Closing in favor of 10up/ElasticPressLabs#3