diff --git a/.env.dist.testing b/.env.dist.testing index 48cc810..ca3522d 100644 --- a/.env.dist.testing +++ b/.env.dist.testing @@ -1,5 +1,6 @@ CONVERTKIT_API_BROADCAST_ID="8697158" CONVERTKIT_API_FORM_ID="2765139" +CONVERTKIT_API_FORM_ID_2="2780977" CONVERTKIT_API_LEGACY_FORM_URL="https://app.convertkit.com/landing_pages/470099" CONVERTKIT_API_LANDING_PAGE_URL="https://cheerful-architect-3237.ck.page/cc5eb21744" CONVERTKIT_API_LEGACY_LANDING_PAGE_URL="https://app.convertkit.com/landing_pages/470103" diff --git a/.env.example b/.env.example index 83d8a88..c138bea 100644 --- a/.env.example +++ b/.env.example @@ -7,6 +7,7 @@ CONVERTKIT_OAUTH_CLIENT_SECRET= CONVERTKIT_OAUTH_REDIRECT_URI="https://convertkit-github.local/wp-admin/options-general.php?page=_wp_convertkit_settings" CONVERTKIT_API_BROADCAST_ID="8697158" CONVERTKIT_API_FORM_ID="2765139" +CONVERTKIT_API_FORM_ID_2="2780977" CONVERTKIT_API_LEGACY_FORM_URL="https://app.convertkit.com/landing_pages/470099" CONVERTKIT_API_LANDING_PAGE_URL="https://cheerful-architect-3237.ck.page/cc5eb21744" CONVERTKIT_API_LEGACY_LANDING_PAGE_URL="https://app.convertkit.com/landing_pages/470103" diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index b5fc993..b83c142 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -222,6 +222,33 @@ public function get_landing_pages( ); } + /** + * Adds subscribers to forms in bulk. + * + * @param array> $forms_subscribers_ids Array of arrays comprising of `form_id`, `subscriber_id` and optional `referrer` URL. + * @param string $callback_url URL to notify for large batch size when async processing complete. + * + * @since 2.1.0 + * + * @see https://developers.kit.com/v4.html#bulk-add-subscribers-to-forms + * + * @return false|object + */ + public function add_subscribers_to_forms(array $forms_subscribers_ids, string $callback_url = '') + { + // Build parameters. + $options = ['additions' => $forms_subscribers_ids]; + if (!empty($callback_url)) { + $options['callback_url'] = $callback_url; + } + + // Send request. + return $this->post( + 'bulk/forms/subscribers', + $options + ); + } + /** * Adds a subscriber to a form by email address * diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index 9152123..7a08408 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -2699,6 +2699,261 @@ public function testGetTagSubscriptionsWithInvalidTagID() $result = $this->api->get_tag_subscriptions(12345); } + /** + * Test that add_subscribers_to_forms() returns the expected data. + * + * @since 2.1.0 + * + * @return void + */ + public function testAddSubscribersToForms() + { + // Create subscriber. + $emailAddress = $this->generateEmailAddress(); + $subscriber = $this->api->create_subscriber( + email_address: $emailAddress + ); + + // Set subscriber_id to ensure subscriber is unsubscribed after test. + $this->subscriber_ids[] = $subscriber->subscriber->id; + + // Add subscribers to forms. + $result = $this->api->add_subscribers_to_forms( + forms_subscribers_ids: [ + [ + 'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID'], + 'subscriber_id' => $subscriber->subscriber->id, + ], + [ + 'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID_2'], + 'subscriber_id' => $subscriber->subscriber->id, + ], + ] + ); + + // Assert no failures. + $this->assertCount(0, $result->failures); + + // Confirm result is an array comprising of each subscriber that was created. + $this->assertIsArray($result->subscribers); + } + + /** + * Test that add_subscribers_to_forms() returns the expected data + * when a referrer URL is specified. + * + * @since 2.1.0 + * + * @return void + */ + public function testAddSubscribersToFormsWithReferrer() + { + // Create subscriber. + $emailAddress = $this->generateEmailAddress(); + $subscriber = $this->api->create_subscriber( + email_address: $emailAddress + ); + + // Set subscriber_id to ensure subscriber is unsubscribed after test. + $this->subscriber_ids[] = $subscriber->subscriber->id; + + // Add subscribers to forms. + $result = $this->api->add_subscribers_to_forms( + forms_subscribers_ids: [ + [ + 'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID'], + 'subscriber_id' => $subscriber->subscriber->id, + 'referrer' => 'https://mywebsite.com/bfpromo/', + ], + [ + 'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID_2'], + 'subscriber_id' => $subscriber->subscriber->id, + 'referrer' => 'https://mywebsite.com/bfpromo/', + ], + ] + ); + + // Assert no failures. + $this->assertCount(0, $result->failures); + + // Confirm result is an array comprising of each subscriber that was created. + $this->assertIsArray($result->subscribers); + + // Assert referrer data set for subscribers. + foreach ($result->subscribers as $subscriber) { + $this->assertEquals( + $subscriber->referrer, + 'https://mywebsite.com/bfpromo/' + ); + } + } + + /** + * Test that add_subscribers_to_forms() returns the expected data + * when a referrer URL with UTM parameters is specified. + * + * @since 2.1.0 + * + * @return void + */ + public function testAddSubscribersToFormsWithReferrerUTMParams() + { + // Define referrer. + $referrerUTMParams = [ + 'utm_source' => 'facebook', + 'utm_medium' => 'cpc', + 'utm_campaign' => 'black_friday', + 'utm_term' => 'car_owners', + 'utm_content' => 'get_10_off', + ]; + $referrer = 'https://mywebsite.com/bfpromo/?' . http_build_query($referrerUTMParams); + + // Create subscriber. + $emailAddress = $this->generateEmailAddress(); + $subscriber = $this->api->create_subscriber( + email_address: $emailAddress + ); + + // Set subscriber_id to ensure subscriber is unsubscribed after test. + $this->subscriber_ids[] = $subscriber->subscriber->id; + + // Add subscribers to forms. + $result = $this->api->add_subscribers_to_forms( + forms_subscribers_ids: [ + [ + 'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID'], + 'subscriber_id' => $subscriber->subscriber->id, + 'referrer' => $referrer, + ], + [ + 'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID_2'], + 'subscriber_id' => $subscriber->subscriber->id, + 'referrer' => $referrer, + ], + ] + ); + + // Assert no failures. + $this->assertCount(0, $result->failures); + + // Confirm result is an array comprising of each subscriber that was created. + $this->assertIsArray($result->subscribers); + + // Assert referrer data set for subscribers. + foreach ($result->subscribers as $subscriber) { + $this->assertEquals( + $subscriber->referrer, + $referrer + ); + $this->assertEquals( + $subscriber->referrer_utm_parameters->source, + $referrerUTMParams['utm_source'] + ); + $this->assertEquals( + $subscriber->referrer_utm_parameters->medium, + $referrerUTMParams['utm_medium'] + ); + $this->assertEquals( + $subscriber->referrer_utm_parameters->campaign, + $referrerUTMParams['utm_campaign'] + ); + $this->assertEquals( + $subscriber->referrer_utm_parameters->term, + $referrerUTMParams['utm_term'] + ); + $this->assertEquals( + $subscriber->referrer_utm_parameters->content, + $referrerUTMParams['utm_content'] + ); + } + } + + /** + * Test that add_subscribers_to_forms() returns the expected errors + * when invalid Form IDs are specified. + * + * @since 2.1.0 + * + * @return void + */ + public function testAddSubscribersToFormsWithInvalidFormIDs() + { + // Create subscriber. + $emailAddress = $this->generateEmailAddress(); + $subscriber = $this->api->create_subscriber( + email_address: $emailAddress + ); + + // Set subscriber_id to ensure subscriber is unsubscribed after test. + $this->subscriber_ids[] = $subscriber->subscriber->id; + + // Add subscribers to forms. + $result = $this->api->add_subscribers_to_forms( + forms_subscribers_ids: [ + [ + 'form_id' => 9999999, + 'subscriber_id' => $subscriber->subscriber->id, + ], + [ + 'form_id' => 9999999, + 'subscriber_id' => $subscriber->subscriber->id, + ], + ] + ); + + // Assert failures. + $this->assertCount(2, $result->failures); + foreach ($result->failures as $failure) { + $this->assertEquals( + $failure->errors[0], + 'Form does not exist' + ); + } + } + + /** + * Test that add_subscribers_to_forms() returns the expected errors + * when invalid Subscriber IDs are specified. + * + * @since 2.1.0 + * + * @return void + */ + public function testAddSubscribersToFormsWithInvalidSubscriberIDs() + { + // Create subscriber. + $emailAddress = $this->generateEmailAddress(); + $subscriber = $this->api->create_subscriber( + email_address: $emailAddress + ); + + // Set subscriber_id to ensure subscriber is unsubscribed after test. + $this->subscriber_ids[] = $subscriber->subscriber->id; + + // Add subscribers to forms. + $result = $this->api->add_subscribers_to_forms( + forms_subscribers_ids: [ + [ + 'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID'], + 'subscriber_id' => 999999, + ], + [ + 'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID_2'], + 'subscriber_id' => 999999, + ], + ] + ); + + // Assert failures. + $this->assertCount(2, $result->failures); + foreach ($result->failures as $failure) { + $this->assertEquals( + $failure->errors[0], + 'Subscriber does not exist' + ); + } + } + /** * Test that add_subscriber_to_form_by_email() returns the expected data. *