returns MetaDTO instead of ?MetaDTO

Author: pdphilip

CHANGELOG.md

@@ -10,6 +10,9 @@ This release is compatible with Laravel 11, 12 & 13, and with Elasticsearch 8 &
 
 - **Elasticsearch 9 support** - the full suite runs green against ES 8.18 and 9.5, and CI now tests
   both on every push. No code changes were needed: the `^8.17` client talks to both server lines.
+- **`ElasticCollection::hasQueryMeta()`** - whether a collection carries the meta of the query that
+  built it. False for the collections Eloquent builds on its own: `newCollection()`, `hydrate()`,
+  and anything derived through `map()`, `filter()` or `values()`.
 
 ### Fixed
 
@@ -19,13 +22,28 @@ This release is compatible with Laravel 11, 12 & 13, and with Elasticsearch 8 &
   [laravel-opensearch#28](https://github.com/pdphilip/laravel-opensearch/pull/28)
 - **`cursor()` crashed on a fresh connection** - `Processor::getRawResponse()` dereferenced null when
   a cursor was the first query on its connection (`Call to a member function asArray() on null`)
+- **`paginate()` lost its query meta when nothing matched** - Laravel skips the query entirely once
+  the count comes back as zero, so an empty page arrived as a bare collection and `getQueryMeta()`
+  on it threw `Method Illuminate\Database\Eloquent\Collection::getQueryMeta does not exist`. The
+  count query's meta is now carried onto the empty page: `getTotalHits()` reports `0`, and it still
+  honours `withTrackTotalHits()` for indices past the 10k window
+- **Meta getters fataled on collections Eloquent built itself** - `ElasticCollection::$meta` was a
+  typed property that nothing initialised, so `getQueryMeta()`, `getTook()`, `getDsl()` and the rest
+  threw `Typed property ElasticCollection::$meta must not be accessed before initialization` on any
+  collection that did not come from a query. They now fall back to an empty `QueryMeta`, which
+  reports its unknowns as `-1`. Note that nullsafe could not guard this: the error came from the
+  property access, so `$collection?->getQueryMeta()` fataled too
+- **`Query\Builder::get()` could hand a null `MetaDTO` to `setQueryMeta()`** - it read the
+  `$metaTransfer` property directly instead of the accessor that initialises it
 
 ### Changed
 
 - `cursor()` returns `LazyCollection` instead of `Generator`. `foreach` is unaffected; anything
   type-hinting `Generator` or `Iterator` needs updating
 - A cursor is re-iterable - a second pass opens a fresh scroll instead of throwing
   `Cannot rewind a generator`
+- `Query\Builder::getMetaTransfer()` (internal) returns `MetaDTO` instead of `?MetaDTO` - it
+  initialises on demand and never actually returned null
 
 > **Laravel 11 notice:** three advisories now cover the whole 11.x branch with no 11.x release that
 > clears them, and Composer 2.9+ blocks advisory-affected versions while resolving. On Laravel 11,

src/Eloquent/Builder.php

@@ -318,6 +318,49 @@ public function chunkByPit($count, callable $callback, $keepAlive = '1m'): bool
         return true;
     }
 
