Pagination

Every paginated collection in the SDK is exposed three ways. They hit the same endpoint and differ only in how much they buffer.

use Envless\Envless;

$envless = new Envless();
$page = $envless->products->list(limit: 50);

echo count($page->items), PHP_EOL;
echo $page->pagination['limit'], ' ', $page->pagination['offset'], PHP_EOL;
echo $page->totalCount(), ' ', $page->hasMore() ? 'more' : 'last page', PHP_EOL;

use Envless\Envless;

$envless = new Envless();
$everything = $envless->products->listAll();

echo count($everything), PHP_EOL;

use Envless\Envless;

$envless = new Envless();

foreach ($envless->products->iterate() as $product) {
    if ($product['slug'] === 'billing') {
        break;
    }

    echo $product['name'], PHP_EOL;
}

A Generator fetches the next page only when the loop gets there, and nothing at all is requested until the loop starts. That makes it the right shape for a long export: memory stays at one page however large the collection is.

use Envless\Envless;

$envless = new Envless();
$names = [];

foreach ($envless->products->iterate() as $product) {
    $names[] = $product['name'];

    if (count($names) === 10) {
        break;
    }
}

echo implode(', ', $names), PHP_EOL;

An Envless\Result\Page has items and pagination as readonly properties, plus hasMore() and totalCount(). It can be counted and looped over directly, and json_encode() turns it back into items and pagination. Its PHPStan type is generic over the item, so $page->items is a list<ProductResource> to PHPStan and Psalm.

Options#

List methods take these as named arguments, after their positional slugs. Each list accepts only the options its route reads, so an option a route ignores is an Error for an unknown named parameter:

How the walk terminates#

listAll and iterate stop on either of two conditions, which matters because it makes them safe against a server that keeps saying hasMore:

The offset advances by the number of items actually received, not by limit, so a short page does not skip rows. A failure on any page fails the whole listAll call, and the rows it had already collected are lost; iterate has already handed over the earlier items, so it throws at the page that failed.

Secondary collections#

A namespace can paginate more than one collection. Those get their own trio, named after what they read.

Two endpoints look like lists but are not paginated, because the whole set is small and fixed. Both return a plain array rather than a page:

One collection carries an extra field#

products->access->list() returns an Envless\Result\ProductAccessPage, which is a normal page plus the product's privacy flag, read as isPrivate. That flag tells you whether the grants matter at all: on a public product every member has access and the list is informational.

use Envless\Envless;

$envless = new Envless();
$access = $envless->products->access->list('internal-tools');

if (!$access->isPrivate) {
    echo 'Public product, every member already has access', PHP_EOL;
}

foreach ($access->items as $entry) {
    echo $entry['id'], PHP_EOL;
}

Counting without fetching#

totalCount() is the size of the full filtered set, not the page, so a single one-row request is enough to count.

use Envless\Envless;

$envless = new Envless();

echo $envless->members->list(limit: 1)->totalCount(), ' members', PHP_EOL;