Page.php

<?php

declare(strict_types=1);

namespace Rapttor\WhopSdk\Http;

use Rapttor\WhopSdk\Resources\AbstractResource;

/**
 * A single page of cursor-paginated API results.
 *
 * Implements {@see \IteratorAggregate} so you can iterate through **all** items
 * across every page transparently:
 *
 * ```php
 * foreach ($client->payments->list(['company_id' => 'biz_xxx']) as $payment) {
 *     // Pages are fetched on demand as the iterator progresses
 * }
 * ```
 *
 * @template TItem of array<string, mixed>
 * @implements \IteratorAggregate<int, TItem>
 */
final class Page implements \IteratorAggregate, \Countable
{
    /**
     * @param list<TItem>                   $data
     * @param array<string, mixed>          $requestParams
     */
    public function __construct(
        private readonly array $data,
        private readonly ?string $nextCursor,
        private readonly AbstractResource $resource,
        private readonly array $requestParams,
    ) {}

    // ── Data access ────────────────────────────────────────────────────────────

    /**
     * Items on the current page.
     *
     * @return list<TItem>
     */
    public function getData(): array
    {
        return $this->data;
    }

    // ── Pagination ─────────────────────────────────────────────────────────────

    public function hasNextPage(): bool
    {
        return $this->nextCursor !== null;
    }

    /**
     * Cursor info for the next page, or null if this is the last page.
     *
     * @return array{after: string}|null
     */
    public function nextPageInfo(): ?array
    {
        if ($this->nextCursor === null) {
            return null;
        }

        return ['after' => $this->nextCursor];
    }

    /**
     * Fetch and return the next page, or null if there are no more pages.
     *
     * @return static<TItem>|null
     */
    public function getNextPage(): ?static
    {
        if ($this->nextCursor === null) {
            return null;
        }

        /** @var static<TItem> */
        return $this->resource->list(
            array_merge($this->requestParams, ['after' => $this->nextCursor])
        );
    }

    // ── IteratorAggregate ──────────────────────────────────────────────────────

    /**
     * Iterate all items across all pages, fetching new pages as needed.
     *
     * @return \Traversable<int, TItem>
     */
    public function getIterator(): \Traversable
    {
        yield from $this->data;

        $page = $this;

        while ($page->hasNextPage()) {
            $page = $page->getNextPage();

            if ($page === null) {
                break;
            }

            yield from $page->getData();
        }
    }

    // ── Countable ──────────────────────────────────────────────────────────────

    /** Returns the number of items on **this** page only. */
    public function count(): int
    {
        return count($this->data);
    }

    // ── Factory ────────────────────────────────────────────────────────────────

    /**
     * Construct a Page from a raw API response array.
     *
     * @param array<string, mixed>  $response
     * @param array<string, mixed>  $requestParams
     * @return static<array<string, mixed>>
     */
    public static function fromResponse(
        array $response,
        AbstractResource $resource,
        array $requestParams,
    ): static {
        /** @var list<array<string, mixed>> $data */
        $data       = $response['data'] ?? [];
        $nextCursor = $response['page_info']['end_cursor'] ?? null;

        /** @var static<array<string, mixed>> */
        return new static($data, $nextCursor, $resource, $requestParams);
    }
}