Skip to content

Commit dd2c992

Browse files
n7studiosn7studios
authored
Merge pull request #54 from ConvertKit/add-subscriber-to-form
Add `add_subscriber_to_form()` function with named arguments
2 parents b6e0d29 + 4747c89 commit dd2c992

File tree

2 files changed

+161
-11
lines changed

2 files changed

+161
-11
lines changed

‎src/ConvertKit_API.php‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,10 +166,21 @@ public function get_landing_pages()
166166
* @param integer $form_id Form ID.
167167
* @param array<string, string> $options Array of user data (email, name).
168168
*
169+
* @deprecated 1.0.0 Use add_subscriber_to_form($form_id, $email, $first_name, $fields, $tag_ids).
170+
*
171+
* @throws \InvalidArgumentException If the provided arguments are not of the expected type.
172+
*
169173
* @return false|object
170174
*/
171175
public function form_subscribe(int $form_id, array $options)
172176
{
177+
// This function is deprecated in 1.0, as we prefer functions with structured arguments.
178+
trigger_error(
179+
'form_subscribe() is deprecated in 1.0.
180+
Use add_subscriber_to_form($form_id, $email, $first_name, $fields, $tag_ids) instead.',
181+
E_USER_NOTICE
182+
);
183+
173184
// Add API Key to array of options.
174185
$options['api_key'] = $this->api_key;
175186

@@ -179,6 +190,49 @@ public function form_subscribe(int $form_id, array $options)
179190
);
180191
}
181192

193+
/**
194+
* Adds a subscriber to a form by email address
195+
*
196+
* @param integer $form_id Form ID.
197+
* @param string $email Email Address.
198+
* @param string $first_name First Name.
199+
* @param array<string, string> $fields Custom Fields.
200+
* @param array<string, int> $tag_ids Tag ID(s) to subscribe to.
201+
*
202+
* @see https://developers.convertkit.com/#add-subscriber-to-a-form
203+
*
204+
* @return false|mixed
205+
*/
206+
public function add_subscriber_to_form(
207+
int $form_id,
208+
string $email,
209+
string $first_name = '',
210+
array $fields = [],
211+
array $tag_ids = []
212+
) {
213+
// Build parameters.
214+
$options = [
215+
'api_key' => $this->api_key,
216+
'email' => $email,
217+
];
218+
219+
if (!empty($first_name)) {
220+
$options['first_name'] = $first_name;
221+
}
222+
if (!empty($fields)) {
223+
$options['fields'] = $fields;
224+
}
225+
if (!empty($tag_ids)) {
226+
$options['tags'] = $tag_ids;
227+
}
228+
229+
// Send request.
230+
return $this->post(
231+
sprintf('forms/%s/subscribe', $form_id),
232+
$options
233+
);
234+
}
235+
182236
/**
183237
* List subscriptions to a form
184238
*

‎tests/ConvertKitAPITest.php‎

Lines changed: 107 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -898,19 +898,19 @@ public function testGetResourcesInvalidResourceType()
898898
}
899899

900900
/**
901-
* Test that form_subscribe() returns the expected data.
901+
* Test that add_subscriber_to_form() returns the expected data.
902902
*
903903
* @since 1.0.0
904904
*
905905
* @return void
906906
*/
907-
public function testFormSubscribe()
907+
public function testAddSubscriberToForm()
908908
{
909-
// Subscribe.
910909
$email = $this->generateEmailAddress();
911-
$result = $this->api->form_subscribe((int) $_ENV['CONVERTKIT_API_FORM_ID'], [
912-
'email' => $email,
913-
]);
910+
$result = $this->api->add_subscriber_to_form(
911+
(int) $_ENV['CONVERTKIT_API_FORM_ID'],
912+
$email
913+
);
914914
$this->assertInstanceOf('stdClass', $result);
915915
$this->assertArrayHasKey('subscription', get_object_vars($result));
916916
$this->assertArrayHasKey('id', get_object_vars($result->subscription));
@@ -921,19 +921,115 @@ public function testFormSubscribe()
921921
}
922922

