# Pagination

PayMongo returns lists a page at a time. A `list()` method returns the first page, and the page fetches the next one for you. You never pass a cursor by hand.

## Pages

These return a `Luigel\Paymongo\Pagination\CursorPage`: `payments()->list()`, `refunds()->list()`, `links()->list()`, `paymentLinks()->list()`, `paymentLinks()->payments()`, `plans()->list()`, `subscriptions()->list()`, `webhooks()->list()` and `disputes()->list()`.

```php
use Luigel\Paymongo\Facades\Paymongo;

$page = Paymongo::payments()->list(['limit' => 50]); // CursorPage<Payment>

foreach ($page as $payment) {
    $payment->id;
}

count($page);    // payments on this page
$page->first();  // ?Payment
$page->items;    // list<Payment>
$page->hasMore;  // bool: is there another page?

$next = $page->nextPage(); // ?CursorPage: requested with after = the last payment's id
```

- Iterate the page, or read `items`, for what is on it. It also has `count()`, `first()` and `toArray()`.
- `hasMore` says whether PayMongo has another page.
- `nextPage()` requests the next page, and returns `null` on the last one. It repeats your parameters, with `after` set to the id of the last item on this page.
- `limit` sets the page size. PayMongo returns 10 items when you leave it out; see its [List all Payments](https://docs.paymongo.com/reference/list-all-payments) reference for this and the other parameters each endpoint takes.

## Every item on every page

`lazy()` walks every page as a Laravel `LazyCollection`, requesting each page only when you reach it, so you can stop early without fetching the rest:

```php
use Luigel\Paymongo\Data\Payment;
use Luigel\Paymongo\Enums\PaymentStatus;
use Luigel\Paymongo\Facades\Paymongo;

// Every payment on every page, fetching the next page only when you reach it.
$collected = Paymongo::payments()->list(['limit' => 100])
    ->lazy() // LazyCollection<int, Payment>
    ->filter(fn (Payment $payment): bool => $payment->status === PaymentStatus::Paid)
    ->sum(fn (Payment $payment): int => $payment->amount ?? 0); // centavos
```

Walking a long history takes one request per page. Narrow the list with the endpoint's filters where it has them, such as `payment_id` on refunds.

## Payouts

`payouts()->list()` and `payouts()->transactions()` return a `Luigel\Paymongo\Pagination\CursorTokenPage`, because the Payouts API pages with cursor tokens instead of `has_more`. It iterates, counts, and has `first()`, `nextPage()` and `lazy()` in the same way, and adds:

```php
use Luigel\Paymongo\Facades\Paymongo;

$page = Paymongo::payouts()->list(['limit' => 20]); // CursorTokenPage<Payout>

$page->nextCursor;                     // ?string, null on the last page
$page->prevCursor;                     // ?string
$page->meta['total_records'] ?? null;  // totals PayMongo sends with the page

$page = $page->nextPage();             // ?CursorTokenPage
```

`nextPage()` is `null` when `nextCursor` is. See [Payouts](/payouts.md).

## Lists that are not paged

`customers()->paymentMethods()` returns every item at once, as a plain array.