Skip to content

Add add_subscriber_to_form() function with named arguments #54

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 3 commits into from
Mar 22, 2023
Merged

Add add_subscriber_to_form() function with named arguments #54

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
522cfb6
Added `add_subscriber_to_form()` function with named arguments
n7studios Mar 20, 2023
39cf9c9
Merge branch '1.0-beta' into add-subscriber-to-form
n7studios Mar 20, 2023
4747c89
Remove InvalidArgumentException
n7studios Mar 22, 2023
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
54 changes: 54 additions & 0 deletions src/ConvertKit_API.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -166,10 +166,21 @@ public function get_landing_pages()
* @param integer $form_id Form ID.
* @param array<string, string> $options Array of user data (email, name).
*
* @deprecated 1.0.0 Use add_subscriber_to_form($form_id, $email, $first_name, $fields, $tag_ids).
*
* @throws \InvalidArgumentException If the provided arguments are not of the expected type.
*
* @return false|object
*/
public function form_subscribe(int $form_id, array $options)
{
// This function is deprecated in 1.0, as we prefer functions with structured arguments.
trigger_error(
'form_subscribe() is deprecated in 1.0.
Use add_subscriber_to_form($form_id, $email, $first_name, $fields, $tag_ids) instead.',
E_USER_NOTICE
);

// Add API Key to array of options.
$options['api_key'] = $this->api_key;

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

/**
* Adds a subscriber to a form by email address
*
* @param integer $form_id Form ID.
* @param string $email Email Address.
* @param string $first_name First Name.
* @param array<string, string> $fields Custom Fields.
* @param array<string, int> $tag_ids Tag ID(s) to subscribe to.
*
* @see https://developers.convertkit.com/#add-subscriber-to-a-form
*
* @return false|mixed
*/
public function add_subscriber_to_form(
int $form_id,
string $email,
string $first_name = '',
array $fields = [],
array $tag_ids = []
) {
// Build parameters.
$options = [
'api_key' => $this->api_key,
'email' => $email,
];

if (!empty($first_name)) {
$options['first_name'] = $first_name;
}
if (!empty($fields)) {
$options['fields'] = $fields;
}
if (!empty($tag_ids)) {
$options['tags'] = $tag_ids;
}

// Send request.
return $this->post(
sprintf('forms/%s/subscribe', $form_id),
$options
);
}

/**
* List subscriptions to a form
*
Expand Down
118 changes: 107 additions & 11 deletions tests/ConvertKitAPITest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -898,19 +898,19 @@ public function testGetResourcesInvalidResourceType()
}

/**
* Test that form_subscribe() returns the expected data.
* Test that add_subscriber_to_form() returns the expected data.
*
* @since 1.0.0
*
* @return void
*/
public function testFormSubscribe()
public function testAddSubscriberToForm()
{
// Subscribe.
$email = $this->generateEmailAddress();
$result = $this->api->form_subscribe((int) $_ENV['CONVERTKIT_API_FORM_ID'], [
'email' => $email,
]);
$result = $this->api->add_subscriber_to_form(
(int) $_ENV['CONVERTKIT_API_FORM_ID'],
$email
);
$this->assertInstanceOf('stdClass', $result);
$this->assertArrayHasKey('subscription', get_object_vars($result));
$this->assertArrayHasKey('id', get_object_vars($result->subscription));
Expand All @@ -921,19 +921,115 @@ public function testFormSubscribe()
}

/**
* Test that form_subscribe() throws a ClientException when an invalid
* Test that add_subscriber_to_form() throws a ClientException when an invalid
* form ID is specified.
*
* @since 1.0.0
*
* @return void
*/
public function testFormSubscribeWithInvalidFormID()
public function testAddSubscriberToFormWithInvalidFormID()
{
$this->expectException(GuzzleHttp\Exception\ClientException::class);
$result = $this->api->form_subscribe(12345, [
'email' => $this->generateEmailAddress(),
]);
$result = $this->api->add_subscriber_to_form(12345, $this->generateEmailAddress());
}

/**
* Test that add_subscriber_to_form() throws a ClientException when an invalid
* email address is specified.
*
* @since 1.0.0
*
* @return void
*/
public function testAddSubscriberToFormWithInvalidEmailAddress()
{
$this->expectException(GuzzleHttp\Exception\ClientException::class);
$result = $this->api->add_subscriber_to_form($_ENV['CONVERTKIT_API_FORM_ID'], 'not-an-email-address');
}

/**
* Test that add_subscriber_to_form() returns the expected data
* when a first_name parameter is included.
*
* @since 1.0.0
*
* @return void
*/
public function testAddSubscriberToFormWithFirstName()
{
$emailAddress = $this->generateEmailAddress();
$firstName = 'First Name';
$result = $this->api->add_subscriber_to_form(
$_ENV['CONVERTKIT_API_FORM_ID'],
$emailAddress,
$firstName
);

$this->assertInstanceOf('stdClass', $result);
$this->assertArrayHasKey('subscription', get_object_vars($result));

// Fetch subscriber from API to confirm the first name was saved.
$subscriber = $this->api->get_subscriber($result->subscription->subscriber->id);
$this->assertEquals($subscriber->subscriber->email_address, $emailAddress);
$this->assertEquals($subscriber->subscriber->first_name, $firstName);
}

/**
* Test that add_subscriber_to_form() returns the expected data
* when custom field data is included.
*
* @since 1.0.0
*
* @return void
*/
public function testAddSubscriberToFormWithCustomFields()
{
$result = $this->api->add_subscriber_to_form(
$_ENV['CONVERTKIT_API_FORM_ID'],
$this->generateEmailAddress(),
'First Name',
[
'last_name' => 'Last Name',
]
);

// Check subscription object returned.
$this->assertInstanceOf('stdClass', $result);
$this->assertArrayHasKey('subscription', get_object_vars($result));

// Fetch subscriber from API to confirm the custom fields were saved.
$subscriber = $this->api->get_subscriber($result->subscription->subscriber->id);
$this->assertEquals($subscriber->subscriber->fields->last_name, 'Last Name');
}

/**
* Test that add_subscriber_to_form() returns the expected data
* when custom field data is included.
*
* @since 1.0.0
*
* @return void
*/
public function testAddSubscriberToFormWithTagID()
{
$result = $this->api->add_subscriber_to_form(
$_ENV['CONVERTKIT_API_FORM_ID'],
$this->generateEmailAddress(),
'First Name',
[],
[
(int) $_ENV['CONVERTKIT_API_TAG_ID']
]
);

// Check subscription object returned.
$this->assertInstanceOf('stdClass', $result);
$this->assertArrayHasKey('subscription', get_object_vars($result));

// Fetch subscriber tags from API to confirm the tag saved.
$subscriberTags = $this->api->get_subscriber_tags($result->subscription->subscriber->id);
$this->assertEquals($subscriberTags->tags[0]->id, $_ENV['CONVERTKIT_API_TAG_ID']);
}

/**
Expand Down