Add tag_subscribers method

src/ConvertKit_API_Traits.php

@@ -602,6 +602,43 @@ public function update_tag_name(int $tag_id, string $name)
         return $this->put(sprintf('tags/%s', $tag_id), ['name' => $name]);
     }
 
+    /**
+     * Tags the given subscribers with the given existing Tags.
+     *
+     * @param array<int,array<string>> $taggings     Taggings, in the format:
+     *   [
+     *    [
+     *      "tag_id" => 0,
+     *      "subscriber_id" => 0
+     *    ],
+     *    [
+     *      "tag_id" => 1,
+     *      "subscriber_id" => 1
+     *    ],
+     *   ].
+     * @param string                   $callback_url URL to notify for large batch size when async processing complete.
+     *
+     * @since 2.2.1
+     *
+     * @see https://developers.kit.com/api-reference/tags/bulk-tag-subscribers
+     *
+     * @return false|mixed
+     */
+    public function tag_subscribers(array $taggings, string $callback_url = '')
+    {
+        // Build parameters.
+        $options = ['taggings' => $taggings];
+        if (!empty($callback_url)) {
+            $options['callback_url'] = $callback_url;
+        }
+
+        // Send request.
+        return $this->post(
+            'bulk/tags/subscribers',
+            $options
+        );
+    }
+
     /**
      * Tags a subscriber with the given existing Tag.
      *

tests/ConvertKitAPIKeyTest.php

@@ -247,41 +247,78 @@ public function testCreateTags()
     }
 
     /**
-     * Test that create_tags() throws a ClientException when attempting
-     * to create blank tags, as this is only supported using OAuth.
+     * Skip this test from ConvertKitAPITest, as testCreateTags() above
+     * confirms a ClientException is thrown.
      *
      * @since   2.2.0
      *
      * @return void
      */
     public function testCreateTagsBlank()
     {
-        $this->expectException(ClientException::class);
-        $result = $this->api->create_tags([
-            '',
-            '',
-        ]);
+        $this->markTestSkipped('testCreateTags() above confirms a ClientException is thrown.');
     }
 
     /**
-     * Test that create_tags() throws a ClientException when creating
-     * tags that already exists, as this is only supported using OAuth.
+     * Skip this test from ConvertKitAPITest, as testCreateTags() above
+     * confirms a ClientException is thrown.
      *
      * @since   2.2.0
      *
      * @return void
      */
     public function testCreateTagsThatExist()