+    /**
+     * {@inheritdoc}
+     *
+     * Laravel skips the query entirely when the count comes back as zero and
+     * returns a bare collection. Elasticsearch still ran a search to produce
+     * that zero, so the count query's meta is carried over rather than lost -
+     * without it getQueryMeta() on an empty page has nothing to report.
+     *
+     * @param  Closure|int|null  $perPage
+     * @param  Closure|int|null  $total
+     */
+    public function paginate($perPage = null, $columns = ['*'], $pageName = 'page', $page = null, $total = null)
+    {
+        $page = $page ?: Paginator::resolveCurrentPage($pageName);
+        $countQuery = $this->toBase();
+        $total = value($total) ?? $countQuery->getCountForPagination();
+        $perPage = value($perPage, $total) ?: $this->model->getPerPage();
+
+        $results = $total
+            ? $this->forPage($page, $perPage)->get($columns)
+            : $this->emptyPageCollection($countQuery);
+
+        return $this->paginator($results, $total, $perPage, $page, [
+            'path' => Paginator::resolveCurrentPath(),
+            'pageName' => $pageName,
+        ]);
+    }
+
+    /**
+     * The collection for a page that matched nothing, carrying the meta of the
+     * count query where the model's collection can hold it.
+     */
+    protected function emptyPageCollection(QueryBuilder $countQuery): Collection
+    {
+        $collection = $this->model->newCollection();
+
+        if ($collection instanceof ElasticCollection) {
+            $collection->setQueryMeta($countQuery->getMetaTransfer());
+        }
+
+        return $collection;
+    }
+
     /**
      *  Using Laravel base method name rather
      *

src/Eloquent/ElasticCollection.php

@@ -2,7 +2,6 @@
 
 namespace PDPhilip\Elasticsearch\Eloquent;
 
-use Illuminate\Contracts\Support\Arrayable;
 use Illuminate\Database\Eloquent\Collection;
 use PDPhilip\Elasticsearch\Data\MetaDTO;
 use PDPhilip\Elasticsearch\Data\QueryMeta;
@@ -15,16 +14,7 @@
  */
 class ElasticCollection extends Collection
 {
-    protected ?QueryMeta $meta;
-
-    /**
-     * @param  Arrayable<TKey, TModel>|iterable<TKey, TModel>|array<TKey|int, mixed>|null  $items
-     */
-    public function __construct($items = [])
-    {
-        parent::__construct($items);
-        //        $this->meta = new QueryMeta;
-    }
+    protected ?QueryMeta $meta = null;
 
     public static function loadCollection(Collection $collection)
     {
@@ -45,56 +35,75 @@ public function setQueryMeta(MetaDTO $meta): self
         return $this;
     }
 
+    /**
+     * Whether this collection carries the meta of the query that built it.
+     *
+     * False for the collections Eloquent builds on its own: newCollection(),
+     * hydrate(), and anything derived through map(), filter() or values().
+     */
+    public function hasQueryMeta(): bool
+    {
+        return $this->meta !== null;
+    }
+
+    /**
+     * Meta of the query that built this collection.
+     *
+     * Falls back to an empty QueryMeta, which reports its unknowns as -1, so
+     * that a collection built without a query still answers every getter. The
+     * fallback is not retained: reading meta that was never set must not make
+     * hasQueryMeta() start answering true.
+     */
     public function getQueryMeta(): QueryMeta
     {
-        return $this->meta;
+        return $this->meta ?? new QueryMeta;
     }
 
     public function getQueryMetaAsArray(): array
     {
-        return $this->meta->toArray();
+        return $this->getQueryMeta()->toArray();
     }
 
     public function getDsl(): array
     {
         return [
-            'query' => $this->meta->getQuery(),
-            'dsl' => $this->meta->getDsl(),
+            'query' => $this->getQueryMeta()->getQuery(),
+            'dsl' => $this->getQueryMeta()->getDsl(),
         ];
     }
 
     public function getTook(): int
     {
-        return $this->meta->getTook();
+        return $this->getQueryMeta()->getTook();
     }
 
     public function getShards(): mixed
     {
-        return $this->meta->getShards();
+        return $this->getQueryMeta()->getShards();
     }
 
     public function getTotal(): int
     {
-        return $this->meta->getTotal();
+        return $this->getQueryMeta()->getTotal();
     }
 
     public function getMaxScore(): string
     {
-        return $this->meta->getMaxScore();
+        return $this->getQueryMeta()->getMaxScore();
     }
 
     public function getResults(): array
     {
-        return $this->meta->getResults();
+        return $this->getQueryMeta()->getResults();
     }
 
     public function getPitId()
     {
-        return $this->meta->getPitId();
+        return $this->getQueryMeta()->getPitId();
     }
 
     public function getAfterKey()
     {
-        return $this->meta->getAfterKey();
+        return $this->getQueryMeta()->getAfterKey();
     }
 }

src/Query/Builder.php

@@ -593,7 +593,7 @@ public function get($columns = ['*']): ElasticCollection|array
         $results = $this->getResultsOnce();
         $this->columns = $original;
         $collection = ElasticCollection::make($results);
-        $collection->setQueryMeta($this->metaTransfer);
+        $collection->setQueryMeta($this->getMetaTransfer());
 
         return $collection;
     }
