صفحه‌بندی

هر فهرستی که صفحه‌بندی دارد سه متد دارد. list یک صفحه را می‌گیرد و یک OpenEmail\Result\Page برمی‌گرداند. listAll cursor را در همهٔ صفحه‌ها دنبال می‌کند و یک آرایه برمی‌گرداند. iterate همان صفحه‌ها را هر بار یک مورد می‌پیماید و یک Generator برمی‌گرداند، که صفحهٔ بعد را فقط وقتی به آن برسید می‌گیرد. هر سه، فیلترهای فهرست، limit:، cursor: و apiKey: را می‌گیرند.

$page = $client->emails->list(status: 'failed', limit: 50); foreach ($page as $email) {    echo $email['id'], ' ', $email['lastError'] ?? '', PHP_EOL;} $failures = $client->emails->listAll(status: 'failed'); foreach ($client->emails->iterate(status: 'failed') as $email) {    echo $email['id'], PHP_EOL;} echo count($failures), ' ', $page->hasMore ? 'more to come' : 'that is all', PHP_EOL;

همین سه نام هر جا که یک فضای نام بیش از یک فهرست دارد تکرار می‌شوند، و به نام فهرستی که می‌پیمایند نام‌گذاری شده‌اند: listEvents، listAllEvents و iterateEvents روی emails، listDeliveries، listAllDeliveries و iterateDeliveries روی webhooks، و مانند آن.

صفحه تغییرناپذیر است: ویژگی‌هایش readonly هستند. همچنین IteratorAggregate و Countable است، پس foreach ($page as $item) ردیف‌هایش را می‌پیماید و count($page) آن‌ها را می‌شمارد.

iterate تا وقتی پیمایشش را شروع نکنید چیزی نمی‌خواهد، و صفحهٔ بعد را فقط وقتی می‌خواهد که همهٔ موردهای صفحهٔ کنونی yield شده باشند، پس هر چیزی که زودتر بایستد درخواست‌ها را هم متوقف می‌کند: break پیمایش را پایان می‌دهد، و بازگشتن از تابعی که حلقه را در بر دارد هم همین‌طور.

$latest = []; foreach ($client->emails->iterate(status: 'failed', limit: 100) as $email) {    $latest[] = $email;     if (count($latest) === 10) {        break;    }} $invoice = null; foreach ($client->emails->iterate(status: 'failed') as $email) {    if (($email['tags']['invoice'] ?? null) === 'inv_2026_09_4192') {        $invoice = $email;         break;    }} echo count($latest), ' ', $invoice['id'] ?? 'not found', PHP_EOL;

هر چیزی که به همهٔ موردها نیاز دارد، مانند iterator_to_array() که روی Generator فراخوانی شود، پیش از بازگشت همهٔ صفحه‌ها را می‌خواند، همان‌طور که listAll می‌خواند.

cursor مبهم (opaque) است. nextCursor آخرین صفحه‌ای را که خوانده‌اید نگه دارید و آن را به‌عنوان cursor: پس بدهید تا از همان‌جا ادامه دهید، در درخواستی بعدی یا در فرایندی دیگر. listAll و iterate هم cursor: را می‌گیرند و پیمایششان را پس از آن آغاز می‌کنند.

$firstPage = $client->emails->list(status: 'failed', limit: 25);$saved = $firstPage->nextCursor; if ($saved !== null) {    $rest = $client->emails->listAll(status: 'failed', cursor: $saved);    echo count($rest), PHP_EOL;}

limit: اندازهٔ هر صفحه است، نه یک مجموع. روی list تعداد ردیف‌هایی است که برمی‌گردند. روی listAll و iterate تعدادی است که هر درخواست می‌خواهد، پس مقدار بزرگ‌تر یعنی رفت‌وبرگشت‌های کمتر برای همان ردیف‌ها. هر فهرست بازه و پیش‌فرض خودش را دارد، بیشتر وقت‌ها 1 تا 100 با 25 وقتی چیزی نفرستید، و مقدار بیرون از بازه رد می‌شود، نه اینکه به مرز بازه بریده شود. مرجع هر فهرست بازه‌اش را می‌گوید.

• —وقتی صفحه‌ای بگوید hasMore برابر false است.
• —وقتی صفحه‌ای هیچ nextCursor نداشته باشد، چون صفحه‌ای که ادعای ادامه کند اما هیچ cursorی را نام نبرد تا ابد حلقه می‌زد.
• —وقتی API یک cursor را پس بدهد که پیمایش پیش‌تر دنبالش کرده است، به همان دلیل.

هر صفحه یک GET است، پس مانند هر خواندنی پیش از آنکه چیزی پرتاب شود جداگانه دوباره تلاش می‌شود. شکستی که پس از تلاش‌های دوباره باقی بماند از listAll بیرون پرتاب می‌شود، و موردهایی که تا آن زمان گرفته شده‌اند دور ریخته می‌شوند. در iterate، موردهای صفحه‌های پیشین تا آن زمان yield شده‌اند، پس کاری را که حلقه انجام می‌دهد طوری بنویسید که دو بار اجرا شدنش بی‌خطر باشد، یا با list صفحه‌بندی کنید و هر nextCursor را نگه دارید تا تلاش دوم بتواند از همان جایی که تلاش نخست ایستاد آغاز شود.

threads->list و drafts->list، همراه با listAll و iterate آن‌ها، به‌جای cursor با pageToken و nextPageToken در API صفحه‌بندی می‌کنند. کلاینت این تفاوت را پنهان می‌کند: توکن را به‌عنوان cursor: بدهید و آن را از nextCursor بخوانید.

$page = $client->threads->list(folder: 'inbox', limit: 50);$later = $page->hasMore ? $client->threads->list(folder: 'inbox', limit: 50, cursor: $page->nextCursor) : null; echo count($page), ' ', $later === null ? 0 : count($later), PHP_EOL;

چند فهرست با چیزی بیش از ردیف‌ها پاسخ می‌دهند، و به‌جای Page یک شیء مخصوص خود از OpenEmail\Result برمی‌گردانند. هرکدام تغییرناپذیر است، روی ردیف‌هایش IteratorAggregate است و Countable هم هست.

برخی فهرست‌ها با offset، با شمارهٔ صفحه یا با cursor عددیِ مخصوص خودشان صفحه‌بندی می‌کنند، و به‌جای یک Page، بدنهٔ تجزیه‌شده را همان‌طور که آمده برمی‌گردانند: یک آرایه با data. listAll یا iterate ندارند، پس صفحه‌بندی‌شان را خودتان انجام می‌دهید.

$offset = 0; do {    $batch = $client->subscriptions->list(status: 'active', limit: 50, offset: $offset);     foreach ($batch['data'] as $row) {        echo $row['senderEmail'], ' ', $row['total'], PHP_EOL;    }     $offset += count($batch['data']);} while ($batch['hasMore'] && $batch['data'] !== []);