+    {
+        $this->markTestSkipped('testCreateTags() above confirms a ClientException is thrown.');
+    }
+
+    /**
+     * Test that tag_subscribers() throws a ClientException when attempting
+     * to tag subscribers, as this is only supported using OAuth.
+     *
+     * @since   2.2.1
+     *
+     * @return void
+     */
+    public function testTagSubscribers()
     {
         $this->expectException(ClientException::class);
-        $result = $this->api->create_tags(
+        $result = $this->api->tag_subscribers(
             [
-                $_ENV['CONVERTKIT_API_TAG_NAME'],
-                $_ENV['CONVERTKIT_API_TAG_NAME_2'],
+                [
+                    'tag_id' => (int) $_ENV['CONVERTKIT_API_TAG_ID'],
+                    'subscriber_id' => (int) $_ENV['CONVERTKIT_API_SUBSCRIBER_ID']
+                ],
             ]
         );
     }
 
+    /**
+     * Skip this test from ConvertKitAPITest, as testTagSubscribers() above
+     * confirms a ClientException is thrown.
+     *
+     * @since   2.2.1
+     *
+     * @return void
+     */
+    public function testTagSubscribersWithInvalidTagID()
+    {
+        $this->markTestSkipped('testTagSubscribers() above confirms a ClientException is thrown.');
+    }
+
+    /**
+     * Skip this test from ConvertKitAPITest, as testTagSubscribers() above
+     * confirms a ClientException is thrown.
+     *
+     * @since   2.2.1
+     *
+     * @return void
+     */
+    public function testTagSubscribersWithInvalidSubscriberID()
+    {
+        $this->markTestSkipped('testTagSubscribers() above confirms a ClientException is thrown.');
+    }
+
     /**
      * Test that add_subscribers_to_forms() throws a ClientException when
      * attempting to add subscribers to forms, as this is only supported

tests/ConvertKitAPITest.php

@@ -1818,6 +1818,125 @@ public function testGetSubscriberStatsWithInvalidSubscriberID()
         $result = $this->api->get_subscriber_stats(12345);
     }
 
+    /**
+     * Test that tag_subscribers() returns the expected data.
+     *
+     * @since   2.2.1
+     *
+     * @return void
+     */
+    public function testTagSubscribers()
+    {
+        // Create subscribers.
+        $subscribers = [
+            [
+                'email_address' => str_replace('@kit.com', '-1@kit.com', $this->generateEmailAddress()),
+            ],
+            [
+                'email_address' => str_replace('@kit.com', '-2@kit.com', $this->generateEmailAddress()),
+            ],
+        ];
+        $result = $this->api->create_subscribers($subscribers);
+
+        // Set subscriber_id to ensure subscriber is unsubscribed after test.
+        foreach ($result->subscribers as $i => $subscriber) {
+            $this->subscriber_ids[] = $subscriber->id;
+        }
+
+        // Tag subscribers.
+        $result = $this->api->tag_subscribers(
+            [
+                [
+                    'tag_id' => (int) $_ENV['CONVERTKIT_API_TAG_ID'],
+                    'subscriber_id' => $this->subscriber_ids[0]
+                ],
+                [
+                    'tag_id' => (int) $_ENV['CONVERTKIT_API_TAG_ID'],
+                    'subscriber_id' => $this->subscriber_ids[1]
+                ],
+            ]
+        );
+
+        // Assert no failures.
+        $this->assertCount(0, $result->failures);
+
+        // Confirm result is an array comprising of each subscriber that was created.
+        $this->assertIsArray($result->subscribers);
+        $this->assertCount(2, $result->subscribers);
+    }
+
+    /**
+     * Test that tag_subscribers() returns failures when an invalid
+     * tag ID is specified.
+     *
+     * @since   2.2.1
+     *
+     * @return void
+     */
+    public function testTagSubscribersWithInvalidTagID()
+    {
+        // Create subscribers.
+        $subscribers = [
+            [
+                'email_address' => str_replace('@kit.com', '-1@kit.com', $this->generateEmailAddress()),
+            ],
+            [
+                'email_address' => str_replace('@kit.com', '-2@kit.com', $this->generateEmailAddress()),
+            ],
+        ];
+        $result = $this->api->create_subscribers($subscribers);
+
+        // Set subscriber_id to ensure subscriber is unsubscribed after test.
+        foreach ($result->subscribers as $i => $subscriber) {
+            $this->subscriber_ids[] = $subscriber->id;
+        }
+
+        // Tag subscribers.
+        $result = $this->api->tag_subscribers(
+            [
+                [
+                    'tag_id' => 12345,
+                    'subscriber_id' => $this->subscriber_ids[0]
+                ],
+                [
+                    'tag_id' => 12345,
+                    'subscriber_id' => $this->subscriber_ids[1]
+                ],
+            ]
+        );
+
+        // Assert failures.
+        $this->assertCount(2, $result->failures);
+    }
+
+    /**
+     * Test that tag_subscribers() returns failures when an invalid
+     * subscriber ID is specified.
+     *
+     * @since   2.2.1
+     *
+     * @return void
+     */
+    public function testTagSubscribersWithInvalidSubscriberID()
+    {
+        // Tag subscribers that do not exist.
+        $result = $this->api->tag_subscribers(
+            [
+                [
+                    'tag_id' => (int) $_ENV['CONVERTKIT_API_TAG_ID'],
+                    'subscriber_id' => 12345,
+                ],
+                [
+                    'tag_id' => (int) $_ENV['CONVERTKIT_API_TAG_ID'],
+                    'subscriber_id' => 67890,
+                ],
+            ]
+        );
+
+        // Assert failures.
+        $this->assertCount(2, $result->failures);
+    }
+
     /**
      * Test that tag_subscriber_by_email() returns the expected data.
      *