/**
* Retrieve new messages from the topic.
*
* Example:
* ```
* $subscription = $pubsub->subscription('my-new-subscription');
* $messages = $subscription->pull();
* foreach ($messages as $message) {
* echo $message['data'];
* }
* ```
*
* @see https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/pull Pull Subscriptions
*
* @param array $options [optional] {
* Configuration Options
*
* @type bool $returnImmediately If set, the system will respond
* immediately, even if no messages are available. Otherwise,
* wait until new messages are available.
* @type int $maxMessages Limit the amount of messages pulled.
* }
* @codingStandardsIgnoreStart
* @return \Generator<array> [ReceivedMessage](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/pull#ReceivedMessage)
* @codingStandardsIgnoreEnd
*/
public function pull(array $options = [])
{
$options['pageToken'] = null;
$options['returnImmediately'] = isset($options['returnImmediately']) ? $options['returnImmediately'] : false;
$options['maxMessages'] = isset($options['maxMessages']) ? $options['maxMessages'] : self::MAX_MESSAGES;
do {
$response = $this->connection->pull($options + ['subscription' => $this->name]);
if (isset($response['receivedMessages'])) {
foreach ($response['receivedMessages'] as $message) {
(yield $message);
}
}
// If there's a page token, we'll request the next page.
$options['pageToken'] = isset($response['nextPageToken']) ? $response['nextPageToken'] : null;
} while ($options['pageToken']);
}