@@ -670,9 +670,11 @@ public function getCountForPagination($columns = ['*'])
      */
     protected function runPaginationCountQuery($columns = ['_id'])
     {
-        return $this->cloneWithout(['columns', 'orders', 'limit', 'offset'])
-            ->limit(1)
-            ->get($columns)->all();
+        $countQuery = $this->cloneWithout(['columns', 'orders', 'limit', 'offset'])->limit(1);
+        $results = $countQuery->get($columns)->all();
+        $this->setMetaTransfer($countQuery->getMetaTransfer());
+
+        return $results;
     }
 
     /**
@@ -1313,7 +1315,7 @@ public function setMetaTransfer(MetaDTO $metaTransfer): void
     }
 
     // @internal
-    public function getMetaTransfer(): ?MetaDTO
+    public function getMetaTransfer(): MetaDTO
     {
         if (! $this->metaTransfer) {
             $this->metaTransfer = new MetaDTO([]);

tests/QueryMetaTest.php

@@ -0,0 +1,98 @@
+<?php
+
+declare(strict_types=1);
+
+use PDPhilip\Elasticsearch\Data\QueryMeta;
+use PDPhilip\Elasticsearch\Eloquent\ElasticCollection;
+use PDPhilip\Elasticsearch\Tests\Models\User;
+
+beforeEach(function () {
+    User::executeSchema();
+
+    User::insert([
+        ['name' => 'John Doe', 'age' => 35, 'title' => 'admin'],
+        ['name' => 'Jane Doe', 'age' => 33, 'title' => 'admin'],
+        ['name' => 'Harry Hoe', 'age' => 13, 'title' => 'user'],
+        ['name' => 'Robert Roe', 'age' => 37, 'title' => 'user'],
+        ['name' => 'Mark Moe', 'age' => 23, 'title' => 'user'],
+    ]);
+});
+
+it('carries the query meta on a page that has results', function () {
+    $results = User::where('title', 'user')->paginate(2);
+
+    expect($results->getCollection())->toBeInstanceOf(ElasticCollection::class)
+        ->and($results->getCollection()->hasQueryMeta())->toBeTrue()
+        ->and($results->total())->toBe(3)
+        ->and($results->getQueryMeta()->getTotalHits())->toBe(3);
+});
+
+it('carries the query meta on a page that matched nothing', function () {
+    $results = User::where('age', 999)->paginate(2);
+
+    expect($results->getCollection())->toBeInstanceOf(ElasticCollection::class)
+        ->and($results->getCollection()->hasQueryMeta())->toBeTrue()
+        ->and($results->count())->toBe(0)
+        ->and($results->total())->toBe(0)
+        ->and($results->getQueryMeta())->toBeInstanceOf(QueryMeta::class)
+        ->and($results->getQueryMeta()->getTotalHits())->toBe(0)
+        ->and($results->getQueryMeta()->getTook())->toBeGreaterThanOrEqual(0);
+});
+
+it('reports the full total on a page that matched nothing when tracking total hits', function () {
+    $results = User::where('age', 999)->withTrackTotalHits()->paginate(2);
+
+    expect($results->total())->toBe(0)
+        ->and($results->getQueryMeta()->getTotalHits())->toBe(0);
+});
+
+it('keeps the query meta through paginator transforms', function () {
+    $emptyPage = User::where('age', 999)->paginate(2)
+        ->withQueryString()
+        ->through(fn ($user) => ['name' => $user->name]);
+
+    $fullPage = User::where('title', 'user')->paginate(2)
+        ->withQueryString()
+        ->through(fn ($user) => ['name' => $user->name]);
+
+    expect($emptyPage->getQueryMeta()->getTotalHits())->toBe(0)
+        ->and($fullPage->getQueryMeta()->getTotalHits())->toBe(3);
+});
+
+it('answers every meta getter on a collection built without a query', function () {
+    $collection = new ElasticCollection;
+
+    expect($collection->hasQueryMeta())->toBeFalse()
+        ->and($collection->getQueryMeta())->toBeInstanceOf(QueryMeta::class)
+        ->and($collection->getQueryMeta()->getTotalHits())->toBe(-1)
+        ->and($collection->getQueryMetaAsArray())->toBe([])
+        ->and($collection->getTook())->toBe(-1)
+        ->and($collection->getTotal())->toBe(-1)
+        ->and($collection->getMaxScore())->toBe('')
+        ->and($collection->getShards())->toBe([])
+        ->and($collection->getDsl())->toBe(['query' => '', 'dsl' => []])
+        ->and($collection->getResults())->toBe([])
+        ->and($collection->getAfterKey())->toBe([])
+        ->and($collection->getPitId())->toBeNull()
+        ->and($collection->hasQueryMeta())->toBeFalse();
+});
+
+it('builds meta safe collections for models', function () {
+    $newCollection = (new User)->newCollection();
+    $hydrated = User::hydrate([['name' => 'John Doe']]);
+
+    expect($newCollection)->toBeInstanceOf(ElasticCollection::class)
+        ->and($newCollection->hasQueryMeta())->toBeFalse()
+        ->and($newCollection->getQueryMeta()->getTotalHits())->toBe(-1)
+        ->and($hydrated)->toBeInstanceOf(ElasticCollection::class)
+        ->and($hydrated->hasQueryMeta())->toBeFalse()
+        ->and($hydrated->getQueryMeta()->getTotalHits())->toBe(-1);
+});
+
+it('keeps the query meta on a fetched collection', function () {
+    $users = User::where('title', 'user')->get();
+
+    expect($users->hasQueryMeta())->toBeTrue()
+        ->and($users->getQueryMeta()->getTotalHits())->toBe(3)
+        ->and($users->getTook())->toBeGreaterThanOrEqual(0);
+});