Documentation on Queue Messages Missing Important Info

[dmagoo]

The following code from the documentation threw me for a loop. Nowhere could I find documentation of what sort of object "listMessages" returns. It happens to be a MessageIterator, which is a subclass of a PaginatedIterator. This is confusing, because, when I query a queue with 20 items with a limit of say, 5, the foreach loop still iterates through all 20. I'm not sure if this is a bug or feature because of lack of documentation. If this is not a bug, it is unclear how to correctly list only the 5 items.

http://php-opencloud.readthedocs.io/en/latest/services/queues/messages.html

$messages = $queue->listMessages(array(
    'marker' => '51db6f78c508f17ddc924357',
    'limit'  => 20,
    'echo'   => true
));

foreach ($messages as $message) {
    echo $message->getId() . PHP_EOL;
}

[dmagoo]

After more digging, I found that there is no way to retrieve easily retrieve the marker for future use. Forums suggest that this is because the marker is abstracted and not needed. If this is true, I'm still confused why marker is allowed as an argument.

In my particular application, I cannot guarantee that messages will be harvested in a single execution of a script, so I would need to maintain a marker. I was able to extract it in a roundabout way as so, but am worried that this could get blown away with an update:

       $url = $messages->constructNextUrl();
       $parts = parse_url($url);
       parse_str($parts['query'], $query);

       if(isset($query['marker'])) {
           $marker = $query['marker'];
       }
      else {
           $marker = null;
      }