Add $setWindowFields aggregation pipeline stage and window operators

[alcaeus]

Q	A
Type	feature
BC Break	no
Fixed issues

Summary

Last but not least, this pull request adds support for window operators and the $setWindowFields aggregation pipeline stage to the builder. There is some code duplication between group accumulators and window operators, as the latter includes all group accumulators except for $mergeObjects. To avoid polluting the interfaces and traits, I've decided to accept the duplication considering that the methods only proxy calls to the Expr class.

[jmikola]

If I understand correctly, the result of array_map() is going to be an associative array of field names to { window: ... } objects. Expr::getExpression() is documented as returning array<string, mixed>.

Isn't that problematic if the expression value isn't an array? Actually, even if it is an array how do you merge a stdClass into it?

[alcaeus]

Ah, this is one where I wasn't sure whether using array_merge_recursive would be sensible. To explain, while the Expr class can generate the expressions used in the setWindowFields output, it can't handle the additional window option used there. Expr can generate this:

{ foo: { $rank: {} }
// Generated using $expr->field('foo')->rank();

But not this as is valid in a window stage:

{ foo: {
    $rank: {},
    window: {...}
}}

To work around this, we use the Expr class to handle operators and store the windows for fields ourselves. In getExpression, we generate the output of the Expr object, which gives us something like this:

[
    'foo' => ['$rank' => []],
    'bar' => ['$documentNumber' => []],
]

The windows property contains the windows (in my example, only foo uses a window):

[
    'foo' => ['documents' => ['unbounded', 'current']],
]

The array_map call then generates the window portion, resulting in this:

[
    'foo' => ['window' => (object) ['documents' => ['unbounded', 'current']]],
]

We can then use array_merge_recursive to recursively merge windows and field expressions together, resulting in this:

[
    'foo' => [
        '$rank' => [],
        'window' => (object) [...],
    ],
    'bar' => ['$documentNumber' => []],
]

To make a long story short, I'll add a comment explaining what this does.

[jmikola]

PHP-CS-Fixer/PHP-CS-Fixer#5449 (comment) was an interesting read about the relevance of static here.