Skip to content

Commit 522cfb6

Browse files
n7studiosn7studios
committed
Added add_subscriber_to_form() function with named arguments
1 parent 8daf63e commit 522cfb6

File tree

2 files changed

+159
-11
lines changed

2 files changed

+159
-11
lines changed

‎src/ConvertKit_API.php

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,12 +180,21 @@ public function get_landing_pages()
180180
* @param integer $form_id Form ID.
181181
* @param array<string, string> $options Array of user data (email, name).
182182
*
183+
* @deprecated 1.0.0 Use add_subscriber_to_form($form_id, $email, $first_name, $fields, $tag_ids).
184+
*
183185
* @throws \InvalidArgumentException If the provided arguments are not of the expected type.
184186
*
185187
* @return false|object
186188
*/
187189
public function form_subscribe(int $form_id, array $options)
188190
{
191+
// This function is deprecated in 1.0, as we prefer functions with structured arguments.
192+
trigger_error(
193+
'form_subscribe() is deprecated in 1.0.
194+
Use add_subscriber_to_form($form_id, $email, $first_name, $fields, $tag_ids) instead.',
195+
E_USER_NOTICE
196+
);
197+
189198
if (!is_int($form_id)) {
190199
throw new \InvalidArgumentException();
191200
}
@@ -202,6 +211,49 @@ public function form_subscribe(int $form_id, array $options)
202211
);
203212
}
204213

214+
/**
215+
* Adds a subscriber to a form by email address
216+
*
217+
* @param integer $form_id Form ID.
218+
* @param string $email Email Address.
219+
* @param string $first_name First Name.
220+
* @param array<string, string> $fields Custom Fields.
221+
* @param array<string, int> $tag_ids Tag ID(s) to subscribe to.
222+
*
223+
* @see https://developers.convertkit.com/#add-subscriber-to-a-form
224+
*
225+
* @return false|mixed
226+
*/
227+
public function add_subscriber_to_form(
228+
int $form_id,
229+
string $email,
230+
string $first_name = '',
231+
array $fields = [],
232+
array $tag_ids = []
233+
) {
234+
// Build parameters.
235+
$options = [
236+
'api_key' => $this->api_key,
237+
'email' => $email,
238+
];
239+
240+
if (!empty($first_name)) {
241+
$options['first_name'] = $first_name;
242+
}
243+
if (!empty($fields)) {
244+
$options['fields'] = $fields;
245+
}
246+
if (!empty($tag_ids)) {
247+
$options['tags'] = $tag_ids;
248+
}
249+
250+
// Send request.
251+
return $this->post(
252+
sprintf('forms/%s/subscribe', $form_id),
253+
$options
254+
);
255+
}
256+
205257
/**
206258
* List subscriptions to a form
207259
*

‎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)