feat: add dead letter queue samples

pubsub/api/composer.json

@@ -1,13 +1,17 @@
 {
     "require": {
         "php": ">=5.4",
-        "google/cloud-pubsub": "^1.27",
+        "google/cloud-pubsub": "^1.29",
         "symfony/console": " ^3.0"
     },
     "autoload": {
         "files": [
             "src/create_subscription.php",
             "src/create_topic.php",
+            "src/dead_letter_create_subscription.php",
+            "src/dead_letter_delivery_attempt.php",
+            "src/dead_letter_remove.php",
+            "src/dead_letter_update_subscription.php",
             "src/create_push_subscription.php",
             "src/delete_subscription.php",
             "src/delete_topic.php",

pubsub/api/pubsub.php

@@ -138,6 +138,108 @@
         }
     });
 
+    $application->add(new Command('dead-letter'))
+        ->setDescription('Manage Dead Letter Policies for Pub\Sub')
+        ->setHelp(<<<EOF
+    The <info>%command.name%</info> command manages Pub\Sub dead letter policies.
+
+    <info>php %command.full_name% create --project my-project
+        --topic my-topic
+        --subscription my-subscription
+        --dead-letter-topic my-dead-letter-topic</info>
+
+    <info>php %command.full_name% update --project my-project
+        --topic my-topic
+        --subscription my-subscription
+        --dead-letter-topic my-dead-letter-topic</info>
+
+    <info>php %command.full_name% remove --project my-project
+        --topic my-topic</info>
+
+    <info>php %command.full_name% pull --project my-project
+        --topic my-topic --subscription my-subscription</info>
+
+EOF
+        )
+        ->addArgument('action', InputArgument::REQUIRED, 'The action to take')
+        ->addOption('project', null, InputOption::VALUE_REQUIRED, 'Your Google Cloud project ID.')
+        ->addOption('topic', null, InputOption::VALUE_REQUIRED, 'The topic name.')
+        ->addOption('subscription', null, InputOption::VALUE_OPTIONAL, 'The subscription name.')
+        ->addOption('dead-letter-topic', null, InputOption::VALUE_OPTIONAL, 'The dead letter topic name.')
+        ->addOption('message', null, InputOption::VALUE_OPTIONAL, 'The value of a pubsub message.')
+        ->setCode(function ($input, $output) {
+            $action = $input->getArgument('action');
+            $projectId = $input->getOption('project');
+            $topicName = $input->getOption('topic');
+            $subscriptionName = $input->getOption('subscription');
+            $deadLetterTopic = $input->getOption('dead-letter-topic');
+            $message = $input->getOption('message');
+
+            switch ($action) {
+                case 'create':
+                    if (!$subscriptionName || !$deadLetterTopic) {
+                        throw new \RuntimeException(
+                            'Subscription Name and Dead Letter Topic are required to create a subscription.'
+                        );
+                    }
+
+                    dead_letter_create_subscription(
+                        $projectId,
+                        $topicName,
+                        $subscriptionName,
+                        $deadLetterTopic
+                    );
+                break;
+
+                case 'update':
+                    if (!$subscriptionName || !$deadLetterTopic) {
+                        throw new \RuntimeException(
+                            'Subscription Name and Dead Letter Topic are required to update a subscription.'
+                        );
+                    }
+
+                    dead_letter_update_subscription(
+                        $projectId,
+                        $topicName,
+                        $subscriptionName,
+                        $deadLetterTopic
+                    );
+                break;
+
+                case 'remove':
+                    if (!$subscriptionName) {
+                        throw new \RuntimeException(
+                            'Subscription Name is required to remove a dead letter policy.'
+                        );
+                    }
+
+                    dead_letter_remove(
+                        $projectId,
+                        $topicName,
+                        $subscriptionName
+                    );
+                break;
+
+                case 'pull':
+                    if (!$subscriptionName || !$message) {
+                        throw new \RuntimeException(
+                            'Subscription Name and message is required to pull messages.'
+                        );
+                    }
+
+                    dead_letter_delivery_attempt(
+                        $projectId,
+                        $topicName,
+                        $subscriptionName,
+                        $message
+                    );
+                break;
+
+                default:
+                    throw new \RuntimeException(sprintf('%s is not a valid action', $action));
+            }
+        });
+
 if (getenv('PHPUNIT_TESTS') === '1') {
     return $application;
 }

pubsub/api/src/dead_letter_create_subscription.php

