From 522cfb6d6ef3006c471beb1505c3286709f3b994 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Mon, 20 Mar 2023 15:19:15 +0000 Subject: [PATCH 1/2] Added `add_subscriber_to_form()` function with named arguments --- src/ConvertKit_API.php | 52 ++++++++++++++++ tests/ConvertKitAPITest.php | 118 ++++++++++++++++++++++++++++++++---- 2 files changed, 159 insertions(+), 11 deletions(-) diff --git a/src/ConvertKit_API.php b/src/ConvertKit_API.php index e989a42..8945839 100644 --- a/src/ConvertKit_API.php +++ b/src/ConvertKit_API.php @@ -180,12 +180,21 @@ public function get_landing_pages() * @param integer $form_id Form ID. * @param array $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 + ); + if (!is_int($form_id)) { throw new \InvalidArgumentException(); } @@ -202,6 +211,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 $fields Custom Fields. + * @param array $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 * diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index 16d9284..4845561 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -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)); @@ -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']); } /** From 4747c89a33f1b9019211ff23522fac6c483094fb Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Wed, 22 Mar 2023 13:10:46 +0000 Subject: [PATCH 2/2] Remove InvalidArgumentException --- src/ConvertKit_API.php | 7 ------- 1 file changed, 7 deletions(-) diff --git a/src/ConvertKit_API.php b/src/ConvertKit_API.php index 7eeec4e..c99d8a7 100644 --- a/src/ConvertKit_API.php +++ b/src/ConvertKit_API.php @@ -181,13 +181,6 @@ public function form_subscribe(int $form_id, array $options) E_USER_NOTICE ); - if (!is_int($form_id)) { - throw new \InvalidArgumentException(); - } - if (!is_array($options)) { - throw new \InvalidArgumentException(); - } - // Add API Key to array of options. $options['api_key'] = $this->api_key;