Skip to content

Commit e59f342

Browse files
n7studiosn7studios
authored
Merge pull request #98 from Kit/add-bulk-add-subscribers-to-forms
Add `add_subscribers_to_forms` method
2 parents 38cb077 + b629894 commit e59f342

File tree

4 files changed

+284
-0
lines changed

4 files changed

+284
-0
lines changed

‎.env.dist.testing

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
CONVERTKIT_API_BROADCAST_ID="8697158"
22
CONVERTKIT_API_FORM_ID="2765139"
3+
CONVERTKIT_API_FORM_ID_2="2780977"
34
CONVERTKIT_API_LEGACY_FORM_URL="https://app.convertkit.com/landing_pages/470099"
45
CONVERTKIT_API_LANDING_PAGE_URL="https://cheerful-architect-3237.ck.page/cc5eb21744"
56
CONVERTKIT_API_LEGACY_LANDING_PAGE_URL="https://app.convertkit.com/landing_pages/470103"

‎.env.example

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ CONVERTKIT_OAUTH_CLIENT_SECRET=
77
CONVERTKIT_OAUTH_REDIRECT_URI="https://convertkit-github.local/wp-admin/options-general.php?page=_wp_convertkit_settings"
88
CONVERTKIT_API_BROADCAST_ID="8697158"
99
CONVERTKIT_API_FORM_ID="2765139"
10+
CONVERTKIT_API_FORM_ID_2="2780977"
1011
CONVERTKIT_API_LEGACY_FORM_URL="https://app.convertkit.com/landing_pages/470099"
1112
CONVERTKIT_API_LANDING_PAGE_URL="https://cheerful-architect-3237.ck.page/cc5eb21744"
1213
CONVERTKIT_API_LEGACY_LANDING_PAGE_URL="https://app.convertkit.com/landing_pages/470103"

‎src/ConvertKit_API_Traits.php

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,33 @@ public function get_landing_pages(
222222
);
223223
}
224224