923923
/**
924-
* Test that form_subscribe() throws a ClientException when an invalid
924+
* Test that add_subscriber_to_form() throws a ClientException when an invalid
925925
* form ID is specified.
926926
*
927927
* @since 1.0.0
928928
*
929929
* @return void
930930
*/
931-
public function testFormSubscribeWithInvalidFormID()
931+
public function testAddSubscriberToFormWithInvalidFormID()
932932
{
933933
$this->expectException(GuzzleHttp\Exception\ClientException::class);
934-
$result = $this->api->form_subscribe(12345, [
935-
'email' => $this->generateEmailAddress(),
936-
]);
934+
$result = $this->api->add_subscriber_to_form(12345, $this->generateEmailAddress());
935+
}
936+
937+
/**
938+
* Test that add_subscriber_to_form() throws a ClientException when an invalid
939+
* email address is specified.
940+
*
941+
* @since 1.0.0
942+
*
943+
* @return void
944+
*/
945+
public function testAddSubscriberToFormWithInvalidEmailAddress()
946+
{
947+
$this->expectException(GuzzleHttp\Exception\ClientException::class);
948+
$result = $this->api->add_subscriber_to_form($_ENV['CONVERTKIT_API_FORM_ID'], 'not-an-email-address');
949+
}
950+
951+
/**
952+
* Test that add_subscriber_to_form() returns the expected data
953+
* when a first_name parameter is included.
954+
*
955+
* @since 1.0.0
956+
*
957+
* @return void
958+
*/
959+
public function testAddSubscriberToFormWithFirstName()
960+
{
961+
$emailAddress = $this->generateEmailAddress();
962+
$firstName = 'First Name';
963+
$result = $this->api->add_subscriber_to_form(
964+
$_ENV['CONVERTKIT_API_FORM_ID'],
965+
$emailAddress,
966+
$firstName
967+
);
968+
969+
$this->assertInstanceOf('stdClass', $result);
970+
$this->assertArrayHasKey('subscription', get_object_vars($result));
971+
972+
// Fetch subscriber from API to confirm the first name was saved.
973+
$subscriber = $this->api->get_subscriber($result->subscription->subscriber->id);
974+
$this->assertEquals($subscriber->subscriber->email_address, $emailAddress);
975+
$this->assertEquals($subscriber->subscriber->first_name, $firstName);
976+
}
977+
978+
/**
979+
* Test that add_subscriber_to_form() returns the expected data
980+
* when custom field data is included.
981+
*
982+
* @since 1.0.0
983+
*
984+
* @return void
985+
*/
986+
public function testAddSubscriberToFormWithCustomFields()
987+
{
988+
$result = $this->api->add_subscriber_to_form(
989+
$_ENV['CONVERTKIT_API_FORM_ID'],
990+
$this->generateEmailAddress(),
991+
'First Name',
992+
[
993+
'last_name' => 'Last Name',
994+
]
995+
);
996+
997+
// Check subscription object returned.
998+
$this->assertInstanceOf('stdClass', $result);
999+
$this->assertArrayHasKey('subscription', get_object_vars($result));
1000+
1001+
// Fetch subscriber from API to confirm the custom fields were saved.
1002+
$subscriber = $this->api->get_subscriber($result->subscription->subscriber->id);
1003+
$this->assertEquals($subscriber->subscriber->fields->last_name, 'Last Name');
1004+
}
1005+
1006+
/**
1007+
* Test that add_subscriber_to_form() returns the expected data
1008+
* when custom field data is included.
1009+
*
1010+
* @since 1.0.0
1011+
*
1012+
* @return void
1013+
*/
1014+
public function testAddSubscriberToFormWithTagID()
1015+
{
1016+
$result = $this->api->add_subscriber_to_form(
1017+
$_ENV['CONVERTKIT_API_FORM_ID'],
1018+
$this->generateEmailAddress(),
1019+
'First Name',
1020+
[],
1021+
[
1022+
(int) $_ENV['CONVERTKIT_API_TAG_ID']
1023+
]
1024+
);
1025+
1026+
// Check subscription object returned.
1027+
$this->assertInstanceOf('stdClass', $result);
1028+
$this->assertArrayHasKey('subscription', get_object_vars($result));
1029+
1030+
// Fetch subscriber tags from API to confirm the tag saved.
1031+
$subscriberTags = $this->api->get_subscriber_tags($result->subscription->subscriber->id);
1032+
$this->assertEquals($subscriberTags->tags[0]->id, $_ENV['CONVERTKIT_API_TAG_ID']);
9371033
}
9381034

9391035
/**

0 commit comments

Comments
 (0)