पेजिनेशन

पेज होने वाली हर सूची के तीन मेथड हैं। list एक पेज लाता है और एक OpenEmail\Result\Page लौटाता है। listAll हर पेज में cursor का पीछा करता है और एक array लौटाता है। 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;

जहाँ भी किसी namespace में एक से ज़्यादा सूची हो, वही तीन नाम दोहराए जाते हैं, उस सूची के नाम पर जिस पर वे चलते हैं: emails पर listEvents, listAllEvents और iterateEvents, webhooks पर listDeliveries, listAllDeliveries और iterateDeliveries, इत्यादि।

पेज अपरिवर्तनीय है: उसकी properties readonly हैं। यह IteratorAggregate और Countable भी है, इसलिए foreach ($page as $item) उसकी पंक्तियों पर चलता है और count($page) उन्हें गिनता है।

iterate तब तक कुछ नहीं माँगता जब तक आप उस पर चलना शुरू न करें, और अगला पेज तभी माँगता है जब मौजूदा पेज का हर आइटम yield हो चुका हो, इसलिए जल्दी रुकने वाली कोई भी चीज़ रिक्वेस्ट भी रोक देती है: break चलना ख़त्म करता है, और लूप वाले फ़ंक्शन से return करना भी।

$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 पर कॉल किया गया iterator_to_array(), वह लौटने से पहले हर पेज पढ़ती है, जैसा listAll करता है।

cursor अपारदर्शी होता है। आपने जो आख़िरी पेज पढ़ा उसका 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 लौटा दे जिसका पालन walk पहले ही कर चुका है, उसी कारण से।

हर पेज एक GET है, इसलिए कुछ भी throw होने से पहले उसे किसी भी read की तरह अपने आप retry किया जाता है। retry के बाद भी बची विफलता listAll से throw होती है, और पहले से लाए गए आइटम छोड़ दिए जाते हैं। iterate में तब तक पहले के पेजों के आइटम yield हो चुके होते हैं, इसलिए लूप जो करता है उसे दो बार चलाने में सुरक्षित बनाएँ, या list से पेज करें और हर nextCursor रखें ताकि दूसरा प्रयास वहीं से शुरू हो सके जहाँ पहला रुका था।

threads->list और drafts->list, अपने listAll और iterate के साथ, cursor के बजाय API के pageToken और nextPageToken से पेज करते हैं। क्लाइंट यह अंतर छिपा देता है: टोकन को 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 वाला एक array। इनमें 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'] !== []);