Add $search stage to aggregation pipeline builder

[alcaeus]

Q	A
Type	feature
BC Break	no
Fixed issues	#2460

Summary

This adds the $search aggregation pipeline stage to the aggregation builder. This stage only works on MongoDB Atlas with Search indexes.

The following is missing from this PR:

• The span operator - I'm currently looking into the documentation as it is using undocumented operators
• The facet collector - this is relevant for the $searchMeta stage but would conflict with the facet stage that people could add down the line. For now, users should use the $$SEARCH_META aggregation variable
• Documentation on how to create indexes (which is only possible through Atlas) and how to use the $search stage itself.

[alcaeus]

Creating as a draft for initial review until #2515 is merged.

[alcaeus]

All of these compounded operator classes could be created as anonymous classes, but that trips psalm into an endless recursion: vimeo/psalm#9573.

[jmikola]

Here's a first pass.

FYI: I had trouble following what all of the compound operator classes were used for. I understand the syntax in Atlas Search (although just barely), but this was too much to wrap my head around in a PR.

[alcaeus]

I had trouble following what all of the compound operator classes were used for.

Yeah, that's where stuff gets messy. In a nutshell, the $search pipeline stage supports a single operator, for example:

{ $search: { query: 'jmikola', path: 'content' } }

This is constructed using:

$builder->search()
    ->text()
        ->query('jmikola')
        ->path('content')

However, when using compound, one can combine multiple operators in one of four conditions (must, mustNot, should, filter). For example:

$builder->search()
    ->compound()
        ->must()
            ->text()->query('jmikola')->path('content')
            ->equals()->value('alcaeus')->path('author')
        ->mustNot()
            ->text()->query('bad words')->path('content')

In this case, the result of text() has to return not only an instance of the Text class used to configure the operator, but at the same time an instance of the surrounding compound operator to allow for switching to another filter. We can do this by composing the original operator class with the interface for the compound operator and using a trait to fill in the functionality (as every operator added will have to be wrapped as well). I had originally planned returning an anonymous class instance for this, but Psalm did not agree with me there so I had to create those separate Compound... operator classes.

The idea behind all this is to not rely on some __call magic and instead provide proper typing information so tools like PhpStorm can show correct code completion options when using the fluent interface.