225+
/**
226+
* Adds subscribers to forms in bulk.
227+
*
228+
* @param array<array<string,string>> $forms_subscribers_ids Array of arrays comprising of `form_id`, `subscriber_id` and optional `referrer` URL.
229+
* @param string $callback_url URL to notify for large batch size when async processing complete.
230+
*
231+
* @since 2.1.0
232+
*
233+
* @see https://developers.kit.com/v4.html#bulk-add-subscribers-to-forms
234+
*
235+
* @return false|object
236+
*/
237+
public function add_subscribers_to_forms(array $forms_subscribers_ids, string $callback_url = '')
238+
{
239+
// Build parameters.
240+
$options = ['additions' => $forms_subscribers_ids];
241+
if (!empty($callback_url)) {
242+
$options['callback_url'] = $callback_url;
243+
}
244+
245+
// Send request.
246+
return $this->post(
247+
'bulk/forms/subscribers',
248+
$options
249+
);
250+
}
251+
225252
/**
226253
* Adds a subscriber to a form by email address
227254
*

‎tests/ConvertKitAPITest.php

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2702,6 +2702,261 @@ public function testGetTagSubscriptionsWithInvalidTagID()
27022702
$result = $this->api->get_tag_subscriptions(12345);
27032703
}
27042704

2705+
/**
2706+
* Test that add_subscribers_to_forms() returns the expected data.
2707+
*
2708+
* @since 2.1.0
2709+
*
2710+
* @return void
2711+
*/
2712+
public function testAddSubscribersToForms()
2713+
{
2714+
// Create subscriber.
2715+
$emailAddress = $this->generateEmailAddress();
2716+
$subscriber = $this->api->create_subscriber(
2717+
email_address: $emailAddress
2718+
);
2719+
2720+
// Set subscriber_id to ensure subscriber is unsubscribed after test.
2721+
$this->subscriber_ids[] = $subscriber->subscriber->id;
2722+
2723+
// Add subscribers to forms.
2724+
$result = $this->api->add_subscribers_to_forms(
2725+
forms_subscribers_ids: [
2726+
[
2727+
'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID'],
2728+
'subscriber_id' => $subscriber->subscriber->id,
2729+
],
2730+
[
2731+
'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID_2'],
2732+
'subscriber_id' => $subscriber->subscriber->id,
2733+
],
2734+
]
2735+
);
2736+
2737+
// Assert no failures.
2738+
$this->assertCount(0, $result->failures);
2739+
2740+
// Confirm result is an array comprising of each subscriber that was created.
2741+
$this->assertIsArray($result->subscribers);
2742+
}
2743+
2744+
/**
2745+
* Test that add_subscribers_to_forms() returns the expected data
2746+
* when a referrer URL is specified.
2747+
*
2748+
* @since 2.1.0
2749+
*
2750+
* @return void
2751+
*/
2752+
public function testAddSubscribersToFormsWithReferrer()
2753+
{
2754+
// Create subscriber.
2755+
$emailAddress = $this->generateEmailAddress();
2756+
$subscriber = $this->api->create_subscriber(
2757+
email_address: $emailAddress
2758+
);
2759+
2760+
// Set subscriber_id to ensure subscriber is unsubscribed after test.
2761+
$this->subscriber_ids[] = $subscriber->subscriber->id;
2762+
2763+
// Add subscribers to forms.
2764+
$result = $this->api->add_subscribers_to_forms(
2765+
forms_subscribers_ids: [
2766+
[
2767+
'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID'],
2768+
'subscriber_id' => $subscriber->subscriber->id,
2769+
'referrer' => 'https://mywebsite.com/bfpromo/',
2770+
],
2771+
[
2772+
'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID_2'],
2773+
'subscriber_id' => $subscriber->subscriber->id,
2774+
'referrer' => 'https://mywebsite.com/bfpromo/',
2775+
],
2776+
]
2777+
);
2778+
2779+
// Assert no failures.
2780+
$this->assertCount(0, $result->failures);
2781+
2782+
// Confirm result is an array comprising of each subscriber that was created.
2783+
$this->assertIsArray($result->subscribers);
2784+
2785+
// Assert referrer data set for subscribers.
2786+
foreach ($result->subscribers as $subscriber) {
2787+
$this->assertEquals(
2788+
$subscriber->referrer,
2789+
'https://mywebsite.com/bfpromo/'
2790+
);
2791+
}
2792+
}
2793+
2794+
/**
2795+
* Test that add_subscribers_to_forms() returns the expected data
2796+
* when a referrer URL with UTM parameters is specified.
2797+
*
2798+
* @since 2.1.0
2799+
*
2800+
* @return void
2801+
*/
2802+
public function testAddSubscribersToFormsWithReferrerUTMParams()
2803+
{
2804+
// Define referrer.
2805+
$referrerUTMParams = [
2806+
'utm_source' => 'facebook',
2807+
'utm_medium' => 'cpc',
2808+
'utm_campaign' => 'black_friday',
2809+
'utm_term' => 'car_owners',
2810+
'utm_content' => 'get_10_off',
2811+
];
2812+
$referrer = 'https://mywebsite.com/bfpromo/?' . http_build_query($referrerUTMParams);
2813+
2814+
// Create subscriber.
2815+
$emailAddress = $this->generateEmailAddress();
2816+
$subscriber = $this->api->create_subscriber(
2817+
email_address: $emailAddress
2818+
);
2819+
2820+
// Set subscriber_id to ensure subscriber is unsubscribed after test.
2821+
$this->subscriber_ids[] = $subscriber->subscriber->id;
2822+
2823+
// Add subscribers to forms.
2824+
$result = $this->api->add_subscribers_to_forms(
2825+
forms_subscribers_ids: [
2826+
[
2827+
'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID'],
2828+
'subscriber_id' => $subscriber->subscriber->id,
2829+
'referrer' => $referrer,
2830+
],
2831+
[
2832+
'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID_2'],
2833+
'subscriber_id' => $subscriber->subscriber->id,
2834+
'referrer' => $referrer,
2835+
],
2836+
]
2837+
);
2838+
2839+
// Assert no failures.
2840+
$this->assertCount(0, $result->failures);
2841+
2842+
// Confirm result is an array comprising of each subscriber that was created.
2843+
$this->assertIsArray($result->subscribers);
2844+
2845+
// Assert referrer data set for subscribers.
2846+
foreach ($result->subscribers as $subscriber) {
2847+
$this->assertEquals(
2848+
$subscriber->referrer,
2849+
$referrer
2850+
);
2851+
$this->assertEquals(
2852+
$subscriber->referrer_utm_parameters->source,
2853+
$referrerUTMParams['utm_source']
2854+
);
2855+
$this->assertEquals(
2856+
$subscriber->referrer_utm_parameters->medium,
2857+
$referrerUTMParams['utm_medium']
2858+
);
2859+
$this->assertEquals(
2860+
$subscriber->referrer_utm_parameters->campaign,
2861+
$referrerUTMParams['utm_campaign']
2862+
);
2863+
$this->assertEquals(
2864+
$subscriber->referrer_utm_parameters->term,
2865+
$referrerUTMParams['utm_term']
2866+
);
2867+
$this->assertEquals(
2868+
$subscriber->referrer_utm_parameters->content,
2869+
$referrerUTMParams['utm_content']
2870+
);
2871+
}
2872+
}
2873+
2874+
/**
2875+
* Test that add_subscribers_to_forms() returns the expected errors
2876+
* when invalid Form IDs are specified.
2877+
*
2878+
* @since 2.1.0
2879+
*
2880+
* @return void
2881+
*/
2882+
public function testAddSubscribersToFormsWithInvalidFormIDs()
2883+
{
2884+
// Create subscriber.
2885+
$emailAddress = $this->generateEmailAddress();
2886+
$subscriber = $this->api->create_subscriber(
2887+
email_address: $emailAddress
2888+
);
2889+
2890+
// Set subscriber_id to ensure subscriber is unsubscribed after test.
2891+
$this->subscriber_ids[] = $subscriber->subscriber->id;
2892+
2893+
// Add subscribers to forms.
2894+
$result = $this->api->add_subscribers_to_forms(
2895+
forms_subscribers_ids: [
2896+
[
2897+
'form_id' => 9999999,
2898+
'subscriber_id' => $subscriber->subscriber->id,
2899+
],
2900+
[
2901+
'form_id' => 9999999,
2902+
'subscriber_id' => $subscriber->subscriber->id,
2903+
],
2904+
]
2905+
);
2906+
2907+
// Assert failures.
2908+
$this->assertCount(2, $result->failures);
2909+
foreach ($result->failures as $failure) {
2910+
$this->assertEquals(
2911+
$failure->errors[0],
2912+
'Form does not exist'
2913+
);
2914+
}
2915+
}
2916+
2917+
/**
2918+
* Test that add_subscribers_to_forms() returns the expected errors
2919+
* when invalid Subscriber IDs are specified.
2920+
*
2921+
* @since 2.1.0
2922+
*
2923+
* @return void
2924+
*/
2925+
public function testAddSubscribersToFormsWithInvalidSubscriberIDs()
2926+
{
2927+
// Create subscriber.
2928+
$emailAddress = $this->generateEmailAddress();
2929+
$subscriber = $this->api->create_subscriber(
2930+
email_address: $emailAddress
2931+
);
2932+
2933+
// Set subscriber_id to ensure subscriber is unsubscribed after test.
2934+
$this->subscriber_ids[] = $subscriber->subscriber->id;
2935+
2936+
// Add subscribers to forms.
2937+
$result = $this->api->add_subscribers_to_forms(
2938+
forms_subscribers_ids: [
2939+
[
2940+
'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID'],
2941+
'subscriber_id' => 999999,
2942+
],
2943+
[
2944+
'form_id' => (int) $_ENV['CONVERTKIT_API_FORM_ID_2'],
2945+
'subscriber_id' => 999999,
2946+
],
2947+
]
2948+
);
2949+
2950+
// Assert failures.
2951+
$this->assertCount(2, $result->failures);
2952+
foreach ($result->failures as $failure) {
2953+
$this->assertEquals(
2954+
$failure->errors[0],
2955+
'Subscriber does not exist'
2956+
);
2957+
}
2958+
}
2959+
27052960
/**
27062961
* Test that add_subscriber_to_form_by_email() returns the expected data.
27072962
*

0 commit comments

Comments
 (0)