PHPackages                             friendsofhyperf/fast-paginate - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. friendsofhyperf/fast-paginate

ActiveLibrary[Utility & Helpers](/categories/utility)

friendsofhyperf/fast-paginate
=============================

Fast paginate for Hyperf.

v3.2.1(1mo ago)366MITPHP

Since Feb 18Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/friendsofhyperf/fast-paginate)[ Packagist](https://packagist.org/packages/friendsofhyperf/fast-paginate)[ Fund](https://hdj.me/sponsors/)[ GitHub Sponsors](https://github.com/huangdijia)[ RSS](/packages/friendsofhyperf-fast-paginate/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (10)Dependencies (10)Versions (40)Used By (0)

Fast Paginate
=============

[](#fast-paginate)

[中文说明](README_CN.md)

> Forked from [hammerstonedev/fast-paginate](https://github.com/hammerstonedev/fast-paginate)

About
-----

[](#about)

Fast Paginate provides faster `limit`/`offset` pagination macros for Hyperf model builders and relations. It is most useful for queries with large offsets, but performance depends on the data and indexes, so benchmark it against the standard paginator for your application.

The component uses an approach similar to a deferred join. It first paginates a query that selects the model's primary key and any selected aliases required for ordering. It then fetches the complete rows for the keys on that page with a second query. Conceptually, the two data queries look like:

```
select contacts.id from contacts limit 15 offset 150000;
select * from contacts where contacts.id in (...);
```

The component executes separate queries rather than putting the limited query inside a `where in`subquery. `fastPaginate()` also runs the normal count query needed for a length-aware paginator; `simpleFastPaginate()` does not run that count query.

Installation
------------

[](#installation)

```
composer require friendsofhyperf/fast-paginate
```

The component depends on Hyperf 3.2 packages. No configuration is required: Hyperf discovers the component's `ConfigProvider`, which registers the pagination macros when the application boots.

Usage
-----

[](#usage)

### Model builders and relations

[](#model-builders-and-relations)

Model builders and relations provide both macros:

```
User::query()->fastPaginate();
User::query()->simpleFastPaginate();

User::first()->posts()->fastPaginate();
User::first()->posts()->simpleFastPaginate();
```

Their signatures match the corresponding Hyperf model-builder pagination methods:

```
fastPaginate($perPage = null, $columns = ['*'], $pageName = 'page', $page = null);
simpleFastPaginate($perPage = null, $columns = ['*'], $pageName = 'page', $page = null);
```

- `$perPage`: items per page; `null` uses the model's configured per-page value.
- `$columns`: columns fetched for the complete rows.
- `$pageName`: query-string parameter used to resolve the current page.
- `$page`: explicit page number; `null` resolves it from the current request.

`fastPaginate()` returns a length-aware paginator with a total count. `simpleFastPaginate()` returns a simple paginator that only determines whether more pages exist. `BelongsToMany` relations keep their hydrated pivot data, and `HasManyThrough` relations are also supported.

### Scout builders

[](#scout-builders)

When `hyperf/scout` is installed, the component also registers `fastPaginate()` on `Hyperf\Scout\Builder`:

```
User::search('Hyperf')->fastPaginate();
```

Its signature is `fastPaginate($perPage = null, $pageName = 'page', $page = null)`. This Scout macro delegates directly to Scout's normal `paginate()` method; it does not use the two-query database optimization. `hyperf/scout` is not required by this component.

Automatic fallbacks
-------------------

[](#automatic-fallbacks)

When the optimized query shape is incompatible, the component automatically calls the corresponding standard `paginate()` or `simplePaginate()` method. This happens when:

- the query contains `having`, `group by`, or `union` clauses;
- `$perPage` is `-1`;
- a selected expression required for ordering contains a `?` binding placeholder.

These fallbacks preserve pagination behavior, but they do not provide the fast-pagination optimization.

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance89

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~31 days

Recently: every ~48 days

Total

39

Last Release

59d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/8337659?v=4)[Deeka Wong](/maintainers/huangdijia)[@huangdijia](https://github.com/huangdijia)

---

Top Contributors

[![huangdijia](https://avatars.githubusercontent.com/u/8337659?v=4)](https://github.com/huangdijia "huangdijia (37 commits)")

---

Tags

hyperfv3.2

### Embed Badge

![Health badge](/badges/friendsofhyperf-fast-paginate/health.svg)

```
[![Health](https://phpackages.com/badges/friendsofhyperf-fast-paginate/health.svg)](https://phpackages.com/packages/friendsofhyperf-fast-paginate)
```

###  Alternatives

[hyperf/database-pgsql

A pgsql handler for hyperf/database.

12333.7k26](/packages/hyperf-database-pgsql)[friendsofhyperf/sentry

The sentry component for Hyperf.

1977.7k](/packages/friendsofhyperf-sentry)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)