Allow custom hits iterator

[booni3]

We need a method to be able to swap out the hits generator on a search by search basis. For example if adding the highlight feature, we need to be able to merge the highlighted html back into the results.

I suggested add this into the ElasticSearchEngine class but obviously needs better implementation.

$model::search($query,
    function (Client $client, Search $body) use ($model, $field) {
        $???->useHitsIterator(HighlighterHitsIteratorAggregate::class);
        $highlight = new Highlight();
        $highlight->addField($field);
        $body->addHighlight($highlight);
        return $client->search(['index' => $model->searchableAs(), 'body' => $body->toArray()]);
    })->paginate(100);

[matchish]

I think we should configure engine here
https://github.com/laravel/scout/blob/c145b4dd752ccdda7855344981dd1815ee0ae746/src/Builder.php#L314

[matchish]

Or you can extend builder in your app to

$model::search($query,
    function (Client $client, Search $body) use ($model, $field) {
        $highlight = new Highlight();
        $highlight->addField($field);
        $body->addHighlight($highlight);
        return $client->search(['index' => $model->searchableAs(), 'body' => $body->toArray()]);
    })->using(new Engine(new HitsIteratorFactory))->paginate(100);

But I'm still not sure what solution is better. Or maybe we should propose to change api
in laravel/scout

[matchish]

Now perfect api for me looks like(no callback at all)

$model::search(new Query($term))->engine(new Engine(new ResultsFactory))->paginate(100);

Or now we can do like this

$raw = $model::search($query,
    function (Client $client, Search $body) use ($model, $field) {
        $highlight = new Highlight();
        $highlight->addField($field);
        $body->addHighlight($highlight);
        return $client->search(['index' => $model->searchableAs(), 'body' => $body->toArray()]);
    })->raw();
$resullts = new HiglightedResults($raw);

[matchish]

Or without changing laravel/scout api
$model::search($term)->query(new ResultsFactory)->paginate(100);

We should't choose how to map results in the engine if we have queryCallback just send to the callback raw results then ResultsFactory can map it in the right way

@booni3 Now I'm working on another issue, I'm trying to finish parallel importing so feel free to send PR if you want.