Open up Paginator::$documents for read

[signor-pedro]

Description
In Elasticsearch\Paginator, the results of the query stored in $this->documents are private readonly.

Since the property is readonly anyway, would you be willing to make it public readonly?

A lot of the time, Elasticsearch returns metadata such as aggregations, necessary for building feature-rich search experiences.

It is a total waste of time to implement a custom Elasticsearch provider. The native one is great and does a lot of heavy lifting. If the property was open for read, I could simply decorate the normalizer, see example.

Example

#[AsDecorator('api_platform.hydra.normalizer.collection')]
class ElasticsearchNormalizer implements NormalizerInterface, NormalizerAwareInterface
{
    public function __construct(
        private NormalizerInterface $normalizer,
    ) {
    }

    public function normalize(mixed $object, string $format = null, array $context = []): array
    {
        if (!$object instanceof Elasticsearch\Paginator) {
            throw new \LogicException();
        }

        return array_merge(
            $this->normalizer->normalize($object, $format, $context), // produces a valid hydra:collection
            ['aggregations => $object->documents['aggregations']], // metadata returned by Elasticsearch read from the raw result
        ));
    }
}