Sayfalama

Sayfalanan her listenin üç metodu vardır. list bir sayfa getirir ve bir OpenEmail\Result\Page döndürür. listAll cursor'ı tüm sayfalar boyunca izler ve tek bir dizi döndürür. iterate aynı sayfaları her seferinde bir öğe olacak şekilde dolaşır ve bir Generator döndürür; bu, bir sonraki sayfayı ancak oraya vardığınızda getirir. Üçü de listenin filtrelerini, limit:, cursor: ve apiKey: alır.

$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;

Bir ad alanında birden fazla liste olduğu her yerde aynı üç ad, dolaştıkları listeye göre adlandırılarak tekrarlanır: emails üzerinde listEvents, listAllEvents ve iterateEvents; webhooks üzerinde listDeliveries, listAllDeliveries ve iterateDeliveries ve benzerleri.

Bir sayfa değişmezdir: özellikleri readonly olarak tanımlıdır. Aynı zamanda IteratorAggregate ve Countable arayüzlerini de uygular; bu yüzden foreach ($page as $item) satırlarını dolaşır, count($page) ise onları sayar.

iterate, siz onu dolaşmaya başlayana kadar hiçbir şey istemez ve bir sonraki sayfayı ancak geçerli sayfanın tüm öğeleri verildikten sonra ister; bu yüzden erken duran her şey istekleri de durdurur: break dolaşmayı bitirir, döngüyü içeren fonksiyondan dönmek de öyle.

$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;

Generator üzerinde çağrılan iterator_to_array() gibi her öğeye ihtiyaç duyan her şey, listAll gibi dönmeden önce tüm sayfaları okur.

Bir cursor opaktır. Okuduğunuz son sayfanın nextCursor değerini saklayın ve daha sonraki bir istekte ya da başka bir süreçte oradan devam etmek için onu cursor: olarak geri geçirin. listAll ve iterate de cursor: alır ve dolaşmaya onun ardından başlar.

$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: toplam değil, her sayfanın boyutudur. list üzerinde kaç satır döneceğidir. listAll ve iterate üzerinde her isteğin kaç satır istediğidir; bu yüzden daha büyük bir değer aynı satırlar için daha az gidiş dönüş anlamına gelir. Her listenin kendi aralığı ve varsayılanı vardır; çoğunlukla 1 ile 100 arasıdır ve hiçbir şey göndermezseniz 25'tir. Aralık dışındaki bir değer kırpılmaz, reddedilir. Her listenin başvuru sayfası kendi aralığını belirtir.

• —Bir sayfa hasMore değerinin false olduğunu söylediğinde.
• —Bir sayfa nextCursor taşımadığında, çünkü devamı olduğunu iddia edip hiçbir cursor belirtmeyen bir sayfa sonsuza dek döngüye girerdi.
• —API, gezinmenin zaten izlediği bir cursor'ı geri verdiğinde, aynı nedenle.

Her sayfa bir GET'tir; bu yüzden herhangi bir hata fırlatılmadan önce her okuma gibi kendi başına yeniden denenir. Yeniden denemelerden sonra da süren bir hata listAll dışına fırlatılır ve o ana kadar getirilen öğeler atılır. iterate içinde ise önceki sayfaların öğeleri o zamana kadar zaten verilmiştir; bu yüzden döngünün yaptığı işi iki kez çalışmaya karşı güvenli hâle getirin ya da list ile sayfalayıp her nextCursor değerini saklayın, böylece ikinci bir deneme ilkinin durduğu yerden başlayabilir.

threads->list ve drafts->list, listAll ve iterate metotlarıyla birlikte, bir cursor yerine API'nin pageToken ve nextPageToken değerleriyle sayfalar. İstemci bu farkı gizler: tokenı cursor: olarak geçirin ve nextCursor üzerinden okuyun.

$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;

Birkaç liste satırlardan fazlasıyla yanıt verir ve Page yerine OpenEmail\Result içinden kendine ait bir nesne döndürür. Her biri değişmezdir, satırları üzerinde IteratorAggregate ve Countable arayüzlerini uygular.

Bazı listeler ofsetle, sayfa numarasıyla ya da kendilerine ait sayısal bir cursor ile sayfalar ve kodu çözülmüş gövdeyi bir Page yerine geldiği gibi, data içeren bir dizi olarak döndürür. Bunların listAll ya da iterate metotları yoktur, bu yüzden sayfalamayı kendiniz yaparsınız.

$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'] !== []);