PHPLIB-1419 Encode Agg builder objects in Collection methods

[GromNaN]

Fix PHPLIB-1419

Requires #1382

The encoding is done in the Collection methods, not in the various Operation classes:

• No option to validate in each Operation class
• Very little code duplicate in each method, whereas handling in operation classes would require the documentation and validation of the new option in each class.
• In the future, it is still possible to move the encoding and add an option to the methods without breaking change.

Only the BulkWrite operation has the option, because the processing of each operation is already organised in this operation class.

The Collection methods does not accept the builderEncoder option for now. If a specific encoder is necessary for an operation, if can be called just before the operation:

$pipeline = new Pipeline(...);

// Required for now, as we could not change the argument type. In 2.0 this will not be necessary.
$pipeline = iterator_to_array($pipeline);

$pipeline = (new CustomBuilderEncoder)->encode($pipeline);
$collection->aggregate($pipeline);

[GromNaN]

Tests failing only in evergreen "test-mongodb-4.0-replicaset-noauth-nossl"

[alcaeus]

We missed a BC break while planning this, so we'll have to think about how we can accomplish this.

The changes made to aggregate and watch will also have to be applied to the Client::watch, Database::watch, and Database::aggregate methods.

[alcaeus]

I don't know how I missed this while we were planning things, but this is a BC break, as any class extending Collection and overriding aggregate will be incompatible due to a narrower parameter type. I don't know if there's a way to solve this in 1.x, as I'd hate to defer this feature to 2.x.

[GromNaN]

The compromise we can make for the moment is to accept an array of stages.

$pipeline = new Pipeline(...);
$results = $collection->aggregate(iterator_to_array($pipeline));

[jmikola]

I assume this was copied from testChangeStreamExample_1_4 in DocumentationExamplesTest. I think this skip was only done for documentation examples to avoid complicating the code snippets.

32bade4 also introduced advanceCursorUntilValid() to fix change stream iteration for sharded clusters in our other tests.

I won't push for changing this, but wanted to provide some context.

[GromNaN]

Thanks for the context. In fact, I've simplified the documentation example you pointed. Given what's being tested, I don't think it's essential for the test to run on all server typologies.