add generic return types to Builder paginate methods

[levikl]

summary

Illuminate\Database\Eloquent\Builder already declares @template TModel of \Illuminate\Database\Eloquent\Model at the class level, and the three paginator classes (LengthAwarePaginator, Paginator, CursorPaginator) already declare @template TKey of array-key and @template-covariant TValue. this change threads the two together by adding generic return type annotations to the three paginate methods on Builder.

before:

/** @return \Illuminate\Pagination\LengthAwarePaginator */
public function paginate(...) { ... }

/** @return \Illuminate\Contracts\Pagination\Paginator */
public function simplePaginate(...) { ... }

/** @return \Illuminate\Contracts\Pagination\CursorPaginator */
public function cursorPaginate(...) { ... }

after:

/** @return \Illuminate\Pagination\LengthAwarePaginator<int, TModel> */
public function paginate(...) { ... }

/** @return \Illuminate\Pagination\Paginator<int, TModel> */
public function simplePaginate(...) { ... }

/** @return \Illuminate\Pagination\CursorPaginator<int, TModel> */
public function cursorPaginate(...) { ... }

why

without these annotations, static analysis tools have no way to carry the model type through a paginator. a call like Product::paginate(5) resolves to an untyped LengthAwarePaginator, so tools that inspect the return shape (eg. for Inertia type generation) fall back to data: Record<string, unknown> instead of emitting data: Product[].

this is a docblock-only change; no runtime behavior is affected.

related

• Resolve @template bindings in Arrayable shapes and Builder method return types surveyor#39
• next: paginated Eloquent response type narrowing wayfinder#249

merge order

this -> laravel/surveyor -> laravel/wayfinder

[levikl]

asking for a friend: how do you backport a docblock change to laravel 12.x + 11.x?