PaginatorContract should implement Countable and other shared interfaces

[albertocactus]

Hello Laravel Team,

I've noticed a small discrepancy between the \Illuminate\Contracts\Pagination\Paginator contract and its concrete implementation, \Illuminate\Pagination\Paginator. This inconsistency impacts the developer experience by causing incorrect type hint warnings in IDEs and static analysis tools.

The Problem

When using the simplePaginate method, the documented return type is \Illuminate\Contracts\Pagination\Paginator.

/** @var \Illuminate\Database\Eloquent\Builder $query */
$paginatedResults = $query->simplePaginate(15);
// IDEs and static analysis tools will flag the following line with an error:
// "Undefined method 'count'"
$count = $paginatedResults->count(); 

The code runs without any errors because the concrete class returned, \Illuminate\Pagination\Paginator, does implement the Countable interface. However, the contract (PaginatorContract) itself does not extend Countable, leading to the developer-facing error in the IDE.

The same issue applies to other interfaces implemented by the Paginator class, such as Arrayable, ArrayAccess, IteratorAggregate, Jsonable, and JsonSerializable.

Proposed Solution

To improve type safety and the overall developer experience, I suggest that the contract should reflect the full public API of its primary implementation.

The PaginatorContract could be updated to extend all the interfaces that the concrete Paginator class implements.

Current PaginatorContract:

// file: vendor/laravel/framework/src/Illuminate/Contracts/Pagination/Paginator.php
interface Paginator 
{
    // ...
}

Current Paginator class:

// file: vendor/laravel/framework/src/Illuminate/Pagination/Paginator.php
class Paginator extends AbstractPaginator implements Arrayable, ArrayAccess, Countable, IteratorAggregate, Jsonable, JsonSerializable, PaginatorContract
{
    // ... implementation
}

Suggested Change

The interfaces should be moved from the concrete class to the contract.

New PaginatorContract:

// file: vendor/laravel/framework/src/Illuminate/Contracts/Pagination/Paginator.php
use Illuminate\Contracts\Support\Arrayable;
use Illuminate\Contracts\Support\Jsonable;
use ArrayAccess;
use Countable;
use IteratorAggregate;
use JsonSerializable;

interface Paginator extends Arrayable, ArrayAccess, Countable, IteratorAggregate, Jsonable, JsonSerializable
{
    // ... methods
}

New Paginator class:

// file: vendor/laravel/framework/src/Illuminate/Pagination/Paginator.php
class Paginator extends AbstractPaginator implements PaginatorContract
{
    // ... implementation
}

This change would make the contract a complete representation of the Paginator's capabilities, immediately fixing the type hinting issues without introducing any breaking changes to the method signatures themselves.

Thank you for your consideration and for building such a great framework!

[macropay-solutions]

This is doable only if the interface is not used by other classes from laravel or 3rd party libs.

[mbabker]

TBH, there are a lot of times where typehinting against a contract gives you an incomplete API because the reality is things in Laravel are designed against the concrete implementations. The one that always irritates me is how the container (and by extension, the application) contract doesn't implement ArrayAccess, yet it is not uncommon to see $this->app['whatever'] or $app['whatever'] in code interacting with the container or application (scan your vendor folder for Laravel service providers and see how often it comes up, both in Laravel itself and any packages you use). These types of hidden dependencies really make working solely with Laravel's interfaces annoying.

Just make the B/C break and make the contracts reliable instead of relying on the behaviors of the concrete implementations. Or get rid of the contracts because they clearly aren't covering all expectations.

[macropay-solutions]

We love that $app['text']. We just love it. :)))

Laravel is to be used as it is. No questions asked. It can't evolve because if it does it breaks things. The only solution is to be rewritten for NEW PROJECTs only with major breaking changes.

[mbabker]

We love that $app['text']. We just love it. :)))

I have no problem with it, but any time I see a $this->app['whatever'] when the app property has a (doc block only) type of Illuminate\Contracts\Foundation\Application, it grinds my gears simply because ArrayAccess isn't part of the contract. It's the paper cuts like that that make things annoying sometimes.

It's the same type of issue as the contracts having incomplete type declarations or the concrete implementations not respecting the contracts, it just makes them meaningless to me.

[macropay-solutions]

@mbabker for sure you noticed the sarcasm from our previous message.

Now leaving aside the preferences of one or another,

laravel and lumen offered us a perfect environment to develop our automated lib suite for auto crud/rest/filtering/aggregations etc.

and we are thankful for that.

Without Eloquent those libs would not exist today.

It is a pity that PHP in on a down slope and new projects or new rewrites are not considering PHP as an option.

Also it is a pity that @taylorotwell did not reply to our emails regarding this lib suite (made of 6 libs by now).

Maybe because Laravel considers that the API battle is lost and it does not deserve any investment from their side.