Faqosja

Çdo listë që faqoset ka tri metoda. list merr një faqe dhe kthen një OpenEmail\Result\Page. listAll ndjek cursor-in nëpër të gjitha faqet dhe kthen një array të vetëm. iterate i përshkon të njëjtat faqe një element në një kohë dhe kthen një Generator, i cili e merr faqen e radhës vetëm kur arrini aty. Të tria marrin filtrat e listës, limit:, cursor: dhe 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;

Të njëjtat tri emra përsëriten kudo ku një hapësirë emrash ka më shumë se një listë, të emërtuar sipas listës që përshkojnë: listEvents, listAllEvents dhe iterateEvents te emails, listDeliveries, listAllDeliveries dhe iterateDeliveries te webhooks, e kështu me radhë.

Një faqe është e pandryshueshme: vetitë e saj janë readonly. Është gjithashtu IteratorAggregate dhe Countable, ndaj foreach ($page as $item) i përshkon rreshtat e saj dhe count($page) i numëron.

iterate nuk kërkon asgjë derisa të filloni ta përshkoni, dhe e kërkon faqen e radhës vetëm pasi të jetë dhënë çdo element i faqes aktuale, ndaj çdo gjë që ndalon herët i ndal edhe kërkesat: break e përfundon përshkimin, po ashtu edhe kthimi nga funksioni që përmban ciklin.

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

Çdo gjë që ka nevojë për çdo element, si iterator_to_array() e thirrur mbi Generator-in, lexon të gjitha faqet para se të kthehet, ashtu si listAll.

Një cursor është i errët. Ruani nextCursor e faqes së fundit që lexuat dhe jepeni prapa si cursor: për të vazhduar prej andej, në një kërkesë të mëvonshme ose në një proces tjetër. listAll dhe iterate marrin gjithashtu cursor: dhe e nisin përshkimin pas tij.

$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: është madhësia e çdo faqeje, jo një total. Te list është numri i rreshtave që kthehen. Te listAll dhe iterate është numri që kërkon çdo kërkesë, ndaj një vlerë më e madhe do të thotë më pak vajtje-ardhje për të njëjtët rreshta. Çdo listë ka diapazonin dhe parazgjedhjen e vet, më shpesh nga 1 deri në 100 dhe 25 kur nuk dërgoni asgjë, dhe një vlerë jashtë diapazonit refuzohet në vend që të kufizohet. Referenca e çdo liste jep diapazonin e saj.

• —Kur një faqe thotë se hasMore është false.
• —Kur një faqe nuk mbart nextCursor, sepse një faqe që pretendon se ka më shumë pa emërtuar asnjë cursor do të përsëritej në cikël përgjithmonë.
• —Kur API-ja kthen një cursor që shëtitja e ka ndjekur tashmë, për të njëjtën arsye.

Çdo faqe është një GET, ndaj, si çdo lexim, riprovohet më vete para se të hidhet ndonjë përjashtim. Një dështim që u mbijeton riprovave hidhet jashtë listAll, dhe elementet e marra tashmë hidhen poshtë. Te iterate, elementet e faqeve të mëparshme janë dhënë tashmë deri atëherë, ndaj bëjeni atë që kryen cikli të sigurt për t’u ekzekutuar dy herë, ose faqosni me list dhe ruani çdo nextCursor, që një përpjekje e dytë të nisë aty ku ndaloi e para.

threads->list dhe drafts->list, bashkë me listAll dhe iterate të tyre, faqosin me pageToken dhe nextPageToken të API-së në vend të një cursor-i. Klienti e fsheh këtë ndryshim: jepeni token-in si cursor: dhe lexojeni nga 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;

Disa lista përgjigjen me më shumë se rreshta dhe kthejnë një objekt të tyrin nga OpenEmail\Result në vend të Page. Secili është i pandryshueshëm, IteratorAggregate mbi rreshtat e tij dhe Countable.

Disa lista faqosin sipas zhvendosjes (offset), sipas numrit të faqes ose sipas një cursor-i numerik të tyrin, dhe kthejnë trupin e dekoduar ashtu siç erdhi, një array me data, në vend të një Page. Nuk kanë listAll ose iterate, ndaj faqosjen e bëni vetë.

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