Skip to content

Add add_subscribers_to_forms method #98

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Dec 6, 2024
Merged

Add add_subscribers_to_forms method #98

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
687d57d
Add `add_subscribers_to_forms` bulk method
n7studios Dec 4, 2024
66c8d5f
Started tests
n7studios Dec 4, 2024
aa90288
Update method and tests
n7studios Dec 4, 2024
5d5715a
Remove code
n7studios Dec 4, 2024
16252a8
Merge branch 'tests-run-phpstan' into add-bulk-add-subscribers-to-forms
n7studios Dec 4, 2024
59a31d8
Merge remote-tracking branch 'origin/tests-run-phpstan' into add-bulk…
n7studios Dec 4, 2024
e513ef8
PHPStan compat.
n7studios Dec 5, 2024
b629894
Add CONVERTKIT_API_FORM_ID_2 to .env file
n7studios Dec 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .env.dist.testing
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
1 change: 1 addition & 0 deletions .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
27 changes: 27 additions & 0 deletions src/ConvertKit_API_Traits.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,33 @@ public function get_landing_pages(
);
}

/**
* Adds subscribers to forms in bulk.
*
* @param array<array<string,string>> $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
*
Expand Down
255 changes: 255 additions & 0 deletions tests/ConvertKitAPITest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand Down
Loading