@@ -0,0 +1,58 @@
+<?php
+/**
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/blob/master/pubsub/api/README.md
+ */
+
+namespace Google\Cloud\Samples\PubSub;
+
+# [START pubsub_dead_letter_create_subscription]
+use Google\Cloud\PubSub\PubSubClient;
+
+/**
+ * Creates a Pub/Sub subscription with dead letter policy enabled.
+ *
+ * @param string $projectId  The Google project ID.
+ * @param string $topicName  The Pub/Sub topic name.
+ * @param string $subscriptionName  The Pub/Sub subscription name.
+ * @param string $deadLetterTopicName The Pub/Sub topic to use for dead letter policy.
+ */
+function dead_letter_create_subscription($projectId, $topicName, $subscriptionName, $deadLetterTopicName)
+{
+    $pubsub = new PubSubClient([
+        'projectId' => $projectId,
+    ]);
+
+    $topic = $pubsub->topic($topicName);
+    $deadLetterTopic = $pubsub->topic($deadLetterTopicName);
+
+    $subscription = $topic->subscribe($subscriptionName, [
+        'deadLetterPolicy' => [
+            'deadLetterTopic' => $deadLetterTopic
+        ]
+    ]);
+
+    printf(
+        'Subscription %s created with dead letter topic %s' . PHP_EOL,
+        $subscription->name(),
+        $deadLetterTopic->name()
+    );
+}
+# [END pubsub_dead_letter_create_subscription]

pubsub/api/src/dead_letter_delivery_attempt.php

@@ -0,0 +1,60 @@
+<?php
+/**
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/blob/master/pubsub/api/README.md
+ */
+
+namespace Google\Cloud\Samples\PubSub;
+
+# [START pubsub_dead_letter_delivery_attempt]
+use Google\Cloud\PubSub\Message;
+use Google\Cloud\PubSub\PubSubClient;
+
+/**
+ * Get the delivery attempt from a pulled message.
+ *
+ * @param string $projectId  The Google project ID.
+ * @param string $topicName  The Pub/Sub topic name.
+ * @param string $subscriptionName  The Pub/Sub subscription name.
+ * @param string $message The contents of a pubsub message data field.
+ */
+function dead_letter_delivery_attempt($projectId, $topicName, $subscriptionName, $message)
+{
+    $pubsub = new PubSubClient([
+        'projectId' => $projectId,
+    ]);
+
+    $topic = $pubsub->topic($topicName);
+
+    // publish test message
+    $topic->publish(new Message([
+        'data' => $message
+    ]));
+
+    $subscription = $topic->subscription($subscriptionName);
+    $messages = $subscription->pull();
+
+    foreach ($messages as $message) {
+        printf('Received message %s' . PHP_EOL, $message->data());
+        printf('Delivery attempt %d' . PHP_EOL, $message->deliveryAttempt());
+    }
+    print('Done' . PHP_EOL);
+}
+# [END pubsub_dead_letter_delivery_attempt]

pubsub/api/src/dead_letter_remove.php

@@ -0,0 +1,58 @@
+<?php
+/**
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/blob/master/pubsub/api/README.md
+ */
+
+namespace Google\Cloud\Samples\PubSub;
+
+# [START pubsub_dead_letter_remove]
+use Google\Cloud\PubSub\PubSubClient;
+
+/**
+ * Remove dead letter policy from an existing subscription.
+ *
+ * @param string $projectId  The Google project ID.
+ * @param string $topicName  The Pub/Sub topic name.
+ * @param string $subscriptionName  The Pub/Sub subscription name.
+ */
+function dead_letter_remove($projectId, $topicName, $subscriptionName)
+{
+    $pubsub = new PubSubClient([
+        'projectId' => $projectId,
+    ]);
+
+    $topic = $pubsub->topic($topicName);
+
+    $subscription = $topic->subscription($subscriptionName);
+
+    // Provide deadLetterPolicy in the update mask, but omit from update fields to unset.
+    $subscription->update([], [
+        'updateMask' => [
+            'deadLetterPolicy'
+        ]
+    ]);
+
+    printf(
+        'Removed dead letter topic from subscription %s' . PHP_EOL,
+        $subscription->name()
+    );
+}
+# [END pubsub_dead_letter_remove]

pubsub/api/src/dead_letter_update_subscription.php

@@ -0,0 +1,58 @@
+<?php
+/**
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/blob/master/pubsub/api/README.md
+ */
+
+namespace Google\Cloud\Samples\PubSub;
+
+# [START pubsub_dead_letter_update_subscription]
+use Google\Cloud\PubSub\PubSubClient;
+
+/**
+ * Set the dead letter policy on an existing subscription.
+ *
+ * @param string $projectId  The Google project ID.
+ * @param string $topicName  The Pub/Sub topic name.
+ * @param string $deadLetterTopicName The Pub/Sub topic to use for dead letter policy.
+ */
+function dead_letter_update_subscription($projectId, $topicName, $subscriptionName, $deadLetterTopicName)
+{
+    $pubsub = new PubSubClient([
+        'projectId' => $projectId,
+    ]);
+
+    $topic = $pubsub->topic($topicName);
+    $deadLetterTopic = $pubsub->topic($deadLetterTopicName);
+
+    $subscription = $topic->subscription($subscriptionName);
+    $subscription->update([
+        'deadLetterPolicy' => [
+            'deadLetterTopic' => $deadLetterTopic
+        ]
+    ]);
+
+    printf(
+        'Subscription %s updated with dead letter topic %s' . PHP_EOL,
+        $subscription->name(),
+        $deadLetterTopic->name()
+    );
+}
+# [END pubsub_dead_letter_update_subscription]