From 687d57daf973ee600f4e9e2d726e56b23510bd57 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Wed, 4 Dec 2024 16:22:10 +0800 Subject: [PATCH 1/6] Add `add_subscribers_to_forms` bulk method --- src/ConvertKit_API_Traits.php | 62 ++++++++++++++++++++++++++++++++--- 1 file changed, 58 insertions(+), 4 deletions(-) diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index b5fc993..ffd8bf3 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -222,21 +222,63 @@ public function get_landing_pages( ); } + /** + * Adds subscribers to forms in bulk. + * + * @param array> $forms_subscribers_ids Array of arrays comprising of `form_id` and `subscriber_id`. + * @param string $referrer 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 $referrer = '', string $callback_url = '') + { + // Build parameters. + $options = [ + 'additions' => $forms_subscribers_ids, + ]; + if (!empty($referrer)) { + $options['referrer'] = $referrer; + } + 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 * * @param integer $form_id Form ID. * @param string $email_address Email Address. + * @param string $referrer Referrer. * * @see https://developers.convertkit.com/v4.html#add-subscriber-to-form-by-email-address * * @return false|mixed */ - public function add_subscriber_to_form_by_email(int $form_id, string $email_address) + public function add_subscriber_to_form_by_email(int $form_id, string $email_address, string $referrer = '') { + // Build parameters. + $options = ['email_address' => $email_address]; + + if (!empty($referrer)) { + $options['referrer'] = $referrer; + } + + // Send request. return $this->post( sprintf('forms/%s/subscribers', $form_id), - ['email_address' => $email_address] + $options ); } @@ -245,6 +287,7 @@ public function add_subscriber_to_form_by_email(int $form_id, string $email_addr * * @param integer $form_id Form ID. * @param integer $subscriber_id Subscriber ID. + * @param string $referrer Referrer URL. * * @see https://developers.convertkit.com/v4.html#add-subscriber-to-form * @@ -252,9 +295,20 @@ public function add_subscriber_to_form_by_email(int $form_id, string $email_addr * * @return false|mixed */ - public function add_subscriber_to_form(int $form_id, int $subscriber_id) + public function add_subscriber_to_form(int $form_id, int $subscriber_id, string $referrer = '') { - return $this->post(sprintf('forms/%s/subscribers/%s', $form_id, $subscriber_id)); + // Build parameters. + $options = []; + + if (!empty($referrer)) { + $options['referrer'] = $referrer; + } + + // Send request. + return $this->post( + sprintf('forms/%s/subscribers/%s', $form_id, $subscriber_id), + $options + ); } /** From 66c8d5faf71ecd3d8f2d80ac83134cff014ae7f0 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Wed, 4 Dec 2024 16:22:15 +0800 Subject: [PATCH 2/6] Started tests --- tests/ConvertKitAPITest.php | 253 ++++++++++++++++++++++++++++++++++++ 1 file changed, 253 insertions(+) diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index b6839a3..5194426 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -2699,6 +2699,259 @@ 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, + ], + [ + '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, + ], + [ + 'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID_2'], + 'subscriber_id' => $subscriber->subscriber->id, + ], + ], + referrer: $referer + ); + + // 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, + $referer + ); + $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. * From aa9028867d1a6a17b9418dfc2337038745fd3e8c Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Wed, 4 Dec 2024 16:25:30 +0800 Subject: [PATCH 3/6] Update method and tests --- src/ConvertKit_API_Traits.php | 12 +++--------- tests/ConvertKitAPITest.php | 26 ++++++++++++++------------ 2 files changed, 17 insertions(+), 21 deletions(-) diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index ffd8bf3..d3c1762 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -225,8 +225,7 @@ public function get_landing_pages( /** * Adds subscribers to forms in bulk. * - * @param array> $forms_subscribers_ids Array of arrays comprising of `form_id` and `subscriber_id`. - * @param string $referrer Referrer URL. + * @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 @@ -235,15 +234,10 @@ public function get_landing_pages( * * @return false|object */ - public function add_subscribers_to_forms(array $forms_subscribers_ids, string $referrer = '', string $callback_url = '') + public function add_subscribers_to_forms(array $forms_subscribers_ids, string $callback_url = '') { // Build parameters. - $options = [ - 'additions' => $forms_subscribers_ids, - ]; - if (!empty($referrer)) { - $options['referrer'] = $referrer; - } + $options = ['additions' => $forms_subscribers_ids]; if (!empty($callback_url)) { $options['callback_url'] = $callback_url; } diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index 5194426..7e2b5a3 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -2763,13 +2763,14 @@ public function testAddSubscribersToFormsWithReferrer() [ '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/', ], - ], - referrer: 'https://mywebsite.com/bfpromo/' + ] ); // Assert no failures. @@ -2779,11 +2780,11 @@ public function testAddSubscribersToFormsWithReferrer() $this->assertIsArray($result->subscribers); // Assert referrer data set for subscribers. - foreach($result->subscribers as $subscriber) { + foreach ($result->subscribers as $subscriber) { $this->assertEquals( - $subscriber->referrer, - 'https://mywebsite.com/bfpromo/' - ); + $subscriber->referrer, + 'https://mywebsite.com/bfpromo/' + ); } } @@ -2822,13 +2823,14 @@ public function testAddSubscribersToFormsWithReferrerUTMParams() [ '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, ], - ], - referrer: $referer + ] ); // Assert no failures. @@ -2838,10 +2840,10 @@ public function testAddSubscribersToFormsWithReferrerUTMParams() $this->assertIsArray($result->subscribers); // Assert referrer data set for subscribers. - foreach($result->subscribers as $subscriber) { + foreach ($result->subscribers as $subscriber) { $this->assertEquals( $subscriber->referrer, - $referer + $referrer ); $this->assertEquals( $subscriber->referrer_utm_parameters->source, @@ -2901,7 +2903,7 @@ public function testAddSubscribersToFormsWithInvalidFormIDs() // Assert failures. $this->assertCount(2, $result->failures); - foreach($result->failures as $failure) { + foreach ($result->failures as $failure) { $this->assertEquals( $failure->errors[0], 'Form does not exist' @@ -2944,7 +2946,7 @@ public function testAddSubscribersToFormsWithInvalidSubscriberIDs() // Assert failures. $this->assertCount(2, $result->failures); - foreach($result->failures as $failure) { + foreach ($result->failures as $failure) { $this->assertEquals( $failure->errors[0], 'Subscriber does not exist' From 5d5715a33415432c3f6cbd4e5062ca86787a600d Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Wed, 4 Dec 2024 17:02:30 +0800 Subject: [PATCH 4/6] Remove code --- src/ConvertKit_API_Traits.php | 29 ++++------------------------- 1 file changed, 4 insertions(+), 25 deletions(-) diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index d3c1762..67afed5 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -254,25 +254,16 @@ public function add_subscribers_to_forms(array $forms_subscribers_ids, string $c * * @param integer $form_id Form ID. * @param string $email_address Email Address. - * @param string $referrer Referrer. * * @see https://developers.convertkit.com/v4.html#add-subscriber-to-form-by-email-address * * @return false|mixed */ - public function add_subscriber_to_form_by_email(int $form_id, string $email_address, string $referrer = '') + public function add_subscriber_to_form_by_email(int $form_id, string $email_address) { - // Build parameters. - $options = ['email_address' => $email_address]; - - if (!empty($referrer)) { - $options['referrer'] = $referrer; - } - - // Send request. return $this->post( sprintf('forms/%s/subscribers', $form_id), - $options + ['email_address' => $email_address] ); } @@ -281,7 +272,6 @@ public function add_subscriber_to_form_by_email(int $form_id, string $email_addr * * @param integer $form_id Form ID. * @param integer $subscriber_id Subscriber ID. - * @param string $referrer Referrer URL. * * @see https://developers.convertkit.com/v4.html#add-subscriber-to-form * @@ -289,20 +279,9 @@ public function add_subscriber_to_form_by_email(int $form_id, string $email_addr * * @return false|mixed */ - public function add_subscriber_to_form(int $form_id, int $subscriber_id, string $referrer = '') + public function add_subscriber_to_form(int $form_id, int $subscriber_id) { - // Build parameters. - $options = []; - - if (!empty($referrer)) { - $options['referrer'] = $referrer; - } - - // Send request. - return $this->post( - sprintf('forms/%s/subscribers/%s', $form_id, $subscriber_id), - $options - ); + return $this->post(sprintf('forms/%s/subscribers/%s', $form_id, $subscriber_id)); } /** From e513ef8c88cb74b7e95b3626080a549e3c1591f6 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Thu, 5 Dec 2024 10:29:38 +0800 Subject: [PATCH 5/6] PHPStan compat. --- src/ConvertKit_API_Traits.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index 67afed5..b83c142 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -225,8 +225,8 @@ 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. + * @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 * From b629894eb6879cc02600a866e3c17003ff1a2a04 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Thu, 5 Dec 2024 11:11:48 +0800 Subject: [PATCH 6/6] Add CONVERTKIT_API_FORM_ID_2 to .env file --- .env.dist.testing | 1 + .env.example | 1 + 2 files changed, 2 insertions(+) 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"