From 7b6f8a85bcb5a669879cec3bf9b57d9dca9d3cb1 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 12:31:40 +0800 Subject: [PATCH 01/17] Update `convertkit.com` to `kit.com` --- .github/ISSUE_TEMPLATE/config.yml | 8 +-- DEPLOYMENT.md | 4 +- SETUP.md | 2 +- composer.json | 29 ++++++-- src/ConvertKit_API_Traits.php | 108 +++++++++++++++--------------- tests/ConvertKitAPIKeyTest.php | 4 +- tests/ConvertKitAPIOAuthTest.php | 2 +- tests/ConvertKitAPITest.php | 8 +-- 8 files changed, 91 insertions(+), 74 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index c500db9..291ddef 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,8 +1,8 @@ blank_issues_enabled: false contact_links: - - name: ConvertKit support - url: https://convertkit.com/support/ + - name: Kit support + url: https://kit.com/support/ about: | - Please only file issues here that you believe represent actual bugs or feature requests for the ConvertKit PHP SDK. + Please only file issues here that you believe represent actual bugs or feature requests for the Kit PHP SDK. - If you're having general trouble with your ConvertKit integration, please reach out to support. \ No newline at end of file + If you're having general trouble with your Kit integration, please reach out to support. \ No newline at end of file diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 5322da0..e146865 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -35,7 +35,7 @@ Commit the updated files, which should comprise of: ## Create a New Release -[Create a New Release](https://github.com/ConvertKit/convertkitsdk-php/releases/new), completing the following: +[Create a New Release](https://github.com/kit/convertkitsdk-php/releases/new), completing the following: - Choose a tag: Click this button and enter the new version number (e.g. `1.0`) - Release title: The version number (e.g. `1.0`) @@ -91,4 +91,4 @@ When you're happy with the above, click `Publish Release`. This will then make the release available to developers, who can include it manually or using composer. -The release will also be available to view on the [Releases](https://github.com/ConvertKit/convertkitsdk-php/releases) section of this GitHub repository. \ No newline at end of file +The release will also be available to view on the [Releases](https://github.com/kit/convertkitsdk-php/releases) section of this GitHub repository. \ No newline at end of file diff --git a/SETUP.md b/SETUP.md index b28399a..5a36c4f 100644 --- a/SETUP.md +++ b/SETUP.md @@ -1,6 +1,6 @@ # Setup Guide -This document describes how to setup your development environment, so that it is ready to run, develop and test the ConvertKit PHP SDK. +This document describes how to setup your development environment, so that it is ready to run, develop and test the Kit PHP SDK. Suggestions are provided for the LAMP/LEMP stack and Git client are for those who prefer the UI over a command line and/or are less familiar with PHP, MySQL and Git - but you're free to use your preferred software. diff --git a/composer.json b/composer.json index 30a377e..3a62e0f 100644 --- a/composer.json +++ b/composer.json @@ -1,17 +1,23 @@ { "name": "convertkit/convertkitapi", - "description": "ConvertKit PHP SDK for the ConvertKit API", + "description": "Kit PHP SDK for the Kit API", "keywords": [ "convertkit", + "kit", "api", - "forms" + "forms", + "tags", + "sequences", + "broadcasts", + "emails", + "subscribers" ], - "homepage": "https://convertkit.com/", + "homepage": "https://developers.kit.com/welcome", "license": "GPLv3", "authors": [ { - "name": "ConvertKit and contributors", - "homepage": "https://github.com/convertkit/convertkitsdk-php/contributors" + "name": "Kit and contributors", + "homepage": "https://github.com/kit/convertkitsdk-php/contributors" } ], "require": { @@ -38,6 +44,17 @@ "minimum-stability": "dev", "prefer-stable": true, "scripts": { - "create-docs": "phpDocumentor --directory=src --target=docs --template='vendor/saggre/phpdocumentor-markdown/themes/markdown'" + "create-docs": "phpDocumentor --directory=src --target=docs --template='vendor/saggre/phpdocumentor-markdown/themes/markdown'", + "phpcs": "vendor/bin/phpcs ./ -s -v", + "phpcbf": "vendor/bin/phpcbf ./ -s -v", + "phpcs-tests": "vendor/bin/phpcs ./tests --standard=phpcs.tests.xml -s -v", + "phpcbf-tests": "vendor/bin/phpcbf ./tests --standard=phpcs.tests.xml -s -v", + "phpstan": "vendor/bin/phpstan analyse --memory-limit=1250M", + "php-coding-standards": "vendor/bin/phpcs ./ -s -v", + "fix-php-coding-standards": "vendor/bin/phpcbf ./ -s -v", + "php-coding-standards-on-tests": "vendor/bin/phpcs ./tests --standard=phpcs.tests.xml -s -v", + "fix-php-coding-standards-on-tests": "vendor/bin/phpcbf ./tests --standard=phpcs.tests.xml -s -v", + "php-static-analysis": "vendor/bin/phpstan analyse --memory-limit=1250M", + "test": "vendor/bin/phpunit" } } diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index 71f2175..6847af7 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -45,14 +45,14 @@ trait ConvertKit_API_Traits * * @var string */ - protected $oauth_authorize_url = 'https://app.convertkit.com/oauth/authorize'; + protected $oauth_authorize_url = 'https://app.kit.com/oauth/authorize'; /** * OAuth Token URL * * @var string */ - protected $oauth_token_url = 'https://api.convertkit.com/oauth/token'; + protected $oauth_token_url = 'https://api.kit.com/oauth/token'; /** * Version of ConvertKit API @@ -66,13 +66,13 @@ trait ConvertKit_API_Traits * * @var string */ - protected $api_url_base = 'https://api.convertkit.com/'; + protected $api_url_base = 'https://api.kit.com/'; /** * Gets the current account * - * @see https://developers.convertkit.com/v4.html#get-current-account + * @see https://developers.kit.com/v4.html#get-current-account * * @return false|mixed */ @@ -84,7 +84,7 @@ public function get_account() /** * Gets the account's colors * - * @see https://developers.convertkit.com/v4.html#list-colors + * @see https://developers.kit.com/v4.html#list-colors * * @return false|mixed */ @@ -98,7 +98,7 @@ public function get_account_colors() * * @param array $colors Hex colors. * - * @see https://developers.convertkit.com/v4.html#list-colors + * @see https://developers.kit.com/v4.html#list-colors * * @return false|mixed */ @@ -113,7 +113,7 @@ public function update_account_colors(array $colors) /** * Gets the Creator Profile * - * @see https://developers.convertkit.com/v4.html#get-creator-profile + * @see https://developers.kit.com/v4.html#get-creator-profile * * @return false|mixed */ @@ -125,7 +125,7 @@ public function get_creator_profile() /** * Gets email stats * - * @see https://developers.convertkit.com/v4.html#get-email-stats + * @see https://developers.kit.com/v4.html#get-email-stats * * @return false|mixed */ @@ -140,7 +140,7 @@ public function get_email_stats() * @param \DateTime|null $starting Gets stats for time period beginning on this date. Defaults to 90 days ago. * @param \DateTime|null $ending Gets stats for time period ending on this date. Defaults to today. * - * @see https://developers.convertkit.com/v4.html#get-growth-stats + * @see https://developers.kit.com/v4.html#get-growth-stats * * @return false|mixed */ @@ -166,7 +166,7 @@ public function get_growth_stats(\DateTime|null $starting = null, \DateTime|null * * @since 1.0.0 * - * @see https://developers.convertkit.com/v4.html#convertkit-api-forms + * @see https://developers.kit.com/v4.html#convertkit-api-forms * * @return mixed|array */ @@ -203,7 +203,7 @@ public function get_forms( * * @since 1.0.0 * - * @see https://developers.convertkit.com/v4.html#convertkit-api-forms + * @see https://developers.kit.com/v4.html#convertkit-api-forms * * @return mixed|array */ @@ -263,7 +263,7 @@ public function add_subscribers_to_forms(array $forms_subscribers_ids, string $c * @param string $email_address Email Address. * @param string $referrer Referrer. * - * @see https://developers.convertkit.com/v4.html#add-subscriber-to-form-by-email-address + * @see https://developers.kit.com/v4.html#add-subscriber-to-form-by-email-address * * @return false|mixed */ @@ -290,7 +290,7 @@ public function add_subscriber_to_form_by_email(int $form_id, string $email_addr * @param integer $subscriber_id Subscriber ID. * @param string $referrer Referrer URL. * - * @see https://developers.convertkit.com/v4.html#add-subscriber-to-form + * @see https://developers.kit.com/v4.html#add-subscriber-to-form * * @since 2.0.0 * @@ -326,7 +326,7 @@ public function add_subscriber_to_form(int $form_id, int $subscriber_id, string * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.convertkit.com/v4.html#list-subscribers-for-a-form + * @see https://developers.kit.com/v4.html#list-subscribers-for-a-form * * @return false|mixed */ @@ -382,7 +382,7 @@ public function get_form_subscriptions( * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.convertkit.com/v4.html#list-sequences + * @see https://developers.kit.com/v4.html#list-sequences * * @return false|mixed */ @@ -410,7 +410,7 @@ public function get_sequences( * @param integer $sequence_id Sequence ID. * @param string $email_address Email Address. * - * @see https://developers.convertkit.com/v4.html#add-subscriber-to-sequence-by-email-address + * @see https://developers.kit.com/v4.html#add-subscriber-to-sequence-by-email-address * * @return false|mixed */ @@ -428,7 +428,7 @@ public function add_subscriber_to_sequence_by_email(int $sequence_id, string $em * @param integer $sequence_id Sequence ID. * @param integer $subscriber_id Subscriber ID. * - * @see https://developers.convertkit.com/v4.html#add-subscriber-to-sequence + * @see https://developers.kit.com/v4.html#add-subscriber-to-sequence * * @since 2.0.0 * @@ -453,7 +453,7 @@ public function add_subscriber_to_sequence(int $sequence_id, int $subscriber_id) * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.convertkit.com/v4.html#list-subscribers-for-a-sequence + * @see https://developers.kit.com/v4.html#list-subscribers-for-a-sequence * * @return false|mixed */ @@ -509,7 +509,7 @@ public function get_sequence_subscriptions( * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.convertkit.com/v4.html#list-tags + * @see https://developers.kit.com/v4.html#list-tags * * @return mixed|array */ @@ -538,7 +538,7 @@ public function get_tags( * * @since 1.0.0 * - * @see https://developers.convertkit.com/v4.html#create-a-tag + * @see https://developers.kit.com/v4.html#create-a-tag * * @return false|mixed */ @@ -558,7 +558,7 @@ public function create_tag(string $tag) * * @since 1.1.0 * - * @see https://developers.convertkit.com/v4.html#bulk-create-tags + * @see https://developers.kit.com/v4.html#bulk-create-tags * * @return false|mixed */ @@ -591,7 +591,7 @@ public function create_tags(array $tags, string $callback_url = '') * @param integer $tag_id Tag ID. * @param string $email_address Email Address. * - * @see https://developers.convertkit.com/v4.html#tag-a-subscriber-by-email-address + * @see https://developers.kit.com/v4.html#tag-a-subscriber-by-email-address * * @return false|mixed */ @@ -609,7 +609,7 @@ public function tag_subscriber_by_email(int $tag_id, string $email_address) * @param integer $tag_id Tag ID. * @param integer $subscriber_id Subscriber ID. * - * @see https://developers.convertkit.com/v4.html#tag-a-subscriber + * @see https://developers.kit.com/v4.html#tag-a-subscriber * * @return false|mixed */ @@ -626,7 +626,7 @@ public function tag_subscriber(int $tag_id, int $subscriber_id) * * @since 1.0.0 * - * @see https://developers.convertkit.com/v4.html#remove-tag-from-subscriber + * @see https://developers.kit.com/v4.html#remove-tag-from-subscriber * * @return false|mixed */ @@ -643,7 +643,7 @@ public function remove_tag_from_subscriber(int $tag_id, int $subscriber_id) * * @since 1.0.0 * - * @see https://developers.convertkit.com/v4.html#remove-tag-from-subscriber-by-email-address + * @see https://developers.kit.com/v4.html#remove-tag-from-subscriber-by-email-address * * @return false|mixed */ @@ -669,7 +669,7 @@ public function remove_tag_from_subscriber_by_email(int $tag_id, string $email_a * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.convertkit.com/v4.html#list-subscribers-for-a-tag + * @see https://developers.kit.com/v4.html#list-subscribers-for-a-tag * * @return false|mixed */ @@ -727,7 +727,7 @@ public function get_tag_subscriptions( * * @since 2.0.0 * - * @see https://developers.convertkit.com/v4.html#convertkit-api-email-templates + * @see https://developers.kit.com/v4.html#convertkit-api-email-templates * * @return false|mixed */ @@ -768,7 +768,7 @@ public function get_email_templates( * * @since 2.0.0 * - * @see https://developers.convertkit.com/v4.html#list-subscribers + * @see https://developers.kit.com/v4.html#list-subscribers * * @return false|mixed */ @@ -841,7 +841,7 @@ public function get_subscribers( * * @since 2.0.0 * - * @see https://developers.convertkit.com/v4.html#create-a-subscriber + * @see https://developers.kit.com/v4.html#create-a-subscriber * * @return mixed */ @@ -879,7 +879,7 @@ public function create_subscriber( * * @since 2.0.0 * - * @see https://developers.convertkit.com/v4.html#bulk-create-subscribers + * @see https://developers.kit.com/v4.html#bulk-create-subscribers * * @return mixed */ @@ -907,7 +907,7 @@ public function create_subscribers(array $subscribers, string $callback_url = '' * * @throws \InvalidArgumentException If the email address is not a valid email format. * - * @see https://developers.convertkit.com/v4.html#get-a-subscriber + * @see https://developers.kit.com/v4.html#get-a-subscriber * * @return false|integer */ @@ -947,7 +947,7 @@ public function get_subscriber_id(string $email_address) * * @param integer $subscriber_id Subscriber ID. * - * @see https://developers.convertkit.com/v4.html#get-a-subscriber + * @see https://developers.kit.com/v4.html#get-a-subscriber * * @return mixed|integer */ @@ -964,7 +964,7 @@ public function get_subscriber(int $subscriber_id) * @param string $email_address New Email Address. * @param array $fields Updated Custom Fields. * - * @see https://developers.convertkit.com/v4.html#update-a-subscriber + * @see https://developers.kit.com/v4.html#update-a-subscriber * * @return mixed */ @@ -999,7 +999,7 @@ public function update_subscriber( * * @param string $email_address Email Address. * - * @see https://developers.convertkit.com/v4.html#unsubscribe-subscriber + * @see https://developers.kit.com/v4.html#unsubscribe-subscriber * * @return mixed|object */ @@ -1018,7 +1018,7 @@ public function unsubscribe_by_email(string $email_address) * * @param integer $subscriber_id Subscriber ID. * - * @see https://developers.convertkit.com/v4.html#unsubscribe-subscriber + * @see https://developers.kit.com/v4.html#unsubscribe-subscriber * * @return mixed|object */ @@ -1036,7 +1036,7 @@ public function unsubscribe(int $subscriber_id) * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.convertkit.com/v4.html#list-tags-for-a-subscriber + * @see https://developers.kit.com/v4.html#list-tags-for-a-subscriber * * @return mixed|array */ @@ -1067,7 +1067,7 @@ public function get_subscriber_tags( * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.convertkit.com/v4.html#list-broadcasts + * @see https://developers.kit.com/v4.html#list-broadcasts * * @return false|mixed */ @@ -1113,7 +1113,7 @@ public function get_broadcasts( * @param string $preview_text Specify the preview text of the email. * @param array $subscriber_filter Filter subscriber(s) to send the email to. * - * @see https://developers.convertkit.com/v4.html#create-a-broadcast + * @see https://developers.kit.com/v4.html#create-a-broadcast * * @return mixed|object */ @@ -1172,7 +1172,7 @@ public function create_broadcast( * * @param integer $id Broadcast ID. * - * @see https://developers.convertkit.com/v4.html#get-a-broadcast + * @see https://developers.kit.com/v4.html#get-a-broadcast * * @return mixed|object */ @@ -1187,7 +1187,7 @@ public function get_broadcast(int $id) * * @param integer $id Broadcast ID. * - * @see https://developers.convertkit.com/v4.html#get-stats + * @see https://developers.kit.com/v4.html#get-stats * * @return mixed|object */ @@ -1220,7 +1220,7 @@ public function get_broadcast_stats(int $id) * @param string $preview_text Specify the preview text of the email. * @param array $subscriber_filter Filter subscriber(s) to send the email to. * - * @see https://developers.convertkit.com/#create-a-broadcast + * @see https://developers.kit.com/#create-a-broadcast * * @return mixed|object */ @@ -1282,7 +1282,7 @@ public function update_broadcast( * * @since 1.0.0 * - * @see https://developers.convertkit.com/v4.html#delete-a-broadcast + * @see https://developers.kit.com/v4.html#delete-a-broadcast * * @return mixed|object */ @@ -1301,7 +1301,7 @@ public function delete_broadcast(int $id) * * @since 2.0.0 * - * @see https://developers.convertkit.com/v4.html#list-webhooks + * @see https://developers.kit.com/v4.html#list-webhooks * * @return false|mixed */ @@ -1333,7 +1333,7 @@ public function get_webhooks( * * @since 1.0.0 * - * @see https://developers.convertkit.com/v4.html#create-a-webhook + * @see https://developers.kit.com/v4.html#create-a-webhook * * @throws \InvalidArgumentException If the event is not supported. * @@ -1409,7 +1409,7 @@ public function create_webhook(string $url, string $event, string $parameter = ' * * @since 1.0.0 * - * @see https://developers.convertkit.com/v4.html#delete-a-webhook + * @see https://developers.kit.com/v4.html#delete-a-webhook * * @return mixed|object */ @@ -1428,7 +1428,7 @@ public function delete_webhook(int $id) * * @since 1.0.0 * - * @see https://developers.convertkit.com/v4.html#list-custom-fields + * @see https://developers.kit.com/v4.html#list-custom-fields * * @return false|mixed */ @@ -1458,7 +1458,7 @@ public function get_custom_fields( * * @since 1.0.0 * - * @see https://developers.convertkit.com/v4.html#create-a-custom-field + * @see https://developers.kit.com/v4.html#create-a-custom-field * * @return mixed|object */ @@ -1478,7 +1478,7 @@ public function create_custom_field(string $label) * * @since 1.0.0 * - * @see https://developers.convertkit.com/v4.html#bulk-create-custom-fields + * @see https://developers.kit.com/v4.html#bulk-create-custom-fields * * @return mixed|object */ @@ -1513,7 +1513,7 @@ public function create_custom_fields(array $labels, string $callback_url = '') * * @since 1.0.0 * - * @see https://developers.convertkit.com/v4.html#update-a-custom-field + * @see https://developers.kit.com/v4.html#update-a-custom-field * * @return mixed|object */ @@ -1532,7 +1532,7 @@ public function update_custom_field(int $id, string $label) * * @since 1.0.0 * - * @see https://developers.convertkit.com/#destroy-field + * @see https://developers.kit.com/#destroy-field * * @return mixed|object */ @@ -1551,7 +1551,7 @@ public function delete_custom_field(int $id) * * @since 1.0.0 * - * @see https://developers.convertkit.com/v4.html#list-purchases + * @see https://developers.kit.com/v4.html#list-purchases * * @return false|mixed */ @@ -1579,7 +1579,7 @@ public function get_purchases( * * @param integer $purchase_id Purchase ID. * - * @see https://developers.convertkit.com/v4.html#get-a-purchase + * @see https://developers.kit.com/v4.html#get-a-purchase * * @return mixed|object */ @@ -1604,7 +1604,7 @@ public function get_purchase(int $purchase_id) * @param float $total Total. * @param \DateTime|null $transaction_time Transaction date and time. * - * @see https://developers.convertkit.com/v4.html#create-a-purchase + * @see https://developers.kit.com/v4.html#create-a-purchase * * @return mixed|object */ @@ -1666,7 +1666,7 @@ public function create_purchase( * * @since 2.0.0 * - * @see https://developers.convertkit.com/v4.html#convertkit-api-segments + * @see https://developers.kit.com/v4.html#convertkit-api-segments * * @return false|mixed */ diff --git a/tests/ConvertKitAPIKeyTest.php b/tests/ConvertKitAPIKeyTest.php index 6558399..d6f0b0c 100644 --- a/tests/ConvertKitAPIKeyTest.php +++ b/tests/ConvertKitAPIKeyTest.php @@ -494,10 +494,10 @@ public function testCreateSubscribers() $this->expectException(ClientException::class); $subscribers = [ [ - 'email_address' => str_replace('@convertkit.com', '-1@convertkit.com', $this->generateEmailAddress()), + 'email_address' => str_replace('@kit.com', '-1@kit.com', $this->generateEmailAddress()), ], [ - 'email_address' => str_replace('@convertkit.com', '-2@convertkit.com', $this->generateEmailAddress()), + 'email_address' => str_replace('@kit.com', '-2@kit.com', $this->generateEmailAddress()), ], ]; $result = $this->api->create_subscribers($subscribers); diff --git a/tests/ConvertKitAPIOAuthTest.php b/tests/ConvertKitAPIOAuthTest.php index 829d0a7..6a2d9eb 100644 --- a/tests/ConvertKitAPIOAuthTest.php +++ b/tests/ConvertKitAPIOAuthTest.php @@ -267,7 +267,7 @@ public function testGetOAuthURL() // Confirm the OAuth URL returned is correct. $this->assertEquals( $this->api->get_oauth_url($_ENV['CONVERTKIT_OAUTH_REDIRECT_URI']), - 'https://app.convertkit.com/oauth/authorize?' . http_build_query([ + 'https://app.kit.com/oauth/authorize?' . http_build_query([ 'client_id' => $_ENV['CONVERTKIT_OAUTH_CLIENT_ID'], 'redirect_uri' => $_ENV['CONVERTKIT_OAUTH_REDIRECT_URI'], 'response_type' => 'code', diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index 786d85e..82f48c1 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -3402,10 +3402,10 @@ public function testCreateSubscribers() { $subscribers = [ [ - 'email_address' => str_replace('@convertkit.com', '-1@convertkit.com', $this->generateEmailAddress()), + 'email_address' => str_replace('@kit.com', '-1@kit.com', $this->generateEmailAddress()), ], [ - 'email_address' => str_replace('@convertkit.com', '-2@convertkit.com', $this->generateEmailAddress()), + 'email_address' => str_replace('@kit.com', '-2@kit.com', $this->generateEmailAddress()), ], ]; $result = $this->api->create_subscribers($subscribers); @@ -3706,7 +3706,7 @@ public function testUnsubscribeByEmail() public function testUnsubscribeByEmailWithNotSubscribedEmailAddress() { $this->expectException(ClientException::class); - $subscriber = $this->api->unsubscribe_by_email('not-subscribed@convertkit.com'); + $subscriber = $this->api->unsubscribe_by_email('not-subscribed@kit.com'); } /** @@ -5071,7 +5071,7 @@ public function testGetResourceInvalidURL() public function testGetResourceInaccessibleURL() { $this->expectException(ClientException::class); - $markup = $this->api->get_resource('https://convertkit.com/a/url/that/does/not/exist'); + $markup = $this->api->get_resource('https://kit.com/a/url/that/does/not/exist'); } /** From 53afc2f00dfc4c039542742a449f6af9b193d3d6 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 12:32:21 +0800 Subject: [PATCH 02/17] Add composer commands --- TESTING.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/TESTING.md b/TESTING.md index 59cf0fe..122d9a9 100644 --- a/TESTING.md +++ b/TESTING.md @@ -14,6 +14,19 @@ If you haven't yet set up your local development environment, refer to the [Setu If you haven't yet created a branch and made any code changes, refer to the [Development Guide](DEVELOPMENT.md) +### Familiar with PHP Coding Standards, PHPStan and PHPUnit? + +The following Composer commands can be used: + +| Command | Short Command | Description | +|---------|---------------|-------------| +| `composer php-coding-standards` | `composer phpcs` | Runs PHP Coding Standards on the `/src` folder | +| `composer fix-php-coding-standards` | `composer phpcbf` | Fix PHP files to meet PHP Coding Standards on the `/src` folder | +| `composer php-coding-standards-on-tests` | `composer phpcs-tests` | Runs PHP Coding Standards on the `/tests` folder | +| `composer fix-php-coding-standards-on-tests` | `composer phpcbf-tests` | Fix PHP files to meet PHP Coding Standards on the `/tests` folder | +| `composer static-analysis` | `composer phpstan` | Runs PHPStan static analysis with increased memory limit | +| `composer test` | `composer test` | Builds and runs WPUnit tests | + ## Write (or modify) a test If your work creates new functionality, write a test. From d8cbe6792a9628cf3c5401ece4101fd5c3e99077 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 12:32:41 +0800 Subject: [PATCH 03/17] Revert composer commands --- composer.json | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/composer.json b/composer.json index 3a62e0f..9e82db0 100644 --- a/composer.json +++ b/composer.json @@ -44,17 +44,6 @@ "minimum-stability": "dev", "prefer-stable": true, "scripts": { - "create-docs": "phpDocumentor --directory=src --target=docs --template='vendor/saggre/phpdocumentor-markdown/themes/markdown'", - "phpcs": "vendor/bin/phpcs ./ -s -v", - "phpcbf": "vendor/bin/phpcbf ./ -s -v", - "phpcs-tests": "vendor/bin/phpcs ./tests --standard=phpcs.tests.xml -s -v", - "phpcbf-tests": "vendor/bin/phpcbf ./tests --standard=phpcs.tests.xml -s -v", - "phpstan": "vendor/bin/phpstan analyse --memory-limit=1250M", - "php-coding-standards": "vendor/bin/phpcs ./ -s -v", - "fix-php-coding-standards": "vendor/bin/phpcbf ./ -s -v", - "php-coding-standards-on-tests": "vendor/bin/phpcs ./tests --standard=phpcs.tests.xml -s -v", - "fix-php-coding-standards-on-tests": "vendor/bin/phpcbf ./tests --standard=phpcs.tests.xml -s -v", - "php-static-analysis": "vendor/bin/phpstan analyse --memory-limit=1250M", - "test": "vendor/bin/phpunit" + "create-docs": "phpDocumentor --directory=src --target=docs --template='vendor/saggre/phpdocumentor-markdown/themes/markdown'" } } From fbc73e2f22173b1788e6435c99d3d02d3506a3e2 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 12:48:42 +0800 Subject: [PATCH 04/17] Fix API Doc Generation --- composer.json | 3 +- docs/Home.md | 18 + docs/classes/ConvertKit_API/ConvertKit_API.md | 1183 +++++++------- .../ConvertKit_API/ConvertKit_API_Traits.md | 1397 +++++++++++++++++ 4 files changed, 2038 insertions(+), 563 deletions(-) create mode 100644 docs/Home.md create mode 100644 docs/classes/ConvertKit_API/ConvertKit_API_Traits.md diff --git a/composer.json b/composer.json index 30a377e..ce31a17 100644 --- a/composer.json +++ b/composer.json @@ -23,7 +23,8 @@ "vlucas/phpdotenv": "^5.5", "phpunit/phpunit": "^5.7 || ^9.0", "squizlabs/php_codesniffer": "^3.3", - "phpstan/phpstan": "^2.0" + "phpstan/phpstan": "^2.0", + "saggre/phpdocumentor-markdown": "^1.0" }, "autoload": { "psr-4": { diff --git a/docs/Home.md b/docs/Home.md new file mode 100644 index 0000000..a452da0 --- /dev/null +++ b/docs/Home.md @@ -0,0 +1,18 @@ + +This is an automatically generated documentation for **Documentation**. + +## Namespaces + +### \ConvertKit_API + +#### Classes + +| Class | Description | +|-------------------------------------------------------------|----------------------| +| [`ConvertKit_API`](./classes/ConvertKit_API/ConvertKit_API) | ConvertKit API Class | + +#### Traits + +| Trait | Description | +|---------------------------------------------------------------------------|-----------------------| +| [`ConvertKit_API_Traits`](./classes/ConvertKit_API/ConvertKit_API_Traits) | ConvertKit API Traits | diff --git a/docs/classes/ConvertKit_API/ConvertKit_API.md b/docs/classes/ConvertKit_API/ConvertKit_API.md index c2a1db3..1766fef 100644 --- a/docs/classes/ConvertKit_API/ConvertKit_API.md +++ b/docs/classes/ConvertKit_API/ConvertKit_API.md @@ -1,13 +1,16 @@ -# ConvertKit_API ConvertKit API Class + +*** + * Full name: `\ConvertKit_API\ConvertKit_API` ## Constants -| Constant | Visibility | Type | Value | -|:---------|:-----------|:-----|:------| -|`VERSION`|public|string|'2.0.0'| +| Constant | Visibility | Type | Value | +|-----------|------------|--------|---------| +| `VERSION` | public | string | '2.0.0' | + ## Properties ### debug @@ -18,6 +21,8 @@ Debug protected bool $debug ``` +*** + ### debug_logger Debug @@ -26,6 +31,8 @@ Debug protected \Monolog\Logger $debug_logger ``` +*** + ### client Guzzle Http ClientInterface @@ -34,6 +41,8 @@ Guzzle Http ClientInterface protected \GuzzleHttp\ClientInterface $client ``` +*** + ### response Guzzle Http Response @@ -42,6 +51,8 @@ Guzzle Http Response protected \Psr\Http\Message\ResponseInterface $response ``` +*** + ## Methods ### __construct @@ -49,22 +60,22 @@ protected \Psr\Http\Message\ResponseInterface $response Constructor for ConvertKitAPI instance ```php -public __construct(string $clientID, string $clientSecret, string $accessToken = '', bool $debug = false, string $debugLogFileLocation = ''): mixed +public __construct(string $clientID = '', string $clientSecret = '', string $accessToken = '', string $apiKey = '', bool $debug = false, string $debugLogFileLocation = ''): mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$clientID` | **string** | OAuth Client ID. | -| `$clientSecret` | **string** | OAuth Client Secret. | -| `$accessToken` | **string** | OAuth Access Token. | -| `$debug` | **bool** | Log requests to debugger. | +| Parameter | Type | Description | +|-------------------------|------------|----------------------------------------------| +| `$clientID` | **string** | OAuth Client ID. | +| `$clientSecret` | **string** | OAuth Client Secret. | +| `$accessToken` | **string** | OAuth Access Token. | +| `$apiKey` | **string** | API Key. | +| `$debug` | **bool** | Log requests to debugger. | | `$debugLogFileLocation` | **string** | Path and filename of debug file to write to. | +*** ---- ### set_http_client Set the Guzzle client implementation to use for API requests. @@ -73,15 +84,14 @@ Set the Guzzle client implementation to use for API requests. public set_http_client(\GuzzleHttp\ClientInterface $client): void ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| +| Parameter | Type | Description | +|-----------|---------------------------------|-------------------------------| | `$client` | **\GuzzleHttp\ClientInterface** | Guzzle client implementation. | +*** ---- ### create_log Add an entry to monologger. @@ -90,15 +100,14 @@ Add an entry to monologger. private create_log(string $message): void ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$message` | **string** | Message. | +| Parameter | Type | Description | +|------------|------------|-------------| +| `$message` | **string** | Message. | +*** ---- ### get_oauth_url Returns the OAuth URL to begin the OAuth process. @@ -107,59 +116,56 @@ Returns the OAuth URL to begin the OAuth process. public get_oauth_url(string $redirectURI): string ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| +| Parameter | Type | Description | +|----------------|------------|---------------| | `$redirectURI` | **string** | Redirect URI. | +*** ---- ### get_access_token Exchanges the given authorization code for an access token and refresh token. ```php -public get_access_token(string $authCode, string $redirectURI): array +public get_access_token(string $authCode, string $redirectURI): mixed|array ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$authCode` | **string** | Authorization Code, returned from get_oauth_url() flow. | -| `$redirectURI` | **string** | Redirect URI. | +| Parameter | Type | Description | +|----------------|------------|---------------------------------------------------------| +| `$authCode` | **string** | Authorization Code, returned from get_oauth_url() flow. | +| `$redirectURI` | **string** | Redirect URI. | **Return Value:** API response +*** ---- ### refresh_token Fetches a new access token using the supplied refresh token. ```php -public refresh_token(string $refreshToken, string $redirectURI): array +public refresh_token(string $refreshToken, string $redirectURI): mixed|array ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| +| Parameter | Type | Description | +|-----------------|------------|----------------| | `$refreshToken` | **string** | Refresh Token. | -| `$redirectURI` | **string** | Redirect URI. | +| `$redirectURI` | **string** | Redirect URI. | **Return Value:** API response +*** ---- ### get_resource Get markup from ConvertKit for the provided $url. @@ -167,6 +173,7 @@ Get markup from ConvertKit for the provided $url. ```php public get_resource(string $url): false|string ``` + Supports legacy forms and legacy landing pages. Forms and Landing Pages should be embedded using the supplied JS embed script in @@ -174,31 +181,42 @@ the API response when using get_forms() or get_landing_pages(). **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$url` | **string** | URL of HTML page. | +| Parameter | Type | Description | +|-----------|------------|-------------------| +| `$url` | **string** | URL of HTML page. | +**Throws:** + +If the URL is not a valid URL format. +- [`InvalidArgumentException`](../InvalidArgumentException) +If parsing the legacy form or landing page failed. +- [`Exception`](../Exception) + +*** ---- ### request Performs an API request using Guzzle. ```php -public request(string $endpoint, string $method, array> $args = []): false|mixed +public request(string $endpoint, string $method, array> $args = []): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$endpoint` | **string** | API Endpoint. | -| `$method` | **string** | Request method. | -| `$args` | **array>** | Request arguments. | +| Parameter | Type | Description | +|-------------|-----------------------------------------------------------------------------------------------------|--------------------| +| `$endpoint` | **string** | API Endpoint. | +| `$method` | **string** | Request method. | +| `$args` | **array>** | Request arguments. | + +**Throws:** +If JSON encoding arguments failed. +- [`Exception`](../Exception) + +*** ---- ### getResponseInterface Returns the response interface used for the last API request. @@ -207,9 +225,8 @@ Returns the response interface used for the last API request. public getResponseInterface(): \Psr\Http\Message\ResponseInterface ``` +*** - ---- ### get_request_headers Returns the headers to use in an API request. @@ -218,16 +235,15 @@ Returns the headers to use in an API request. public get_request_headers(string $type = 'application/json', bool $auth = true): array ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$type` | **string** | Accept and Content-Type Headers. | -| `$auth` | **bool** | Include authorization header. | +| Parameter | Type | Description | +|-----------|------------|----------------------------------| +| `$type` | **string** | Accept and Content-Type Headers. | +| `$auth` | **bool** | Include authorization header. | +*** ---- ### get_timeout Returns the maximum amount of time to wait for @@ -237,13 +253,12 @@ a response to the request before exiting. public get_timeout(): int ``` - **Return Value:** Timeout, in seconds. +*** ---- ### get_user_agent Returns the user agent string to use in all HTTP requests. @@ -252,9 +267,7 @@ Returns the user agent string to use in all HTTP requests. public get_user_agent(): string ``` - - ---- +*** ## Inherited methods @@ -266,12 +279,12 @@ Gets the current account public get_account(): false|mixed ``` - **See Also:** -* https://developers.convertkit.com/v4.html#get-current-account +* https://developers.convertkit.com/v4.html#get-current-account + +*** ---- ### get_account_colors Gets the account's colors @@ -280,12 +293,12 @@ Gets the account's colors public get_account_colors(): false|mixed ``` - **See Also:** -* https://developers.convertkit.com/v4.html#list-colors +* https://developers.convertkit.com/v4.html#list-colors + +*** ---- ### update_account_colors Gets the account's colors @@ -294,18 +307,18 @@ Gets the account's colors public update_account_colors(array $colors): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| +| Parameter | Type | Description | +|-----------|--------------------------|-------------| | `$colors` | **array** | Hex colors. | **See Also:** -* https://developers.convertkit.com/v4.html#list-colors +* https://developers.convertkit.com/v4.html#list-colors + +*** ---- ### get_creator_profile Gets the Creator Profile @@ -314,12 +327,12 @@ Gets the Creator Profile public get_creator_profile(): false|mixed ``` - **See Also:** -* https://developers.convertkit.com/v4.html#get-creator-profile +* https://developers.convertkit.com/v4.html#get-creator-profile + +*** ---- ### get_email_stats Gets email stats @@ -328,152 +341,175 @@ Gets email stats public get_email_stats(): false|mixed ``` - **See Also:** -* https://developers.convertkit.com/v4.html#get-email-stats +* https://developers.convertkit.com/v4.html#get-email-stats + +*** ---- ### get_growth_stats Gets growth stats ```php -public get_growth_stats(\DateTime $starting = null, \DateTime $ending = null): false|mixed +public get_growth_stats(\DateTime|null $starting = null, \DateTime|null $ending = null): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$starting` | **\DateTime** | Gets stats for time period beginning on this date. Defaults to 90 days ago. | -| `$ending` | **\DateTime** | Gets stats for time period ending on this date. Defaults to today. | +| Parameter | Type | Description | +|-------------|---------------------|-----------------------------------------------------------------------------| +| `$starting` | **\DateTime\|null** | Gets stats for time period beginning on this date. Defaults to 90 days ago. | +| `$ending` | **\DateTime\|null** | Gets stats for time period ending on this date. Defaults to today. | **See Also:** -* https://developers.convertkit.com/v4.html#get-growth-stats +* https://developers.convertkit.com/v4.html#get-growth-stats + +*** ---- ### get_forms Get forms. ```php -public get_forms(string $status = 'active', bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|array +public get_forms(string $status = 'active', bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): mixed|array ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$status` | **string** | Form status (active\|archived\|trashed\|all). | -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$status` | **string** | Form status (active\|archived\|trashed\|all). | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#convertkit-api-forms +* https://developers.convertkit.com/v4.html#convertkit-api-forms + +*** ---- ### get_landing_pages Get landing pages. ```php -public get_landing_pages(string $status = 'active', bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|array +public get_landing_pages(string $status = 'active', bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): mixed|array ``` +**Parameters:** + +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$status` | **string** | Form status (active\|archived\|trashed\|all). | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#convertkit-api-forms + +*** + +### add_subscribers_to_forms + +Adds subscribers to forms in bulk. + +```php +public add_subscribers_to_forms(array[] $forms_subscribers_ids, string $callback_url = ''): mixed|object +``` **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$status` | **string** | Form status (active\|archived\|trashed\|all). | -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------| +| `$forms_subscribers_ids` | **array[]** | Array of arrays comprising of `form_id`, `subscriber_id` and optional `referrer` URL. | +| `$callback_url` | **string** | URL to notify for large batch size when async processing complete. | **See Also:** -* https://developers.convertkit.com/v4.html#convertkit-api-forms +* https://developers.kit.com/v4.html#bulk-add-subscribers-to-forms + +*** ---- ### add_subscriber_to_form_by_email Adds a subscriber to a form by email address ```php -public add_subscriber_to_form_by_email(int $form_id, string $email_address): false|mixed +public add_subscriber_to_form_by_email(int $form_id, string $email_address, string $referrer = ''): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$form_id` | **int** | Form ID. | +| Parameter | Type | Description | +|------------------|------------|----------------| +| `$form_id` | **int** | Form ID. | | `$email_address` | **string** | Email Address. | +| `$referrer` | **string** | Referrer. | **See Also:** -* https://developers.convertkit.com/v4.html#add-subscriber-to-form-by-email-address +* https://developers.convertkit.com/v4.html#add-subscriber-to-form-by-email-address + +*** ---- ### add_subscriber_to_form Adds a subscriber to a form by subscriber ID ```php -public add_subscriber_to_form(int $form_id, int $subscriber_id): false|mixed +public add_subscriber_to_form(int $form_id, int $subscriber_id, string $referrer = ''): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$form_id` | **int** | Form ID. | -| `$subscriber_id` | **int** | Subscriber ID. | +| Parameter | Type | Description | +|------------------|------------|----------------| +| `$form_id` | **int** | Form ID. | +| `$subscriber_id` | **int** | Subscriber ID. | +| `$referrer` | **string** | Referrer URL. | **See Also:** -* https://developers.convertkit.com/v4.html#add-subscriber-to-form +* https://developers.convertkit.com/v4.html#add-subscriber-to-form + +*** ---- ### get_form_subscriptions List subscribers for a form ```php -public get_form_subscriptions(int $form_id, string $subscriber_state = 'active', \DateTime $created_after = null, \DateTime $created_before = null, \DateTime $added_after = null, \DateTime $added_before = null, bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +public get_form_subscriptions(int $form_id, string $subscriber_state = 'active', \DateTime|null $created_after = null, \DateTime|null $created_before = null, \DateTime|null $added_after = null, \DateTime|null $added_before = null, bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$form_id` | **int** | Form ID. | -| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | -| `$created_after` | **\DateTime** | Filter subscribers who have been created after this date. | -| `$created_before` | **\DateTime** | Filter subscribers who have been created before this date. | -| `$added_after` | **\DateTime** | Filter subscribers who have been added to the form after this date. | -| `$added_before` | **\DateTime** | Filter subscribers who have been added to the form before this date. | -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|---------------------|----------------------------------------------------------------------| +| `$form_id` | **int** | Form ID. | +| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | +| `$created_after` | **\DateTime\|null** | Filter subscribers who have been created after this date. | +| `$created_before` | **\DateTime\|null** | Filter subscribers who have been created before this date. | +| `$added_after` | **\DateTime\|null** | Filter subscribers who have been added to the form after this date. | +| `$added_before` | **\DateTime\|null** | Filter subscribers who have been added to the form before this date. | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#list-subscribers-for-a-form +* https://developers.convertkit.com/v4.html#list-subscribers-for-a-form + +*** ---- ### get_sequences Gets sequences @@ -482,21 +518,21 @@ Gets sequences public get_sequences(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#list-sequences +* https://developers.convertkit.com/v4.html#list-sequences + +*** ---- ### add_subscriber_to_sequence_by_email Adds a subscriber to a sequence by email address @@ -505,19 +541,19 @@ Adds a subscriber to a sequence by email address public add_subscriber_to_sequence_by_email(int $sequence_id, string $email_address): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$sequence_id` | **int** | Sequence ID. | +| Parameter | Type | Description | +|------------------|------------|----------------| +| `$sequence_id` | **int** | Sequence ID. | | `$email_address` | **string** | Email Address. | **See Also:** -* https://developers.convertkit.com/v4.html#add-subscriber-to-sequence-by-email-address +* https://developers.convertkit.com/v4.html#add-subscriber-to-sequence-by-email-address + +*** ---- ### add_subscriber_to_sequence Adds a subscriber to a sequence by subscriber ID @@ -526,71 +562,71 @@ Adds a subscriber to a sequence by subscriber ID public add_subscriber_to_sequence(int $sequence_id, int $subscriber_id): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$sequence_id` | **int** | Sequence ID. | +| Parameter | Type | Description | +|------------------|---------|----------------| +| `$sequence_id` | **int** | Sequence ID. | | `$subscriber_id` | **int** | Subscriber ID. | **See Also:** -* https://developers.convertkit.com/v4.html#add-subscriber-to-sequence +* https://developers.convertkit.com/v4.html#add-subscriber-to-sequence + +*** ---- ### get_sequence_subscriptions List subscribers for a sequence ```php -public get_sequence_subscriptions(int $sequence_id, string $subscriber_state = 'active', \DateTime $created_after = null, \DateTime $created_before = null, \DateTime $added_after = null, \DateTime $added_before = null, bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +public get_sequence_subscriptions(int $sequence_id, string $subscriber_state = 'active', \DateTime|null $created_after = null, \DateTime|null $created_before = null, \DateTime|null $added_after = null, \DateTime|null $added_before = null, bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$sequence_id` | **int** | Sequence ID. | -| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | -| `$created_after` | **\DateTime** | Filter subscribers who have been created after this date. | -| `$created_before` | **\DateTime** | Filter subscribers who have been created before this date. | -| `$added_after` | **\DateTime** | Filter subscribers who have been added to the form after this date. | -| `$added_before` | **\DateTime** | Filter subscribers who have been added to the form before this date. | -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|---------------------|----------------------------------------------------------------------| +| `$sequence_id` | **int** | Sequence ID. | +| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | +| `$created_after` | **\DateTime\|null** | Filter subscribers who have been created after this date. | +| `$created_before` | **\DateTime\|null** | Filter subscribers who have been created before this date. | +| `$added_after` | **\DateTime\|null** | Filter subscribers who have been added to the form after this date. | +| `$added_before` | **\DateTime\|null** | Filter subscribers who have been added to the form before this date. | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#list-subscribers-for-a-sequence +* https://developers.convertkit.com/v4.html#list-subscribers-for-a-sequence + +*** ---- ### get_tags List tags. ```php -public get_tags(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|array +public get_tags(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): mixed|array ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#list-tags +* https://developers.convertkit.com/v4.html#list-tags + +*** ---- ### create_tag Creates a tag. @@ -599,18 +635,18 @@ Creates a tag. public create_tag(string $tag): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$tag` | **string** | Tag Name. | +| Parameter | Type | Description | +|-----------|------------|-------------| +| `$tag` | **string** | Tag Name. | **See Also:** -* https://developers.convertkit.com/v4.html#create-a-tag +* https://developers.convertkit.com/v4.html#create-a-tag + +*** ---- ### create_tags Creates multiple tags. @@ -619,19 +655,19 @@ Creates multiple tags. public create_tags(array $tags, string $callback_url = ''): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$tags` | **array** | Tag Names. | -| `$callback_url` | **string** | URL to notify for large batch size when async processing complete. | +| Parameter | Type | Description | +|-----------------|-----------------------|--------------------------------------------------------------------| +| `$tags` | **array** | Tag Names. | +| `$callback_url` | **string** | URL to notify for large batch size when async processing complete. | **See Also:** -* https://developers.convertkit.com/v4.html#bulk-create-tags +* https://developers.convertkit.com/v4.html#bulk-create-tags + +*** ---- ### tag_subscriber_by_email Tags a subscriber with the given existing Tag. @@ -640,19 +676,19 @@ Tags a subscriber with the given existing Tag. public tag_subscriber_by_email(int $tag_id, string $email_address): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$tag_id` | **int** | Tag ID. | +| Parameter | Type | Description | +|------------------|------------|----------------| +| `$tag_id` | **int** | Tag ID. | | `$email_address` | **string** | Email Address. | **See Also:** -* https://developers.convertkit.com/v4.html#tag-a-subscriber-by-email-address +* https://developers.convertkit.com/v4.html#tag-a-subscriber-by-email-address + +*** ---- ### tag_subscriber Tags a subscriber by subscriber ID with the given existing Tag. @@ -661,19 +697,19 @@ Tags a subscriber by subscriber ID with the given existing Tag. public tag_subscriber(int $tag_id, int $subscriber_id): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$tag_id` | **int** | Tag ID. | +| Parameter | Type | Description | +|------------------|---------|----------------| +| `$tag_id` | **int** | Tag ID. | | `$subscriber_id` | **int** | Subscriber ID. | **See Also:** -* https://developers.convertkit.com/v4.html#tag-a-subscriber +* https://developers.convertkit.com/v4.html#tag-a-subscriber + +*** ---- ### remove_tag_from_subscriber Removes a tag from a subscriber. @@ -682,19 +718,19 @@ Removes a tag from a subscriber. public remove_tag_from_subscriber(int $tag_id, int $subscriber_id): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$tag_id` | **int** | Tag ID. | +| Parameter | Type | Description | +|------------------|---------|----------------| +| `$tag_id` | **int** | Tag ID. | | `$subscriber_id` | **int** | Subscriber ID. | **See Also:** -* https://developers.convertkit.com/v4.html#remove-tag-from-subscriber +* https://developers.convertkit.com/v4.html#remove-tag-from-subscriber + +*** ---- ### remove_tag_from_subscriber_by_email Removes a tag from a subscriber by email address. @@ -703,48 +739,48 @@ Removes a tag from a subscriber by email address. public remove_tag_from_subscriber_by_email(int $tag_id, string $email_address): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$tag_id` | **int** | Tag ID. | +| Parameter | Type | Description | +|------------------|------------|---------------------------| +| `$tag_id` | **int** | Tag ID. | | `$email_address` | **string** | Subscriber email address. | **See Also:** -* https://developers.convertkit.com/v4.html#remove-tag-from-subscriber-by-email-address +* https://developers.convertkit.com/v4.html#remove-tag-from-subscriber-by-email-address + +*** ---- ### get_tag_subscriptions List subscribers for a tag ```php -public get_tag_subscriptions(int $tag_id, string $subscriber_state = 'active', \DateTime $created_after = null, \DateTime $created_before = null, \DateTime $tagged_after = null, \DateTime $tagged_before = null, bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +public get_tag_subscriptions(int $tag_id, string $subscriber_state = 'active', \DateTime|null $created_after = null, \DateTime|null $created_before = null, \DateTime|null $tagged_after = null, \DateTime|null $tagged_before = null, bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$tag_id` | **int** | Tag ID. | -| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | -| `$created_after` | **\DateTime** | Filter subscribers who have been created after this date. | -| `$created_before` | **\DateTime** | Filter subscribers who have been created before this date. | -| `$tagged_after` | **\DateTime** | Filter subscribers who have been tagged after this date. | -| `$tagged_before` | **\DateTime** | Filter subscribers who have been tagged before this date. | -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|---------------------|----------------------------------------------------------------------| +| `$tag_id` | **int** | Tag ID. | +| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | +| `$created_after` | **\DateTime\|null** | Filter subscribers who have been created after this date. | +| `$created_before` | **\DateTime\|null** | Filter subscribers who have been created before this date. | +| `$tagged_after` | **\DateTime\|null** | Filter subscribers who have been tagged after this date. | +| `$tagged_before` | **\DateTime\|null** | Filter subscribers who have been tagged before this date. | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#list-subscribers-for-a-tag +* https://developers.convertkit.com/v4.html#list-subscribers-for-a-tag + +*** ---- ### get_email_templates List email templates. @@ -753,52 +789,52 @@ List email templates. public get_email_templates(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#convertkit-api-email-templates +* https://developers.convertkit.com/v4.html#convertkit-api-email-templates + +*** ---- ### get_subscribers List subscribers. ```php -public get_subscribers(string $subscriber_state = 'active', string $email_address = '', \DateTime $created_after = null, \DateTime $created_before = null, \DateTime $updated_after = null, \DateTime $updated_before = null, string $sort_field = 'id', string $sort_order = 'desc', bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +public get_subscribers(string $subscriber_state = 'active', string $email_address = '', \DateTime|null $created_after = null, \DateTime|null $created_before = null, \DateTime|null $updated_after = null, \DateTime|null $updated_before = null, string $sort_field = 'id', string $sort_order = 'desc', bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | -| `$email_address` | **string** | Search susbcribers by email address. This is an exact match search. | -| `$created_after` | **\DateTime** | Filter subscribers who have been created after this date. | -| `$created_before` | **\DateTime** | Filter subscribers who have been created before this date. | -| `$updated_after` | **\DateTime** | Filter subscribers who have been updated after this date. | -| `$updated_before` | **\DateTime** | Filter subscribers who have been updated before this date. | -| `$sort_field` | **string** | Sort Field (id\|updated_at\|cancelled_at). | -| `$sort_order` | **string** | Sort Order (asc\|desc). | -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|---------------------|----------------------------------------------------------------------| +| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | +| `$email_address` | **string** | Search susbcribers by email address. This is an exact match search. | +| `$created_after` | **\DateTime\|null** | Filter subscribers who have been created after this date. | +| `$created_before` | **\DateTime\|null** | Filter subscribers who have been created before this date. | +| `$updated_after` | **\DateTime\|null** | Filter subscribers who have been updated after this date. | +| `$updated_before` | **\DateTime\|null** | Filter subscribers who have been updated before this date. | +| `$sort_field` | **string** | Sort Field (id\|updated_at\|cancelled_at). | +| `$sort_order` | **string** | Sort Order (asc\|desc). | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#list-subscribers +* https://developers.convertkit.com/v4.html#list-subscribers + +*** ---- ### create_subscriber Create a subscriber. @@ -806,24 +842,26 @@ Create a subscriber. ```php public create_subscriber(string $email_address, string $first_name = '', string $subscriber_state = '', array $fields = []): mixed ``` + Behaves as an upsert. If a subscriber with the provided email address does not exist, it creates one with the specified first name and state. If a subscriber with the provided email address already exists, it updates the first name. **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$email_address` | **string** | Email Address. | -| `$first_name` | **string** | First Name. | -| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | -| `$fields` | **array** | Custom Fields. | +| Parameter | Type | Description | +|---------------------|--------------------------|----------------------------------------------------------------------| +| `$email_address` | **string** | Email Address. | +| `$first_name` | **string** | First Name. | +| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | +| `$fields` | **array** | Custom Fields. | **See Also:** -* https://developers.convertkit.com/v4.html#create-a-subscriber +* https://developers.convertkit.com/v4.html#create-a-subscriber + +*** ---- ### create_subscribers Create multiple subscribers. @@ -832,19 +870,19 @@ Create multiple subscribers. public create_subscribers(array> $subscribers, string $callback_url = ''): mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$subscribers` | **array>** | Subscribers. | -| `$callback_url` | **string** | URL to notify for large batch size when async processing complete. | +| Parameter | Type | Description | +|-----------------|-------------------------------------|--------------------------------------------------------------------| +| `$subscribers` | **array>** | Subscribers. | +| `$callback_url` | **string** | URL to notify for large batch size when async processing complete. | **See Also:** -* https://developers.convertkit.com/v4.html#bulk-create-subscribers +* https://developers.convertkit.com/v4.html#bulk-create-subscribers + +*** ---- ### get_subscriber_id Get the ConvertKit subscriber ID associated with email address if it exists. @@ -852,126 +890,133 @@ Get the ConvertKit subscriber ID associated with email address if it exists. ```php public get_subscriber_id(string $email_address): false|int ``` + Return false if subscriber not found. **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| +| Parameter | Type | Description | +|------------------|------------|----------------| | `$email_address` | **string** | Email Address. | +**Throws:** + +If the email address is not a valid email format. +- [`InvalidArgumentException`](../InvalidArgumentException) + **See Also:** -* https://developers.convertkit.com/v4.html#get-a-subscriber +* https://developers.convertkit.com/v4.html#get-a-subscriber + +*** ---- ### get_subscriber Get subscriber by id ```php -public get_subscriber(int $subscriber_id): false|int +public get_subscriber(int $subscriber_id): mixed|int ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| +| Parameter | Type | Description | +|------------------|---------|----------------| | `$subscriber_id` | **int** | Subscriber ID. | **See Also:** -* https://developers.convertkit.com/v4.html#get-a-subscriber +* https://developers.convertkit.com/v4.html#get-a-subscriber + +*** ---- ### update_subscriber Updates the information for a single subscriber. ```php -public update_subscriber(int $subscriber_id, string $first_name = '', string $email_address = '', array $fields = []): false|mixed +public update_subscriber(int $subscriber_id, string $first_name = '', string $email_address = '', array $fields = []): mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$subscriber_id` | **int** | Existing Subscriber ID. | -| `$first_name` | **string** | New First Name. | -| `$email_address` | **string** | New Email Address. | -| `$fields` | **array** | Updated Custom Fields. | +| Parameter | Type | Description | +|------------------|--------------------------|-------------------------| +| `$subscriber_id` | **int** | Existing Subscriber ID. | +| `$first_name` | **string** | New First Name. | +| `$email_address` | **string** | New Email Address. | +| `$fields` | **array** | Updated Custom Fields. | **See Also:** -* https://developers.convertkit.com/v4.html#update-a-subscriber +* https://developers.convertkit.com/v4.html#update-a-subscriber + +*** ---- ### unsubscribe_by_email Unsubscribe an email address. ```php -public unsubscribe_by_email(string $email_address): false|object +public unsubscribe_by_email(string $email_address): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| +| Parameter | Type | Description | +|------------------|------------|----------------| | `$email_address` | **string** | Email Address. | **See Also:** -* https://developers.convertkit.com/v4.html#unsubscribe-subscriber +* https://developers.convertkit.com/v4.html#unsubscribe-subscriber + +*** ---- ### unsubscribe Unsubscribe the given subscriber ID. ```php -public unsubscribe(int $subscriber_id): false|object +public unsubscribe(int $subscriber_id): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| +| Parameter | Type | Description | +|------------------|---------|----------------| | `$subscriber_id` | **int** | Subscriber ID. | **See Also:** -* https://developers.convertkit.com/v4.html#unsubscribe-subscriber +* https://developers.convertkit.com/v4.html#unsubscribe-subscriber + +*** ---- ### get_subscriber_tags Get a list of the tags for a subscriber. ```php -public get_subscriber_tags(int $subscriber_id, bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|array +public get_subscriber_tags(int $subscriber_id, bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): mixed|array ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$subscriber_id` | **int** | Subscriber ID. | -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$subscriber_id` | **int** | Subscriber ID. | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#list-tags-for-a-subscriber +* https://developers.convertkit.com/v4.html#list-tags-for-a-subscriber + +*** ---- ### get_broadcasts List broadcasts. @@ -980,145 +1025,159 @@ List broadcasts. public get_broadcasts(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#list-broadcasts +* https://developers.convertkit.com/v4.html#list-broadcasts + +*** ---- ### create_broadcast Creates a broadcast. ```php -public create_broadcast(string $subject = '', string $content = '', string $description = '', bool $public = false, \DateTime $published_at = null, \DateTime $send_at = null, string $email_address = '', string $email_template_id = '', string $thumbnail_alt = '', string $thumbnail_url = '', string $preview_text = '', array $subscriber_filter = []): false|object +public create_broadcast(string $subject = '', string $content = '', string $description = '', bool $public = false, \DateTime|null $published_at = null, \DateTime|null $send_at = null, string $email_address = '', string $email_template_id = '', string $thumbnail_alt = '', string $thumbnail_url = '', string $preview_text = '', array $subscriber_filter = []): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$subject` | **string** | The broadcast email's subject. | -| `$content` | **string** | The broadcast's email HTML content. | -| `$description` | **string** | An internal description of this broadcast. | -| `$public` | **bool** | Specifies whether or not this is a public post. | -| `$published_at` | **\DateTime** | Specifies the time that this post was published (applicable
only to public posts). | -| `$send_at` | **\DateTime** | Time that this broadcast should be sent; leave blank to create
a draft broadcast. If set to a future time, this is the time that
the broadcast will be scheduled to send. | -| `$email_address` | **string** | Sending email address; leave blank to use your account's
default sending email address. | -| `$email_template_id` | **string** | ID of the email template to use; leave blank to use your
account's default email template. | -| `$thumbnail_alt` | **string** | Specify the ALT attribute of the public thumbnail image
(applicable only to public posts). | -| `$thumbnail_url` | **string** | Specify the URL of the thumbnail image to accompany the broadcast
post (applicable only to public posts). | -| `$preview_text` | **string** | Specify the preview text of the email. | -| `$subscriber_filter` | **array** | Filter subscriber(s) to send the email to. | +| Parameter | Type | Description | +|----------------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `$subject` | **string** | The broadcast email's subject. | +| `$content` | **string** | The broadcast's email HTML content. | +| `$description` | **string** | An internal description of this broadcast. | +| `$public` | **bool** | Specifies whether or not this is a public post. | +| `$published_at` | **\DateTime\|null** | Specifies the time that this post was published (applicable +only to public posts). | +| `$send_at` | **\DateTime\|null** | Time that this broadcast should be sent; leave blank to create +a draft broadcast. If set to a future time, this is the time that +the broadcast will be scheduled to send. | +| `$email_address` | **string** | Sending email address; leave blank to use your account's +default sending email address. | +| `$email_template_id` | **string** | ID of the email template to use; leave blank to use your +account's default email template. | +| `$thumbnail_alt` | **string** | Specify the ALT attribute of the public thumbnail image +(applicable only to public posts). | +| `$thumbnail_url` | **string** | Specify the URL of the thumbnail image to accompany the broadcast +post (applicable only to public posts). | +| `$preview_text` | **string** | Specify the preview text of the email. | +| `$subscriber_filter` | **array** | Filter subscriber(s) to send the email to. | **See Also:** -* https://developers.convertkit.com/v4.html#create-a-broadcast +* https://developers.convertkit.com/v4.html#create-a-broadcast + +*** ---- ### get_broadcast Retrieve a specific broadcast. ```php -public get_broadcast(int $id): false|object +public get_broadcast(int $id): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$id` | **int** | Broadcast ID. | +| Parameter | Type | Description | +|-----------|---------|---------------| +| `$id` | **int** | Broadcast ID. | **See Also:** -* https://developers.convertkit.com/v4.html#get-a-broadcast +* https://developers.convertkit.com/v4.html#get-a-broadcast + +*** ---- ### get_broadcast_stats Get the statistics (recipient count, open rate, click rate, unsubscribe count, total clicks, status, and send progress) for a specific broadcast. ```php -public get_broadcast_stats(int $id): false|object +public get_broadcast_stats(int $id): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$id` | **int** | Broadcast ID. | +| Parameter | Type | Description | +|-----------|---------|---------------| +| `$id` | **int** | Broadcast ID. | **See Also:** -* https://developers.convertkit.com/v4.html#get-stats +* https://developers.convertkit.com/v4.html#get-stats + +*** ---- ### update_broadcast Updates a broadcast. ```php -public update_broadcast(int $id, string $subject = '', string $content = '', string $description = '', bool $public = false, \DateTime $published_at = null, \DateTime $send_at = null, string $email_address = '', string $email_template_id = '', string $thumbnail_alt = '', string $thumbnail_url = '', string $preview_text = '', array $subscriber_filter = []): false|object +public update_broadcast(int $id, string $subject = '', string $content = '', string $description = '', bool $public = false, \DateTime|null $published_at = null, \DateTime|null $send_at = null, string $email_address = '', string $email_template_id = '', string $thumbnail_alt = '', string $thumbnail_url = '', string $preview_text = '', array $subscriber_filter = []): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$id` | **int** | Broadcast ID. | -| `$subject` | **string** | The broadcast email's subject. | -| `$content` | **string** | The broadcast's email HTML content. | -| `$description` | **string** | An internal description of this broadcast. | -| `$public` | **bool** | Specifies whether or not this is a public post. | -| `$published_at` | **\DateTime** | Specifies the time that this post was published (applicable
only to public posts). | -| `$send_at` | **\DateTime** | Time that this broadcast should be sent; leave blank to create
a draft broadcast. If set to a future time, this is the time that
the broadcast will be scheduled to send. | -| `$email_address` | **string** | Sending email address; leave blank to use your account's
default sending email address. | -| `$email_template_id` | **string** | ID of the email template to use; leave blank to use your
account's default email template. | -| `$thumbnail_alt` | **string** | Specify the ALT attribute of the public thumbnail image
(applicable only to public posts). | -| `$thumbnail_url` | **string** | Specify the URL of the thumbnail image to accompany the broadcast
post (applicable only to public posts). | -| `$preview_text` | **string** | Specify the preview text of the email. | -| `$subscriber_filter` | **array** | Filter subscriber(s) to send the email to. | +| Parameter | Type | Description | +|----------------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `$id` | **int** | Broadcast ID. | +| `$subject` | **string** | The broadcast email's subject. | +| `$content` | **string** | The broadcast's email HTML content. | +| `$description` | **string** | An internal description of this broadcast. | +| `$public` | **bool** | Specifies whether or not this is a public post. | +| `$published_at` | **\DateTime\|null** | Specifies the time that this post was published (applicable +only to public posts). | +| `$send_at` | **\DateTime\|null** | Time that this broadcast should be sent; leave blank to create +a draft broadcast. If set to a future time, this is the time that +the broadcast will be scheduled to send. | +| `$email_address` | **string** | Sending email address; leave blank to use your account's +default sending email address. | +| `$email_template_id` | **string** | ID of the email template to use; leave blank to use your +account's default email template. | +| `$thumbnail_alt` | **string** | Specify the ALT attribute of the public thumbnail image +(applicable only to public posts). | +| `$thumbnail_url` | **string** | Specify the URL of the thumbnail image to accompany the broadcast +post (applicable only to public posts). | +| `$preview_text` | **string** | Specify the preview text of the email. | +| `$subscriber_filter` | **array** | Filter subscriber(s) to send the email to. | **See Also:** -* https://developers.convertkit.com/#create-a-broadcast +* https://developers.convertkit.com/#create-a-broadcast + +*** ---- ### delete_broadcast Deletes an existing broadcast. ```php -public delete_broadcast(int $id): false|object +public delete_broadcast(int $id): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$id` | **int** | Broadcast ID. | +| Parameter | Type | Description | +|-----------|---------|---------------| +| `$id` | **int** | Broadcast ID. | **See Also:** -* https://developers.convertkit.com/v4.html#delete-a-broadcast +* https://developers.convertkit.com/v4.html#delete-a-broadcast + +*** ---- ### get_webhooks List webhooks. @@ -1127,63 +1186,68 @@ List webhooks. public get_webhooks(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#list-webhooks +* https://developers.convertkit.com/v4.html#list-webhooks + +*** ---- ### create_webhook Creates a webhook that will be called based on the chosen event types. ```php -public create_webhook(string $url, string $event, string $parameter = ''): false|object +public create_webhook(string $url, string $event, string $parameter = ''): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$url` | **string** | URL to receive event. | -| `$event` | **string** | Event to subscribe to. | +| Parameter | Type | Description | +|--------------|------------|--------------------------------------------| +| `$url` | **string** | URL to receive event. | +| `$event` | **string** | Event to subscribe to. | | `$parameter` | **string** | Optional parameter depending on the event. | +**Throws:** + +If the event is not supported. +- [`InvalidArgumentException`](../InvalidArgumentException) + **See Also:** -* https://developers.convertkit.com/v4.html#create-a-webhook +* https://developers.convertkit.com/v4.html#create-a-webhook + +*** ---- ### delete_webhook Deletes an existing webhook. ```php -public delete_webhook(int $id): false|object +public delete_webhook(int $id): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$id` | **int** | Webhook ID. | +| Parameter | Type | Description | +|-----------|---------|-------------| +| `$id` | **int** | Webhook ID. | **See Also:** -* https://developers.convertkit.com/v4.html#delete-a-webhook +* https://developers.convertkit.com/v4.html#delete-a-webhook + +*** ---- ### get_custom_fields List custom fields. @@ -1192,103 +1256,103 @@ List custom fields. public get_custom_fields(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#list-custom-fields +* https://developers.convertkit.com/v4.html#list-custom-fields + +*** ---- ### create_custom_field Creates a custom field. ```php -public create_custom_field(string $label): false|object +public create_custom_field(string $label): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$label` | **string** | Custom Field label. | +| Parameter | Type | Description | +|-----------|------------|---------------------| +| `$label` | **string** | Custom Field label. | **See Also:** -* https://developers.convertkit.com/v4.html#create-a-custom-field +* https://developers.convertkit.com/v4.html#create-a-custom-field + +*** ---- ### create_custom_fields Creates multiple custom fields. ```php -public create_custom_fields(string[] $labels, string $callback_url = ''): false|object +public create_custom_fields(string[] $labels, string $callback_url = ''): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$labels` | **string[]** | Custom Fields labels. | -| `$callback_url` | **string** | URL to notify for large batch size when async processing complete. | +| Parameter | Type | Description | +|-----------------|--------------|--------------------------------------------------------------------| +| `$labels` | **string[]** | Custom Fields labels. | +| `$callback_url` | **string** | URL to notify for large batch size when async processing complete. | **See Also:** -* https://developers.convertkit.com/v4.html#bulk-create-custom-fields +* https://developers.convertkit.com/v4.html#bulk-create-custom-fields + +*** ---- ### update_custom_field Updates an existing custom field. ```php -public update_custom_field(int $id, string $label): false|object +public update_custom_field(int $id, string $label): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$id` | **int** | Custom Field ID. | -| `$label` | **string** | Updated Custom Field label. | +| Parameter | Type | Description | +|-----------|------------|-----------------------------| +| `$id` | **int** | Custom Field ID. | +| `$label` | **string** | Updated Custom Field label. | **See Also:** -* https://developers.convertkit.com/v4.html#update-a-custom-field +* https://developers.convertkit.com/v4.html#update-a-custom-field + +*** ---- ### delete_custom_field Deletes an existing custom field. ```php -public delete_custom_field(int $id): false|object +public delete_custom_field(int $id): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$id` | **int** | Custom Field ID. | +| Parameter | Type | Description | +|-----------|---------|------------------| +| `$id` | **int** | Custom Field ID. | **See Also:** -* https://developers.convertkit.com/#destroy-field +* https://developers.convertkit.com/#destroy-field + +*** ---- ### get_purchases List purchases. @@ -1297,72 +1361,72 @@ List purchases. public get_purchases(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#list-purchases +* https://developers.convertkit.com/v4.html#list-purchases + +*** ---- ### get_purchase Retuns a specific purchase. ```php -public get_purchase(int $purchase_id): false|object +public get_purchase(int $purchase_id): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| +| Parameter | Type | Description | +|----------------|---------|--------------| | `$purchase_id` | **int** | Purchase ID. | **See Also:** -* https://developers.convertkit.com/v4.html#get-a-purchase +* https://developers.convertkit.com/v4.html#get-a-purchase + +*** ---- ### create_purchase Creates a purchase. ```php -public create_purchase(string $email_address, string $transaction_id, array $products, string $currency = 'USD', string $first_name = null, string $status = null, float $subtotal, float $tax, float $shipping, float $discount, float $total, \DateTime $transaction_time = null): false|object +public create_purchase(string $email_address, string $transaction_id, array $products, string $currency = 'USD', string|null $first_name = null, string|null $status = null, float $subtotal, float $tax, float $shipping, float $discount, float $total, \DateTime|null $transaction_time = null): mixed|object ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$email_address` | **string** | Email Address. | -| `$transaction_id` | **string** | Transaction ID. | -| `$products` | **array** | Products. | -| `$currency` | **string** | ISO Currency Code. | -| `$first_name` | **string** | First Name. | -| `$status` | **string** | Order Status. | -| `$subtotal` | **float** | Subtotal. | -| `$tax` | **float** | Tax. | -| `$shipping` | **float** | Shipping. | -| `$discount` | **float** | Discount. | -| `$total` | **float** | Total. | -| `$transaction_time` | **\DateTime** | Transaction date and time. | +| Parameter | Type | Description | +|---------------------|--------------------------------------|----------------------------| +| `$email_address` | **string** | Email Address. | +| `$transaction_id` | **string** | Transaction ID. | +| `$products` | **array** | Products. | +| `$currency` | **string** | ISO Currency Code. | +| `$first_name` | **string\|null** | First Name. | +| `$status` | **string\|null** | Order Status. | +| `$subtotal` | **float** | Subtotal. | +| `$tax` | **float** | Tax. | +| `$shipping` | **float** | Shipping. | +| `$discount` | **float** | Discount. | +| `$total` | **float** | Total. | +| `$transaction_time` | **\DateTime\|null** | Transaction date and time. | **See Also:** -* https://developers.convertkit.com/v4.html#create-a-purchase +* https://developers.convertkit.com/v4.html#create-a-purchase + +*** ---- ### get_segments List segments. @@ -1371,21 +1435,21 @@ List segments. public get_segments(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | **See Also:** -* https://developers.convertkit.com/v4.html#convertkit-api-segments +* https://developers.convertkit.com/v4.html#convertkit-api-segments + +*** ---- ### convert_relative_to_absolute_urls Converts any relative URls to absolute, fully qualified HTTP(s) URLs for the given @@ -1395,17 +1459,16 @@ DOM Elements. public convert_relative_to_absolute_urls(\DOMNodeList<\DOMElement> $elements, string $attribute, string $url): void ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$elements` | **\DOMNodeList<\DOMElement>** | Elements. | -| `$attribute` | **string** | HTML Attribute. | -| `$url` | **string** | Absolute URL to prepend to relative URLs. | +| Parameter | Type | Description | +|--------------|-------------------------------|-------------------------------------------| +| `$elements` | **\DOMNodeList<\DOMElement>** | Elements. | +| `$attribute` | **string** | HTML Attribute. | +| `$url` | **string** | Absolute URL to prepend to relative URLs. | +*** ---- ### strip_html_head_body_tags Strips , and opening and closing tags from the given markup, @@ -1415,19 +1478,18 @@ as well as the Content-Type meta tag we might have added in get_html(). public strip_html_head_body_tags(string $markup): string ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| +| Parameter | Type | Description | +|-----------|------------|--------------| | `$markup` | **string** | HTML Markup. | **Return Value:** HTML Markup +*** ---- ### build_total_count_and_pagination_params Adds total count and pagination parameters to the given array of existing API parameters. @@ -1436,19 +1498,18 @@ Adds total count and pagination parameters to the given array of existing API pa private build_total_count_and_pagination_params(array $params = [], bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): array ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$params` | **array** | API parameters. | -| `$include_total_count` | **bool** | Return total count of records. | -| `$after_cursor` | **string** | Return results after the given pagination cursor. | -| `$before_cursor` | **string** | Return results before the given pagination cursor. | -| `$per_page` | **int** | Number of results to return. | +| Parameter | Type | Description | +|------------------------|-------------------------------------|----------------------------------------------------| +| `$params` | **array** | API parameters. | +| `$include_total_count` | **bool** | Return total count of records. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | +*** ---- ### get Performs a GET request to the API. @@ -1457,16 +1518,15 @@ Performs a GET request to the API. public get(string $endpoint, array> $args = []): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$endpoint` | **string** | API Endpoint. | -| `$args` | **array>** | Request arguments. | +| Parameter | Type | Description | +|-------------|----------------------------------------------------------------|--------------------| +| `$endpoint` | **string** | API Endpoint. | +| `$args` | **array>** | Request arguments. | +*** ---- ### post Performs a POST request to the API. @@ -1475,16 +1535,15 @@ Performs a POST request to the API. public post(string $endpoint, array> $args = []): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$endpoint` | **string** | API Endpoint. | -| `$args` | **array>** | Request arguments. | +| Parameter | Type | Description | +|-------------|-----------------------------------------------------------------------------------------------------|--------------------| +| `$endpoint` | **string** | API Endpoint. | +| `$args` | **array>** | Request arguments. | +*** ---- ### put Performs a PUT request to the API. @@ -1493,16 +1552,15 @@ Performs a PUT request to the API. public put(string $endpoint, array> $args = []): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$endpoint` | **string** | API Endpoint. | -| `$args` | **array>** | Request arguments. | +| Parameter | Type | Description | +|-------------|----------------------------------------------------------------|--------------------| +| `$endpoint` | **string** | API Endpoint. | +| `$args` | **array>** | Request arguments. | +*** ---- ### delete Performs a DELETE request to the API. @@ -1511,16 +1569,15 @@ Performs a DELETE request to the API. public delete(string $endpoint, array> $args = []): false|mixed ``` - **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$endpoint` | **string** | API Endpoint. | -| `$args` | **array>** | Request arguments. | +| Parameter | Type | Description | +|-------------|----------------------------------------------------------|--------------------| +| `$endpoint` | **string** | API Endpoint. | +| `$args` | **array>** | Request arguments. | +*** ---- ### request Performs an API request. @@ -1528,18 +1585,23 @@ Performs an API request. ```php public request(string $endpoint, string $method, array> $args = []): false|mixed ``` -* This method is **abstract**. +* This method is **abstract**. **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$endpoint` | **string** | API Endpoint. | -| `$method` | **string** | Request method. | -| `$args` | **array>** | Request arguments. | +| Parameter | Type | Description | +|-------------|-----------------------------------------------------------------------------------------------------|--------------------| +| `$endpoint` | **string** | API Endpoint. | +| `$method` | **string** | Request method. | +| `$args` | **array>** | Request arguments. | + +**Throws:** +If JSON encoding arguments failed. +- [`Exception`](../Exception) + +*** ---- ### get_request_headers Returns the headers to use in an API request. @@ -1547,17 +1609,17 @@ Returns the headers to use in an API request. ```php public get_request_headers(string $type = 'application/json', bool $auth = true): array ``` -* This method is **abstract**. +* This method is **abstract**. **Parameters:** -| Parameter | Type | Description | -|-----------|------|-------------| -| `$type` | **string** | Accept and Content-Type Headers. | -| `$auth` | **bool** | Include authorization header. | +| Parameter | Type | Description | +|-----------|------------|----------------------------------| +| `$type` | **string** | Accept and Content-Type Headers. | +| `$auth` | **bool** | Include authorization header. | +*** ---- ### get_timeout Returns the maximum amount of time to wait for @@ -1566,14 +1628,14 @@ a response to the request before exiting. ```php public get_timeout(): int ``` -* This method is **abstract**. +* This method is **abstract**. **Return Value:** Timeout, in seconds. +*** ---- ### get_user_agent Returns the user agent string to use in all HTTP requests. @@ -1581,9 +1643,6 @@ Returns the user agent string to use in all HTTP requests. ```php public get_user_agent(): string ``` -* This method is **abstract**. - - ---- - +* This method is **abstract**. +*** diff --git a/docs/classes/ConvertKit_API/ConvertKit_API_Traits.md b/docs/classes/ConvertKit_API/ConvertKit_API_Traits.md new file mode 100644 index 0000000..9d25991 --- /dev/null +++ b/docs/classes/ConvertKit_API/ConvertKit_API_Traits.md @@ -0,0 +1,1397 @@ + +ConvertKit API Traits + +*** + +* Full name: `\ConvertKit_API\ConvertKit_API_Traits` + +## Properties + +### client_id + +ConvertKit OAuth Application Client ID + +```php +protected string $client_id +``` + +*** +### client_secret + +ConvertKit OAuth Application Client Secret + +```php +protected string $client_secret +``` + +*** +### access_token + +Access Token + +```php +protected string $access_token +``` + +*** +### api_key + +API Key + +```php +protected string $api_key +``` + +*** +### oauth_authorize_url + +OAuth Authorization URL + +```php +protected string $oauth_authorize_url +``` + +*** +### oauth_token_url + +OAuth Token URL + +```php +protected string $oauth_token_url +``` + +*** +### api_version + +Version of ConvertKit API + +```php +protected string $api_version +``` + +*** +### api_url_base + +ConvertKit API URL + +```php +protected string $api_url_base +``` + +*** + +## Methods + +### get_account + +Gets the current account + +```php +public get_account(): false|mixed +``` + +**See Also:** + +* https://developers.convertkit.com/v4.html#get-current-account + +*** +### get_account_colors + +Gets the account's colors + +```php +public get_account_colors(): false|mixed +``` + +**See Also:** + +* https://developers.convertkit.com/v4.html#list-colors + +*** +### update_account_colors + +Gets the account's colors + +```php +public update_account_colors(array $colors): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|--------------------------|-------------| +| `$colors` | **array** | Hex colors. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#list-colors + +*** +### get_creator_profile + +Gets the Creator Profile + +```php +public get_creator_profile(): false|mixed +``` + +**See Also:** + +* https://developers.convertkit.com/v4.html#get-creator-profile + +*** +### get_email_stats + +Gets email stats + +```php +public get_email_stats(): false|mixed +``` + +**See Also:** + +* https://developers.convertkit.com/v4.html#get-email-stats + +*** +### get_growth_stats + +Gets growth stats + +```php +public get_growth_stats(\DateTime|null $starting = null, \DateTime|null $ending = null): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|-------------|---------------------|-----------------------------------------------------------------------------| +| `$starting` | **\DateTime\|null** | Gets stats for time period beginning on this date. Defaults to 90 days ago. | +| `$ending` | **\DateTime\|null** | Gets stats for time period ending on this date. Defaults to today. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#get-growth-stats + +*** +### get_forms + +Get forms. + +```php +public get_forms(string $status = 'active', bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): mixed|array +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$status` | **string** | Form status (active\|archived\|trashed\|all). | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#convertkit-api-forms + +*** +### get_landing_pages + +Get landing pages. + +```php +public get_landing_pages(string $status = 'active', bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): mixed|array +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$status` | **string** | Form status (active\|archived\|trashed\|all). | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#convertkit-api-forms + +*** +### add_subscribers_to_forms + +Adds subscribers to forms in bulk. + +```php +public add_subscribers_to_forms(array[] $forms_subscribers_ids, string $callback_url = ''): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|--------------------------|----------------------------|---------------------------------------------------------------------------------------| +| `$forms_subscribers_ids` | **array[]** | Array of arrays comprising of `form_id`, `subscriber_id` and optional `referrer` URL. | +| `$callback_url` | **string** | URL to notify for large batch size when async processing complete. | + +**See Also:** + +* https://developers.kit.com/v4.html#bulk-add-subscribers-to-forms + +*** +### add_subscriber_to_form_by_email + +Adds a subscriber to a form by email address + +```php +public add_subscriber_to_form_by_email(int $form_id, string $email_address, string $referrer = ''): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------|------------|----------------| +| `$form_id` | **int** | Form ID. | +| `$email_address` | **string** | Email Address. | +| `$referrer` | **string** | Referrer. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#add-subscriber-to-form-by-email-address + +*** +### add_subscriber_to_form + +Adds a subscriber to a form by subscriber ID + +```php +public add_subscriber_to_form(int $form_id, int $subscriber_id, string $referrer = ''): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------|------------|----------------| +| `$form_id` | **int** | Form ID. | +| `$subscriber_id` | **int** | Subscriber ID. | +| `$referrer` | **string** | Referrer URL. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#add-subscriber-to-form + +*** +### get_form_subscriptions + +List subscribers for a form + +```php +public get_form_subscriptions(int $form_id, string $subscriber_state = 'active', \DateTime|null $created_after = null, \DateTime|null $created_before = null, \DateTime|null $added_after = null, \DateTime|null $added_before = null, bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|---------------------|----------------------------------------------------------------------| +| `$form_id` | **int** | Form ID. | +| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | +| `$created_after` | **\DateTime\|null** | Filter subscribers who have been created after this date. | +| `$created_before` | **\DateTime\|null** | Filter subscribers who have been created before this date. | +| `$added_after` | **\DateTime\|null** | Filter subscribers who have been added to the form after this date. | +| `$added_before` | **\DateTime\|null** | Filter subscribers who have been added to the form before this date. | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#list-subscribers-for-a-form + +*** +### get_sequences + +Gets sequences + +```php +public get_sequences(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#list-sequences + +*** +### add_subscriber_to_sequence_by_email + +Adds a subscriber to a sequence by email address + +```php +public add_subscriber_to_sequence_by_email(int $sequence_id, string $email_address): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------|------------|----------------| +| `$sequence_id` | **int** | Sequence ID. | +| `$email_address` | **string** | Email Address. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#add-subscriber-to-sequence-by-email-address + +*** +### add_subscriber_to_sequence + +Adds a subscriber to a sequence by subscriber ID + +```php +public add_subscriber_to_sequence(int $sequence_id, int $subscriber_id): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------|---------|----------------| +| `$sequence_id` | **int** | Sequence ID. | +| `$subscriber_id` | **int** | Subscriber ID. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#add-subscriber-to-sequence + +*** +### get_sequence_subscriptions + +List subscribers for a sequence + +```php +public get_sequence_subscriptions(int $sequence_id, string $subscriber_state = 'active', \DateTime|null $created_after = null, \DateTime|null $created_before = null, \DateTime|null $added_after = null, \DateTime|null $added_before = null, bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|---------------------|----------------------------------------------------------------------| +| `$sequence_id` | **int** | Sequence ID. | +| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | +| `$created_after` | **\DateTime\|null** | Filter subscribers who have been created after this date. | +| `$created_before` | **\DateTime\|null** | Filter subscribers who have been created before this date. | +| `$added_after` | **\DateTime\|null** | Filter subscribers who have been added to the form after this date. | +| `$added_before` | **\DateTime\|null** | Filter subscribers who have been added to the form before this date. | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#list-subscribers-for-a-sequence + +*** +### get_tags + +List tags. + +```php +public get_tags(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): mixed|array +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#list-tags + +*** +### create_tag + +Creates a tag. + +```php +public create_tag(string $tag): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------------|-------------| +| `$tag` | **string** | Tag Name. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#create-a-tag + +*** +### create_tags + +Creates multiple tags. + +```php +public create_tags(array $tags, string $callback_url = ''): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------------|-----------------------|--------------------------------------------------------------------| +| `$tags` | **array** | Tag Names. | +| `$callback_url` | **string** | URL to notify for large batch size when async processing complete. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#bulk-create-tags + +*** +### tag_subscriber_by_email + +Tags a subscriber with the given existing Tag. + +```php +public tag_subscriber_by_email(int $tag_id, string $email_address): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------|------------|----------------| +| `$tag_id` | **int** | Tag ID. | +| `$email_address` | **string** | Email Address. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#tag-a-subscriber-by-email-address + +*** +### tag_subscriber + +Tags a subscriber by subscriber ID with the given existing Tag. + +```php +public tag_subscriber(int $tag_id, int $subscriber_id): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------|---------|----------------| +| `$tag_id` | **int** | Tag ID. | +| `$subscriber_id` | **int** | Subscriber ID. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#tag-a-subscriber + +*** +### remove_tag_from_subscriber + +Removes a tag from a subscriber. + +```php +public remove_tag_from_subscriber(int $tag_id, int $subscriber_id): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------|---------|----------------| +| `$tag_id` | **int** | Tag ID. | +| `$subscriber_id` | **int** | Subscriber ID. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#remove-tag-from-subscriber + +*** +### remove_tag_from_subscriber_by_email + +Removes a tag from a subscriber by email address. + +```php +public remove_tag_from_subscriber_by_email(int $tag_id, string $email_address): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------|------------|---------------------------| +| `$tag_id` | **int** | Tag ID. | +| `$email_address` | **string** | Subscriber email address. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#remove-tag-from-subscriber-by-email-address + +*** +### get_tag_subscriptions + +List subscribers for a tag + +```php +public get_tag_subscriptions(int $tag_id, string $subscriber_state = 'active', \DateTime|null $created_after = null, \DateTime|null $created_before = null, \DateTime|null $tagged_after = null, \DateTime|null $tagged_before = null, bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|---------------------|----------------------------------------------------------------------| +| `$tag_id` | **int** | Tag ID. | +| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | +| `$created_after` | **\DateTime\|null** | Filter subscribers who have been created after this date. | +| `$created_before` | **\DateTime\|null** | Filter subscribers who have been created before this date. | +| `$tagged_after` | **\DateTime\|null** | Filter subscribers who have been tagged after this date. | +| `$tagged_before` | **\DateTime\|null** | Filter subscribers who have been tagged before this date. | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#list-subscribers-for-a-tag + +*** +### get_email_templates + +List email templates. + +```php +public get_email_templates(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#convertkit-api-email-templates + +*** +### get_subscribers + +List subscribers. + +```php +public get_subscribers(string $subscriber_state = 'active', string $email_address = '', \DateTime|null $created_after = null, \DateTime|null $created_before = null, \DateTime|null $updated_after = null, \DateTime|null $updated_before = null, string $sort_field = 'id', string $sort_order = 'desc', bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|---------------------|----------------------------------------------------------------------| +| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | +| `$email_address` | **string** | Search susbcribers by email address. This is an exact match search. | +| `$created_after` | **\DateTime\|null** | Filter subscribers who have been created after this date. | +| `$created_before` | **\DateTime\|null** | Filter subscribers who have been created before this date. | +| `$updated_after` | **\DateTime\|null** | Filter subscribers who have been updated after this date. | +| `$updated_before` | **\DateTime\|null** | Filter subscribers who have been updated before this date. | +| `$sort_field` | **string** | Sort Field (id\|updated_at\|cancelled_at). | +| `$sort_order` | **string** | Sort Order (asc\|desc). | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#list-subscribers + +*** +### create_subscriber + +Create a subscriber. + +```php +public create_subscriber(string $email_address, string $first_name = '', string $subscriber_state = '', array $fields = []): mixed +``` + +Behaves as an upsert. If a subscriber with the provided email address does not exist, +it creates one with the specified first name and state. If a subscriber with the provided +email address already exists, it updates the first name. + +**Parameters:** + +| Parameter | Type | Description | +|---------------------|--------------------------|----------------------------------------------------------------------| +| `$email_address` | **string** | Email Address. | +| `$first_name` | **string** | First Name. | +| `$subscriber_state` | **string** | Subscriber State (active\|bounced\|cancelled\|complained\|inactive). | +| `$fields` | **array** | Custom Fields. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#create-a-subscriber + +*** +### create_subscribers + +Create multiple subscribers. + +```php +public create_subscribers(array> $subscribers, string $callback_url = ''): mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------------|-------------------------------------|--------------------------------------------------------------------| +| `$subscribers` | **array>** | Subscribers. | +| `$callback_url` | **string** | URL to notify for large batch size when async processing complete. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#bulk-create-subscribers + +*** +### get_subscriber_id + +Get the ConvertKit subscriber ID associated with email address if it exists. + +```php +public get_subscriber_id(string $email_address): false|int +``` + +Return false if subscriber not found. + +**Parameters:** + +| Parameter | Type | Description | +|------------------|------------|----------------| +| `$email_address` | **string** | Email Address. | + +**Throws:** + +If the email address is not a valid email format. +- [`InvalidArgumentException`](../InvalidArgumentException) + +**See Also:** + +* https://developers.convertkit.com/v4.html#get-a-subscriber + +*** +### get_subscriber + +Get subscriber by id + +```php +public get_subscriber(int $subscriber_id): mixed|int +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------|---------|----------------| +| `$subscriber_id` | **int** | Subscriber ID. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#get-a-subscriber + +*** +### update_subscriber + +Updates the information for a single subscriber. + +```php +public update_subscriber(int $subscriber_id, string $first_name = '', string $email_address = '', array $fields = []): mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------|--------------------------|-------------------------| +| `$subscriber_id` | **int** | Existing Subscriber ID. | +| `$first_name` | **string** | New First Name. | +| `$email_address` | **string** | New Email Address. | +| `$fields` | **array** | Updated Custom Fields. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#update-a-subscriber + +*** +### unsubscribe_by_email + +Unsubscribe an email address. + +```php +public unsubscribe_by_email(string $email_address): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------|------------|----------------| +| `$email_address` | **string** | Email Address. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#unsubscribe-subscriber + +*** +### unsubscribe + +Unsubscribe the given subscriber ID. + +```php +public unsubscribe(int $subscriber_id): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------|---------|----------------| +| `$subscriber_id` | **int** | Subscriber ID. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#unsubscribe-subscriber + +*** +### get_subscriber_tags + +Get a list of the tags for a subscriber. + +```php +public get_subscriber_tags(int $subscriber_id, bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): mixed|array +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$subscriber_id` | **int** | Subscriber ID. | +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#list-tags-for-a-subscriber + +*** +### get_broadcasts + +List broadcasts. + +```php +public get_broadcasts(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#list-broadcasts + +*** +### create_broadcast + +Creates a broadcast. + +```php +public create_broadcast(string $subject = '', string $content = '', string $description = '', bool $public = false, \DateTime|null $published_at = null, \DateTime|null $send_at = null, string $email_address = '', string $email_template_id = '', string $thumbnail_alt = '', string $thumbnail_url = '', string $preview_text = '', array $subscriber_filter = []): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|----------------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `$subject` | **string** | The broadcast email's subject. | +| `$content` | **string** | The broadcast's email HTML content. | +| `$description` | **string** | An internal description of this broadcast. | +| `$public` | **bool** | Specifies whether or not this is a public post. | +| `$published_at` | **\DateTime\|null** | Specifies the time that this post was published (applicable +only to public posts). | +| `$send_at` | **\DateTime\|null** | Time that this broadcast should be sent; leave blank to create +a draft broadcast. If set to a future time, this is the time that +the broadcast will be scheduled to send. | +| `$email_address` | **string** | Sending email address; leave blank to use your account's +default sending email address. | +| `$email_template_id` | **string** | ID of the email template to use; leave blank to use your +account's default email template. | +| `$thumbnail_alt` | **string** | Specify the ALT attribute of the public thumbnail image +(applicable only to public posts). | +| `$thumbnail_url` | **string** | Specify the URL of the thumbnail image to accompany the broadcast +post (applicable only to public posts). | +| `$preview_text` | **string** | Specify the preview text of the email. | +| `$subscriber_filter` | **array** | Filter subscriber(s) to send the email to. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#create-a-broadcast + +*** +### get_broadcast + +Retrieve a specific broadcast. + +```php +public get_broadcast(int $id): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|---------|---------------| +| `$id` | **int** | Broadcast ID. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#get-a-broadcast + +*** +### get_broadcast_stats + +Get the statistics (recipient count, open rate, click rate, unsubscribe count, +total clicks, status, and send progress) for a specific broadcast. + +```php +public get_broadcast_stats(int $id): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|---------|---------------| +| `$id` | **int** | Broadcast ID. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#get-stats + +*** +### update_broadcast + +Updates a broadcast. + +```php +public update_broadcast(int $id, string $subject = '', string $content = '', string $description = '', bool $public = false, \DateTime|null $published_at = null, \DateTime|null $send_at = null, string $email_address = '', string $email_template_id = '', string $thumbnail_alt = '', string $thumbnail_url = '', string $preview_text = '', array $subscriber_filter = []): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|----------------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `$id` | **int** | Broadcast ID. | +| `$subject` | **string** | The broadcast email's subject. | +| `$content` | **string** | The broadcast's email HTML content. | +| `$description` | **string** | An internal description of this broadcast. | +| `$public` | **bool** | Specifies whether or not this is a public post. | +| `$published_at` | **\DateTime\|null** | Specifies the time that this post was published (applicable +only to public posts). | +| `$send_at` | **\DateTime\|null** | Time that this broadcast should be sent; leave blank to create +a draft broadcast. If set to a future time, this is the time that +the broadcast will be scheduled to send. | +| `$email_address` | **string** | Sending email address; leave blank to use your account's +default sending email address. | +| `$email_template_id` | **string** | ID of the email template to use; leave blank to use your +account's default email template. | +| `$thumbnail_alt` | **string** | Specify the ALT attribute of the public thumbnail image +(applicable only to public posts). | +| `$thumbnail_url` | **string** | Specify the URL of the thumbnail image to accompany the broadcast +post (applicable only to public posts). | +| `$preview_text` | **string** | Specify the preview text of the email. | +| `$subscriber_filter` | **array** | Filter subscriber(s) to send the email to. | + +**See Also:** + +* https://developers.convertkit.com/#create-a-broadcast + +*** +### delete_broadcast + +Deletes an existing broadcast. + +```php +public delete_broadcast(int $id): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|---------|---------------| +| `$id` | **int** | Broadcast ID. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#delete-a-broadcast + +*** +### get_webhooks + +List webhooks. + +```php +public get_webhooks(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#list-webhooks + +*** +### create_webhook + +Creates a webhook that will be called based on the chosen event types. + +```php +public create_webhook(string $url, string $event, string $parameter = ''): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|--------------|------------|--------------------------------------------| +| `$url` | **string** | URL to receive event. | +| `$event` | **string** | Event to subscribe to. | +| `$parameter` | **string** | Optional parameter depending on the event. | + +**Throws:** + +If the event is not supported. +- [`InvalidArgumentException`](../InvalidArgumentException) + +**See Also:** + +* https://developers.convertkit.com/v4.html#create-a-webhook + +*** +### delete_webhook + +Deletes an existing webhook. + +```php +public delete_webhook(int $id): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|---------|-------------| +| `$id` | **int** | Webhook ID. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#delete-a-webhook + +*** +### get_custom_fields + +List custom fields. + +```php +public get_custom_fields(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#list-custom-fields + +*** +### create_custom_field + +Creates a custom field. + +```php +public create_custom_field(string $label): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------------|---------------------| +| `$label` | **string** | Custom Field label. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#create-a-custom-field + +*** +### create_custom_fields + +Creates multiple custom fields. + +```php +public create_custom_fields(string[] $labels, string $callback_url = ''): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------------|--------------|--------------------------------------------------------------------| +| `$labels` | **string[]** | Custom Fields labels. | +| `$callback_url` | **string** | URL to notify for large batch size when async processing complete. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#bulk-create-custom-fields + +*** +### update_custom_field + +Updates an existing custom field. + +```php +public update_custom_field(int $id, string $label): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------------|-----------------------------| +| `$id` | **int** | Custom Field ID. | +| `$label` | **string** | Updated Custom Field label. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#update-a-custom-field + +*** +### delete_custom_field + +Deletes an existing custom field. + +```php +public delete_custom_field(int $id): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|---------|------------------| +| `$id` | **int** | Custom Field ID. | + +**See Also:** + +* https://developers.convertkit.com/#destroy-field + +*** +### get_purchases + +List purchases. + +```php +public get_purchases(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#list-purchases + +*** +### get_purchase + +Retuns a specific purchase. + +```php +public get_purchase(int $purchase_id): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|----------------|---------|--------------| +| `$purchase_id` | **int** | Purchase ID. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#get-a-purchase + +*** +### create_purchase + +Creates a purchase. + +```php +public create_purchase(string $email_address, string $transaction_id, array $products, string $currency = 'USD', string|null $first_name = null, string|null $status = null, float $subtotal, float $tax, float $shipping, float $discount, float $total, \DateTime|null $transaction_time = null): mixed|object +``` + +**Parameters:** + +| Parameter | Type | Description | +|---------------------|--------------------------------------|----------------------------| +| `$email_address` | **string** | Email Address. | +| `$transaction_id` | **string** | Transaction ID. | +| `$products` | **array** | Products. | +| `$currency` | **string** | ISO Currency Code. | +| `$first_name` | **string\|null** | First Name. | +| `$status` | **string\|null** | Order Status. | +| `$subtotal` | **float** | Subtotal. | +| `$tax` | **float** | Tax. | +| `$shipping` | **float** | Shipping. | +| `$discount` | **float** | Discount. | +| `$total` | **float** | Total. | +| `$transaction_time` | **\DateTime\|null** | Transaction date and time. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#create-a-purchase + +*** +### get_segments + +List segments. + +```php +public get_segments(bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|------------|------------------------------------------------------------------| +| `$include_total_count` | **bool** | To include the total count of records in the response, use true. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +**See Also:** + +* https://developers.convertkit.com/v4.html#convertkit-api-segments + +*** +### convert_relative_to_absolute_urls + +Converts any relative URls to absolute, fully qualified HTTP(s) URLs for the given +DOM Elements. + +```php +public convert_relative_to_absolute_urls(\DOMNodeList<\DOMElement> $elements, string $attribute, string $url): void +``` + +**Parameters:** + +| Parameter | Type | Description | +|--------------|-------------------------------|-------------------------------------------| +| `$elements` | **\DOMNodeList<\DOMElement>** | Elements. | +| `$attribute` | **string** | HTML Attribute. | +| `$url` | **string** | Absolute URL to prepend to relative URLs. | + +*** +### strip_html_head_body_tags + +Strips , and opening and closing tags from the given markup, +as well as the Content-Type meta tag we might have added in get_html(). + +```php +public strip_html_head_body_tags(string $markup): string +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|------------|--------------| +| `$markup` | **string** | HTML Markup. | + +**Return Value:** + +HTML Markup + +*** +### build_total_count_and_pagination_params + +Adds total count and pagination parameters to the given array of existing API parameters. + +```php +private build_total_count_and_pagination_params(array $params = [], bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100): array +``` + +**Parameters:** + +| Parameter | Type | Description | +|------------------------|-------------------------------------|----------------------------------------------------| +| `$params` | **array** | API parameters. | +| `$include_total_count` | **bool** | Return total count of records. | +| `$after_cursor` | **string** | Return results after the given pagination cursor. | +| `$before_cursor` | **string** | Return results before the given pagination cursor. | +| `$per_page` | **int** | Number of results to return. | + +*** +### get + +Performs a GET request to the API. + +```php +public get(string $endpoint, array> $args = []): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|-------------|----------------------------------------------------------------|--------------------| +| `$endpoint` | **string** | API Endpoint. | +| `$args` | **array>** | Request arguments. | + +*** +### post + +Performs a POST request to the API. + +```php +public post(string $endpoint, array> $args = []): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|-------------|-----------------------------------------------------------------------------------------------------|--------------------| +| `$endpoint` | **string** | API Endpoint. | +| `$args` | **array>** | Request arguments. | + +*** +### put + +Performs a PUT request to the API. + +```php +public put(string $endpoint, array> $args = []): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|-------------|----------------------------------------------------------------|--------------------| +| `$endpoint` | **string** | API Endpoint. | +| `$args` | **array>** | Request arguments. | + +*** +### delete + +Performs a DELETE request to the API. + +```php +public delete(string $endpoint, array> $args = []): false|mixed +``` + +**Parameters:** + +| Parameter | Type | Description | +|-------------|----------------------------------------------------------|--------------------| +| `$endpoint` | **string** | API Endpoint. | +| `$args` | **array>** | Request arguments. | + +*** +### request + +Performs an API request. + +```php +public request(string $endpoint, string $method, array> $args = []): false|mixed +``` + +* This method is **abstract**. +**Parameters:** + +| Parameter | Type | Description | +|-------------|-----------------------------------------------------------------------------------------------------|--------------------| +| `$endpoint` | **string** | API Endpoint. | +| `$method` | **string** | Request method. | +| `$args` | **array>** | Request arguments. | + +**Throws:** + +If JSON encoding arguments failed. +- [`Exception`](../Exception) + +*** +### get_request_headers + +Returns the headers to use in an API request. + +```php +public get_request_headers(string $type = 'application/json', bool $auth = true): array +``` + +* This method is **abstract**. +**Parameters:** + +| Parameter | Type | Description | +|-----------|------------|----------------------------------| +| `$type` | **string** | Accept and Content-Type Headers. | +| `$auth` | **bool** | Include authorization header. | + +*** +### get_timeout + +Returns the maximum amount of time to wait for +a response to the request before exiting. + +```php +public get_timeout(): int +``` + +* This method is **abstract**. +**Return Value:** + +Timeout, in seconds. + +*** +### get_user_agent + +Returns the user agent string to use in all HTTP requests. + +```php +public get_user_agent(): string +``` + +* This method is **abstract**. +*** From 7bc6eaa7b1149e59bea111b0c58888cd1e8ad831 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 13:52:36 +0800 Subject: [PATCH 05/17] Fix Failing Tests --- tests/ConvertKitAPITest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index 786d85e..e05a025 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -1408,7 +1408,7 @@ public function testGetSequenceSubscriptionsPagination() // Assert has_previous_page and has_next_page are correct. $this->assertTrue($result->pagination->has_previous_page); - $this->assertFalse($result->pagination->has_next_page); + $this->assertTrue($result->pagination->has_next_page); // Use pagination to fetch previous page. $result = $this->api->get_sequence_subscriptions( From bf2b64e43a9a059e8f727f968a14b82e69ee4970 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 14:02:35 +0800 Subject: [PATCH 06/17] Change ServerException to ClientException for refresh token with invalid token --- tests/ConvertKitAPIOAuthTest.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/ConvertKitAPIOAuthTest.php b/tests/ConvertKitAPIOAuthTest.php index 829d0a7..c1b089e 100644 --- a/tests/ConvertKitAPIOAuthTest.php +++ b/tests/ConvertKitAPIOAuthTest.php @@ -401,7 +401,7 @@ public function testRefreshToken() } /** - * Test that a ServerException is thrown when an invalid refresh token is supplied + * Test that a ClientException is thrown when an invalid refresh token is supplied * when refreshing an access token. * * @since 2.0.0 @@ -410,7 +410,7 @@ public function testRefreshToken() */ public function testRefreshTokenWithInvalidToken() { - $this->expectException(ServerException::class); + $this->expectException(ClientException::class); $api = new ConvertKit_API( clientID: $_ENV['CONVERTKIT_OAUTH_CLIENT_ID'], clientSecret: $_ENV['CONVERTKIT_OAUTH_CLIENT_SECRET'] From c1ed992aa9fdc9044e7449808e5eb887a6caad7e Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 15:20:31 +0800 Subject: [PATCH 07/17] Add Composer Commands --- composer.json | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/composer.json b/composer.json index 30a377e..6082043 100644 --- a/composer.json +++ b/composer.json @@ -38,6 +38,17 @@ "minimum-stability": "dev", "prefer-stable": true, "scripts": { - "create-docs": "phpDocumentor --directory=src --target=docs --template='vendor/saggre/phpdocumentor-markdown/themes/markdown'" + "create-docs": "phpDocumentor --directory=src --target=docs --template='vendor/saggre/phpdocumentor-markdown/themes/markdown'", + "phpcs": "vendor/bin/phpcs ./ -s -v", + "phpcbf": "vendor/bin/phpcbf ./ -s -v", + "phpcs-tests": "vendor/bin/phpcs ./tests --standard=phpcs.tests.xml -s -v", + "phpcbf-tests": "vendor/bin/phpcbf ./tests --standard=phpcs.tests.xml -s -v", + "phpstan": "vendor/bin/phpstan analyse --memory-limit=1250M", + "php-coding-standards": "vendor/bin/phpcs ./ -s -v", + "fix-php-coding-standards": "vendor/bin/phpcbf ./ -s -v", + "php-coding-standards-on-tests": "vendor/bin/phpcs ./tests --standard=phpcs.tests.xml -s -v", + "fix-php-coding-standards-on-tests": "vendor/bin/phpcbf ./tests --standard=phpcs.tests.xml -s -v", + "php-static-analysis": "vendor/bin/phpstan analyse --memory-limit=1250M", + "test": "vendor/bin/phpunit --verbose --stop-on-failure @additional_args" } } From 522723bfa38c859b12fda09c986318710fe7f6fc Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 18:01:06 +0800 Subject: [PATCH 08/17] Add `get_subscriber_stats` method --- src/ConvertKit_API_Traits.php | 14 ++++++++++++ tests/ConvertKitAPITest.php | 43 +++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+) diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index 71f2175..1af3745 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -1027,6 +1027,20 @@ public function unsubscribe(int $subscriber_id) return $this->post(sprintf('subscribers/%s/unsubscribe', $subscriber_id)); } + /** + * Get the email statistics for a specific subscriber. + * + * @param integer $id Subscriber ID. + * + * @see https://developers.kit.com/api-reference/subscribers/list-stats-for-a-subscriber + * + * @return mixed|object + */ + public function get_subscriber_stats(int $id) + { + return $this->get(sprintf('subscribers/%s/stats', $id)); + } + /** * Get a list of the tags for a subscriber. * diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index e05a025..7ae5276 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -1722,6 +1722,49 @@ public function testCreateTagsThatExist() $this->assertEquals($result->tags[0]->name, $_ENV['CONVERTKIT_API_TAG_NAME_2']); } + /** + * Test that get_subscriber_stats() returns the expected data + * when using a valid subscriber ID. + * + * @since 2.2.1 + * + * @return void + */ + public function testGetSubscriberStats() + { + $result = $this->api->get_subscriber_stats( + id: (int) $_ENV['CONVERTKIT_API_SUBSCRIBER_ID'] + ); + $this->assertArrayHasKey('subscriber', get_object_vars($result)); + $this->assertArrayHasKey('id', get_object_vars($result->subscriber)); + $this->assertArrayHasKey('stats', get_object_vars($result->subscriber)); + $this->assertArrayHasKey('sent', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('opened', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('clicked', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('bounced', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('open_rate', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('click_rate', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('last_sent', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('last_opened', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('last_clicked', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('sends_since_last_open', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('sends_since_last_click', get_object_vars($result->subscriber->stats)); + } + + /** + * Test that get_subscriber_stats() throws a ClientException when an invalid + * subscriber ID is specified. + * + * @since 2.2.1 + * + * @return void + */ + public function testGetSubscriberStatsWithInvalidSubscriberID() + { + $this->expectException(ClientException::class); + $result = $this->api->get_subscriber_stats(12345); + } + /** * Test that tag_subscriber_by_email() returns the expected data. * From 511b40e3e943065762b4a56f4ed0968a38985675 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 18:12:29 +0800 Subject: [PATCH 09/17] Update method URLs to new API docs --- src/ConvertKit_API_Traits.php | 106 +++++++++++++++++----------------- 1 file changed, 53 insertions(+), 53 deletions(-) diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index 6847af7..432a7da 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -72,7 +72,7 @@ trait ConvertKit_API_Traits /** * Gets the current account * - * @see https://developers.kit.com/v4.html#get-current-account + * @see https://developers.kit.com/api-reference/accounts/get-current-account * * @return false|mixed */ @@ -84,7 +84,7 @@ public function get_account() /** * Gets the account's colors * - * @see https://developers.kit.com/v4.html#list-colors + * @see https://developers.kit.com/api-reference/accounts/list-colors * * @return false|mixed */ @@ -94,11 +94,11 @@ public function get_account_colors() } /** - * Gets the account's colors + * Updates the account's colors * * @param array $colors Hex colors. * - * @see https://developers.kit.com/v4.html#list-colors + * @see https://developers.kit.com/api-reference/accounts/update-colors * * @return false|mixed */ @@ -113,7 +113,7 @@ public function update_account_colors(array $colors) /** * Gets the Creator Profile * - * @see https://developers.kit.com/v4.html#get-creator-profile + * @see https://developers.kit.com/api-reference/accounts/get-creator-profile * * @return false|mixed */ @@ -125,7 +125,7 @@ public function get_creator_profile() /** * Gets email stats * - * @see https://developers.kit.com/v4.html#get-email-stats + * @see https://developers.kit.com/api-reference/accounts/get-email-stats * * @return false|mixed */ @@ -140,7 +140,7 @@ public function get_email_stats() * @param \DateTime|null $starting Gets stats for time period beginning on this date. Defaults to 90 days ago. * @param \DateTime|null $ending Gets stats for time period ending on this date. Defaults to today. * - * @see https://developers.kit.com/v4.html#get-growth-stats + * @see https://developers.kit.com/api-reference/accounts/get-growth-stats * * @return false|mixed */ @@ -166,7 +166,7 @@ public function get_growth_stats(\DateTime|null $starting = null, \DateTime|null * * @since 1.0.0 * - * @see https://developers.kit.com/v4.html#convertkit-api-forms + * @see https://developers.kit.com/api-reference/forms/list-forms * * @return mixed|array */ @@ -203,7 +203,7 @@ public function get_forms( * * @since 1.0.0 * - * @see https://developers.kit.com/v4.html#convertkit-api-forms + * @see https://developers.kit.com/api-reference/forms/list-forms * * @return mixed|array */ @@ -237,7 +237,7 @@ public function get_landing_pages( * * @since 2.1.0 * - * @see https://developers.kit.com/v4.html#bulk-add-subscribers-to-forms + * @see https://developers.kit.com/api-reference/forms/bulk-add-subscribers-to-forms * * @return mixed|object */ @@ -263,7 +263,7 @@ public function add_subscribers_to_forms(array $forms_subscribers_ids, string $c * @param string $email_address Email Address. * @param string $referrer Referrer. * - * @see https://developers.kit.com/v4.html#add-subscriber-to-form-by-email-address + * @see https://developers.kit.com/api-reference/forms/add-subscriber-to-form-by-email-address * * @return false|mixed */ @@ -290,7 +290,7 @@ public function add_subscriber_to_form_by_email(int $form_id, string $email_addr * @param integer $subscriber_id Subscriber ID. * @param string $referrer Referrer URL. * - * @see https://developers.kit.com/v4.html#add-subscriber-to-form + * @see https://developers.kit.com/api-reference/forms/add-subscriber-to-form * * @since 2.0.0 * @@ -326,7 +326,7 @@ public function add_subscriber_to_form(int $form_id, int $subscriber_id, string * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.kit.com/v4.html#list-subscribers-for-a-form + * @see https://developers.kit.com/api-reference/forms/list-subscribers-for-a-form * * @return false|mixed */ @@ -382,7 +382,7 @@ public function get_form_subscriptions( * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.kit.com/v4.html#list-sequences + * @see https://developers.kit.com/api-reference/sequences/list-sequences * * @return false|mixed */ @@ -410,7 +410,7 @@ public function get_sequences( * @param integer $sequence_id Sequence ID. * @param string $email_address Email Address. * - * @see https://developers.kit.com/v4.html#add-subscriber-to-sequence-by-email-address + * @see https://developers.kit.com/api-reference/sequences/add-subscriber-to-sequence-by-email-address * * @return false|mixed */ @@ -428,7 +428,7 @@ public function add_subscriber_to_sequence_by_email(int $sequence_id, string $em * @param integer $sequence_id Sequence ID. * @param integer $subscriber_id Subscriber ID. * - * @see https://developers.kit.com/v4.html#add-subscriber-to-sequence + * @see https://developers.kit.com/api-reference/sequences/add-subscriber-to-sequence * * @since 2.0.0 * @@ -453,7 +453,7 @@ public function add_subscriber_to_sequence(int $sequence_id, int $subscriber_id) * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.kit.com/v4.html#list-subscribers-for-a-sequence + * @see https://developers.kit.com/api-reference/sequences/list-subscribers-for-a-sequence * * @return false|mixed */ @@ -509,7 +509,7 @@ public function get_sequence_subscriptions( * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.kit.com/v4.html#list-tags + * @see https://developers.kit.com/api-reference/tags/list-tags * * @return mixed|array */ @@ -538,7 +538,7 @@ public function get_tags( * * @since 1.0.0 * - * @see https://developers.kit.com/v4.html#create-a-tag + * @see https://developers.kit.com/api-reference/tags/create-a-tag * * @return false|mixed */ @@ -558,7 +558,7 @@ public function create_tag(string $tag) * * @since 1.1.0 * - * @see https://developers.kit.com/v4.html#bulk-create-tags + * @see https://developers.kit.com/api-reference/tags/bulk-create-tags * * @return false|mixed */ @@ -591,7 +591,7 @@ public function create_tags(array $tags, string $callback_url = '') * @param integer $tag_id Tag ID. * @param string $email_address Email Address. * - * @see https://developers.kit.com/v4.html#tag-a-subscriber-by-email-address + * @see https://developers.kit.com/api-reference/tags/tag-a-subscriber-by-email-address * * @return false|mixed */ @@ -609,7 +609,7 @@ public function tag_subscriber_by_email(int $tag_id, string $email_address) * @param integer $tag_id Tag ID. * @param integer $subscriber_id Subscriber ID. * - * @see https://developers.kit.com/v4.html#tag-a-subscriber + * @see https://developers.kit.com/api-reference/tags/tag-a-subscriber * * @return false|mixed */ @@ -626,7 +626,7 @@ public function tag_subscriber(int $tag_id, int $subscriber_id) * * @since 1.0.0 * - * @see https://developers.kit.com/v4.html#remove-tag-from-subscriber + * @see https://developers.kit.com/api-reference/tags/remove-tag-from-subscriber * * @return false|mixed */ @@ -643,7 +643,7 @@ public function remove_tag_from_subscriber(int $tag_id, int $subscriber_id) * * @since 1.0.0 * - * @see https://developers.kit.com/v4.html#remove-tag-from-subscriber-by-email-address + * @see https://developers.kit.com/api-reference/tags/remove-tag-from-subscriber-by-email-address * * @return false|mixed */ @@ -669,7 +669,7 @@ public function remove_tag_from_subscriber_by_email(int $tag_id, string $email_a * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.kit.com/v4.html#list-subscribers-for-a-tag + * @see https://developers.kit.com/api-reference/tags/list-subscribers-for-a-tag * * @return false|mixed */ @@ -727,7 +727,7 @@ public function get_tag_subscriptions( * * @since 2.0.0 * - * @see https://developers.kit.com/v4.html#convertkit-api-email-templates + * @see https://developers.kit.com/api-reference/email-templates/list-email-templates * * @return false|mixed */ @@ -768,7 +768,7 @@ public function get_email_templates( * * @since 2.0.0 * - * @see https://developers.kit.com/v4.html#list-subscribers + * @see https://developers.kit.com/api-reference/subscribers/list-subscribers * * @return false|mixed */ @@ -841,7 +841,7 @@ public function get_subscribers( * * @since 2.0.0 * - * @see https://developers.kit.com/v4.html#create-a-subscriber + * @see https://developers.kit.com/api-reference/subscribers/create-a-subscriber * * @return mixed */ @@ -879,7 +879,7 @@ public function create_subscriber( * * @since 2.0.0 * - * @see https://developers.kit.com/v4.html#bulk-create-subscribers + * @see https://developers.kit.com/api-reference/subscribers/bulk-create-subscribers * * @return mixed */ @@ -907,7 +907,7 @@ public function create_subscribers(array $subscribers, string $callback_url = '' * * @throws \InvalidArgumentException If the email address is not a valid email format. * - * @see https://developers.kit.com/v4.html#get-a-subscriber + * @see https://developers.kit.com/api-reference/subscribers/get-a-subscriber * * @return false|integer */ @@ -947,7 +947,7 @@ public function get_subscriber_id(string $email_address) * * @param integer $subscriber_id Subscriber ID. * - * @see https://developers.kit.com/v4.html#get-a-subscriber + * @see https://developers.kit.com/api-reference/subscribers/get-a-subscriber * * @return mixed|integer */ @@ -964,7 +964,7 @@ public function get_subscriber(int $subscriber_id) * @param string $email_address New Email Address. * @param array $fields Updated Custom Fields. * - * @see https://developers.kit.com/v4.html#update-a-subscriber + * @see https://developers.kit.com/api-reference/subscribers/update-a-subscriber * * @return mixed */ @@ -999,7 +999,7 @@ public function update_subscriber( * * @param string $email_address Email Address. * - * @see https://developers.kit.com/v4.html#unsubscribe-subscriber + * @see https://developers.kit.com/api-reference/subscribers/unsubscribe-subscriber * * @return mixed|object */ @@ -1018,7 +1018,7 @@ public function unsubscribe_by_email(string $email_address) * * @param integer $subscriber_id Subscriber ID. * - * @see https://developers.kit.com/v4.html#unsubscribe-subscriber + * @see https://developers.kit.com/api-reference/subscribers/unsubscribe-subscriber * * @return mixed|object */ @@ -1036,7 +1036,7 @@ public function unsubscribe(int $subscriber_id) * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.kit.com/v4.html#list-tags-for-a-subscriber + * @see https://developers.kit.com/api-reference/subscribers/list-tags-for-a-subscriber * * @return mixed|array */ @@ -1067,7 +1067,7 @@ public function get_subscriber_tags( * @param string $before_cursor Return results before the given pagination cursor. * @param integer $per_page Number of results to return. * - * @see https://developers.kit.com/v4.html#list-broadcasts + * @see https://developers.kit.com/api-reference/broadcasts/list-broadcasts * * @return false|mixed */ @@ -1113,7 +1113,7 @@ public function get_broadcasts( * @param string $preview_text Specify the preview text of the email. * @param array $subscriber_filter Filter subscriber(s) to send the email to. * - * @see https://developers.kit.com/v4.html#create-a-broadcast + * @see https://developers.kit.com/api-reference/broadcasts/create-a-broadcast * * @return mixed|object */ @@ -1172,7 +1172,7 @@ public function create_broadcast( * * @param integer $id Broadcast ID. * - * @see https://developers.kit.com/v4.html#get-a-broadcast + * @see https://developers.kit.com/api-reference/broadcasts/get-a-broadcast * * @return mixed|object */ @@ -1187,7 +1187,7 @@ public function get_broadcast(int $id) * * @param integer $id Broadcast ID. * - * @see https://developers.kit.com/v4.html#get-stats + * @see https://developers.kit.com/api-reference/broadcasts/get-stats-for-a-broadcast * * @return mixed|object */ @@ -1220,7 +1220,7 @@ public function get_broadcast_stats(int $id) * @param string $preview_text Specify the preview text of the email. * @param array $subscriber_filter Filter subscriber(s) to send the email to. * - * @see https://developers.kit.com/#create-a-broadcast + * @see https://developers.kit.com/api-reference/broadcasts/update-a-broadcast * * @return mixed|object */ @@ -1282,7 +1282,7 @@ public function update_broadcast( * * @since 1.0.0 * - * @see https://developers.kit.com/v4.html#delete-a-broadcast + * @see https://developers.kit.com/api-reference/broadcasts/delete-a-broadcast * * @return mixed|object */ @@ -1301,7 +1301,7 @@ public function delete_broadcast(int $id) * * @since 2.0.0 * - * @see https://developers.kit.com/v4.html#list-webhooks + * @see https://developers.kit.com/api-reference/webhooks/list-webhooks * * @return false|mixed */ @@ -1333,7 +1333,7 @@ public function get_webhooks( * * @since 1.0.0 * - * @see https://developers.kit.com/v4.html#create-a-webhook + * @see https://developers.kit.com/api-reference/webhooks/create-a-webhook * * @throws \InvalidArgumentException If the event is not supported. * @@ -1409,7 +1409,7 @@ public function create_webhook(string $url, string $event, string $parameter = ' * * @since 1.0.0 * - * @see https://developers.kit.com/v4.html#delete-a-webhook + * @see https://developers.kit.com/api-reference/webhooks/delete-a-webhook * * @return mixed|object */ @@ -1428,7 +1428,7 @@ public function delete_webhook(int $id) * * @since 1.0.0 * - * @see https://developers.kit.com/v4.html#list-custom-fields + * @see https://developers.kit.com/api-reference/custom-fields/list-custom-fields * * @return false|mixed */ @@ -1458,7 +1458,7 @@ public function get_custom_fields( * * @since 1.0.0 * - * @see https://developers.kit.com/v4.html#create-a-custom-field + * @see https://developers.kit.com/api-reference/custom-fields/create-a-custom-field * * @return mixed|object */ @@ -1478,7 +1478,7 @@ public function create_custom_field(string $label) * * @since 1.0.0 * - * @see https://developers.kit.com/v4.html#bulk-create-custom-fields + * @see https://developers.kit.com/api-reference/custom-fields/bulk-create-custom-fields * * @return mixed|object */ @@ -1513,7 +1513,7 @@ public function create_custom_fields(array $labels, string $callback_url = '') * * @since 1.0.0 * - * @see https://developers.kit.com/v4.html#update-a-custom-field + * @see https://developers.kit.com/api-reference/custom-fields/update-a-custom-field * * @return mixed|object */ @@ -1532,7 +1532,7 @@ public function update_custom_field(int $id, string $label) * * @since 1.0.0 * - * @see https://developers.kit.com/#destroy-field + * @see https://developers.kit.com/api-reference/custom-fields/delete-custom-field * * @return mixed|object */ @@ -1551,7 +1551,7 @@ public function delete_custom_field(int $id) * * @since 1.0.0 * - * @see https://developers.kit.com/v4.html#list-purchases + * @see https://developers.kit.com/api-reference/purchases/list-purchases * * @return false|mixed */ @@ -1579,7 +1579,7 @@ public function get_purchases( * * @param integer $purchase_id Purchase ID. * - * @see https://developers.kit.com/v4.html#get-a-purchase + * @see https://developers.kit.com/api-reference/purchases/get-a-purchase * * @return mixed|object */ @@ -1604,7 +1604,7 @@ public function get_purchase(int $purchase_id) * @param float $total Total. * @param \DateTime|null $transaction_time Transaction date and time. * - * @see https://developers.kit.com/v4.html#create-a-purchase + * @see https://developers.kit.com/api-reference/purchases/create-a-purchase * * @return mixed|object */ @@ -1666,7 +1666,7 @@ public function create_purchase( * * @since 2.0.0 * - * @see https://developers.kit.com/v4.html#convertkit-api-segments + * @see https://developers.kit.com/api-reference/segments/list-segments * * @return false|mixed */ From 964bced182f070fe88aa60355dadc5ae2ec96b2c Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 18:37:49 +0800 Subject: [PATCH 10/17] Add `get_broadcasts_stats` method --- src/ConvertKit_API_Traits.php | 33 ++++++++++++++++++ tests/ConvertKitAPITest.php | 65 +++++++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+) diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index 71f2175..2576493 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -1196,6 +1196,39 @@ public function get_broadcast_stats(int $id) return $this->get(sprintf('broadcasts/%s/stats', $id)); } + /** + * List stats for a list of broadcasts. + * + * @param boolean $include_total_count To include the total count of records in the response, use true. + * @param string $after_cursor Return results after the given pagination cursor. + * @param string $before_cursor Return results before the given pagination cursor. + * @param integer $per_page Number of results to return. + * + * @since 2.2.1 + * + * @see https://developers.kit.com/api-reference/broadcasts/get-stats-for-a-list-of-broadcasts + * + * @return false|mixed + */ + public function get_broadcasts_stats( + bool $include_total_count = false, + string $after_cursor = '', + string $before_cursor = '', + int $per_page = 100 + ) { + // Send request. + return $this->get( + 'broadcasts/stats', + $this->build_total_count_and_pagination_params( + [], + $include_total_count, + $after_cursor, + $before_cursor, + $per_page + ) + ); + } + /** * Updates a broadcast. * diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index e05a025..e718be3 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -4190,6 +4190,71 @@ public function testGetBroadcastStatsWithInvalidBroadcastID() $this->api->get_broadcast_stats(12345); } + /** + * Test that get_broadcasts_stats() returns the expected data. + * + * @since 2.2.1 + * + * @return void + */ + public function testGetBroadcastsStats() + { + // Get broadcasts stats. + $result = $this->api->get_broadcasts_stats( + per_page: 1 + ); + + // Assert broadcasts and pagination exist. + $this->assertDataExists($result, 'broadcasts'); + $this->assertPaginationExists($result); + + // Assert a single broadcast was returned. + $this->assertCount(1, $result->broadcasts); + + // Store the Broadcast ID to check it's different from the next broadcast. + $id = $result->broadcasts[0]->id; + + // Assert has_previous_page and has_next_page are correct. + $this->assertFalse($result->pagination->has_previous_page); + $this->assertTrue($result->pagination->has_next_page); + + // Use pagination to fetch next page. + $result = $this->api->get_broadcasts_stats( + per_page: 1, + after_cursor: $result->pagination->end_cursor + ); + + // Assert broadcasts and pagination exist. + $this->assertDataExists($result, 'broadcasts'); + $this->assertPaginationExists($result); + + // Assert a single broadcast was returned. + $this->assertCount(1, $result->broadcasts); + + // Assert the broadcast ID is different from the previous broadcast. + $this->assertNotEquals($id, $result->broadcasts[0]->id); + + // Assert has_previous_page and has_next_page are correct. + $this->assertTrue($result->pagination->has_previous_page); + $this->assertTrue($result->pagination->has_next_page); + + // Use pagination to fetch previous page. + $result = $this->api->get_broadcasts_stats( + per_page: 1, + before_cursor: $result->pagination->start_cursor + ); + + // Assert broadcasts and pagination exist. + $this->assertDataExists($result, 'broadcasts'); + $this->assertPaginationExists($result); + + // Assert a single webhook was returned. + $this->assertCount(1, $result->broadcasts); + + // Assert the broadcast ID matches the first broadcast. + $this->assertEquals($id, $result->broadcasts[0]->id); + } + /** * Test that update_broadcast() throws a ClientException when an invalid * broadcast ID is specified. From a93716af09036be2334a86cb92dbd00004a236e7 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 18:40:34 +0800 Subject: [PATCH 11/17] Add `testGetBroadcastsStatsWithTotalCount` test --- tests/ConvertKitAPITest.php | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index e718be3..82d5d41 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -4255,6 +4255,29 @@ public function testGetBroadcastsStats() $this->assertEquals($id, $result->broadcasts[0]->id); } + /** + * Test that get_broadcasts_stats() returns the expected data + * when the total count is included. + * + * @since 2.2.1 + * + * @return void + */ + public function testGetBroadcastsStatsWithTotalCount() + { + $result = $this->api->get_broadcasts_stats( + include_total_count: true + ); + + // Assert broadcasts and pagination exist. + $this->assertDataExists($result, 'broadcasts'); + $this->assertPaginationExists($result); + + // Assert total count is included. + $this->assertArrayHasKey('total_count', get_object_vars($result->pagination)); + $this->assertGreaterThan(0, $result->pagination->total_count); + } + /** * Test that update_broadcast() throws a ClientException when an invalid * broadcast ID is specified. From b7ab7f962738c25d3d142264ab60dad6826e5ec3 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 18:57:34 +0800 Subject: [PATCH 12/17] Add `get_broadcast_link_clicks` method --- src/ConvertKit_API_Traits.php | 35 +++++++++++++ tests/ConvertKitAPITest.php | 95 +++++++++++++++++++++++++++++++++++ 2 files changed, 130 insertions(+) diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index 71f2175..44cac1b 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -1196,6 +1196,41 @@ public function get_broadcast_stats(int $id) return $this->get(sprintf('broadcasts/%s/stats', $id)); } + /** + * List link clicks for a specific broadcast. + * + * @param integer $id Broadcast ID. + * @param boolean $include_total_count To include the total count of records in the response, use true. + * @param string $after_cursor Return results after the given pagination cursor. + * @param string $before_cursor Return results before the given pagination cursor. + * @param integer $per_page Number of results to return. + * + * @since 2.2.1 + * + * @see https://developers.kit.com/api-reference/broadcasts/get-link-clicks-for-a-broadcast + * + * @return false|mixed + */ + public function get_broadcast_link_clicks( + int $id, + bool $include_total_count = false, + string $after_cursor = '', + string $before_cursor = '', + int $per_page = 100 + ) { + // Send request. + return $this->get( + sprintf('broadcasts/%s/clicks', $id), + $this->build_total_count_and_pagination_params( + [], + $include_total_count, + $after_cursor, + $before_cursor, + $per_page + ) + ); + } + /** * Updates a broadcast. * diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index e05a025..e49b927 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -4190,6 +4190,101 @@ public function testGetBroadcastStatsWithInvalidBroadcastID() $this->api->get_broadcast_stats(12345); } + /** + * Test that get_broadcast_link_clicks() returns the expected data. + * + * @since 2.2.1 + * + * @return void + */ + public function testGetBroadcastLinkClicks() + { + // Get broadcast link clicks. + $result = $this->api->get_broadcast_link_clicks( + $_ENV['CONVERTKIT_API_BROADCAST_ID'], + per_page: 1 + ); + + // Assert broadcasts and pagination exist. + $this->assertDataExists($result, 'broadcast'); + $this->assertPaginationExists($result); + + // Assert a single broadcast was returned. + $this->assertCount(1, $result->broadcasts); + + // Assert has_previous_page and has_next_page are correct. + $this->assertFalse($result->pagination->has_previous_page); + $this->assertTrue($result->pagination->has_next_page); + + // Use pagination to fetch next page. + $result = $this->api->get_broadcasts_stats( + per_page: 1, + after_cursor: $result->pagination->end_cursor + ); + + // Assert broadcasts and pagination exist. + $this->assertDataExists($result, 'broadcast'); + $this->assertPaginationExists($result); + + // Assert a single broadcast was returned. + $this->assertCount(1, $result->broadcasts); + + // Assert has_previous_page and has_next_page are correct. + $this->assertTrue($result->pagination->has_previous_page); + $this->assertTrue($result->pagination->has_next_page); + + // Use pagination to fetch previous page. + $result = $this->api->get_broadcasts_stats( + per_page: 1, + before_cursor: $result->pagination->start_cursor + ); + + // Assert broadcasts and pagination exist. + $this->assertDataExists($result, 'broadcasts'); + $this->assertPaginationExists($result); + + // Assert a single webhook was returned. + $this->assertCount(1, $result->broadcasts); + } + + /** + * Test that get_broadcast_link_clicks() returns the expected data + * when the total count is included. + * + * @since 2.2.1 + * + * @return void + */ + public function testGetBroadcastLinkClicksWithTotalCount() + { + $result = $this->api->get_broadcast_link_clicks( + $_ENV['CONVERTKIT_API_BROADCAST_ID'], + include_total_count: true + ); + + // Assert broadcasts and pagination exist. + $this->assertDataExists($result, 'broadcast'); + $this->assertPaginationExists($result); + + // Assert total count is included. + $this->assertArrayHasKey('total_count', get_object_vars($result->pagination)); + $this->assertGreaterThan(0, $result->pagination->total_count); + } + + /** + * Test that get_broadcast_link_clicks() throws a ClientException when an invalid + * broadcast ID is specified. + * + * @since 2.2.1 + * + * @return void + */ + public function testGetBroadcastLinkClicksWithInvalidBroadcastID() + { + $this->expectException(ClientException::class); + $this->api->get_broadcast_link_clicks(12345); + } + /** * Test that update_broadcast() throws a ClientException when an invalid * broadcast ID is specified. From 8480d84b2af94ae0d0bb258b556c7d2273ac0e4e Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 19:24:32 +0800 Subject: [PATCH 13/17] Add `update_tag_name` method --- src/ConvertKit_API_Traits.php | 17 ++++++++++++ tests/ConvertKitAPITest.php | 49 +++++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+) diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index 71f2175..927dca2 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -585,6 +585,23 @@ public function create_tags(array $tags, string $callback_url = '') ); } + /** + * Updates the name of a tag. + * + * @param integer $tag_id Tag ID. + * @param string $name New name. + * + * @since 2.2.1 + * + * @see https://developers.kit.com/api-reference/tags/update-tag-name + * + * @return false|mixed + */ + public function update_tag_name(int $tag_id, string $name) + { + return $this->put(sprintf('tags/%s', $tag_id), ['name' => $name]); + } + /** * Tags a subscriber with the given existing Tag. * diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index e05a025..ad89999 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -1722,6 +1722,55 @@ public function testCreateTagsThatExist() $this->assertEquals($result->tags[0]->name, $_ENV['CONVERTKIT_API_TAG_NAME_2']); } + /** + * Test that update_tag_name() returns the expected data. + * + * @since 2.2.1 + * + * @return void + */ + public function testUpdateTagName() + { + $result = $this->api->update_tag_name( + tag_id: (int) $_ENV['CONVERTKIT_API_TAG_ID'], + name: $_ENV['CONVERTKIT_API_TAG_NAME'], + ); + } + + /** + * Test that update_tag_name() throws a ClientException when an invalid + * tag ID is specified. + * + * @since 2.2.1 + * + * @return void + */ + public function testUpdateTagNameWithInvalidTagID() + { + $this->expectException(ClientException::class); + $result = $this->api->update_tag_name( + tag_id: 12345, + name: $_ENV['CONVERTKIT_API_TAG_NAME'], + ); + } + + /** + * Test that update_tag_name() throws a ClientException when a blank + * name is specified. + * + * @since 2.2.1 + * + * @return void + */ + public function testUpdateTagNameWithBlankName() + { + $this->expectException(ClientException::class); + $result = $this->api->update_tag_name( + tag_id: (int) $_ENV['CONVERTKIT_API_TAG_ID'], + name: '' + ); + } + /** * Test that tag_subscriber_by_email() returns the expected data. * From 7150507947f200bdbc8038afc8a70db1032436f5 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 19:27:13 +0800 Subject: [PATCH 14/17] Fix tests --- tests/ConvertKitAPITest.php | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index ad89999..54ec07d 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -1735,6 +1735,10 @@ public function testUpdateTagName() tag_id: (int) $_ENV['CONVERTKIT_API_TAG_ID'], name: $_ENV['CONVERTKIT_API_TAG_NAME'], ); + + // Assert existing tag is returned. + $this->assertEquals($result->tag->id, (int) $_ENV['CONVERTKIT_API_TAG_ID']); + $this->assertEquals($result->tag->name, $_ENV['CONVERTKIT_API_TAG_NAME']); } /** From 4f088b7001b084f4d09ef53fb0b20330abb790ce Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 21:13:48 +0800 Subject: [PATCH 15/17] Remove `include_total_count`, as not supported --- src/ConvertKit_API_Traits.php | 18 ++++------ tests/ConvertKitAPITest.php | 64 +++-------------------------------- 2 files changed, 12 insertions(+), 70 deletions(-) diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index 44cac1b..381746f 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -1199,11 +1199,10 @@ public function get_broadcast_stats(int $id) /** * List link clicks for a specific broadcast. * - * @param integer $id Broadcast ID. - * @param boolean $include_total_count To include the total count of records in the response, use true. - * @param string $after_cursor Return results after the given pagination cursor. - * @param string $before_cursor Return results before the given pagination cursor. - * @param integer $per_page Number of results to return. + * @param integer $id Broadcast ID. + * @param string $after_cursor Return results after the given pagination cursor. + * @param string $before_cursor Return results before the given pagination cursor. + * @param integer $per_page Number of results to return. * * @since 2.2.1 * @@ -1213,7 +1212,6 @@ public function get_broadcast_stats(int $id) */ public function get_broadcast_link_clicks( int $id, - bool $include_total_count = false, string $after_cursor = '', string $before_cursor = '', int $per_page = 100 @@ -1222,11 +1220,9 @@ public function get_broadcast_link_clicks( return $this->get( sprintf('broadcasts/%s/clicks', $id), $this->build_total_count_and_pagination_params( - [], - $include_total_count, - $after_cursor, - $before_cursor, - $per_page + after_cursor: $after_cursor, + before_cursor: $before_cursor, + per_page: $per_page ) ); } diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index e49b927..cb83d34 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -4205,70 +4205,16 @@ public function testGetBroadcastLinkClicks() per_page: 1 ); - // Assert broadcasts and pagination exist. - $this->assertDataExists($result, 'broadcast'); + // Assert clicks and pagination exist. + $this->assertDataExists($result->broadcast, 'clicks'); $this->assertPaginationExists($result); - // Assert a single broadcast was returned. - $this->assertCount(1, $result->broadcasts); + // Assert a single click was returned. + $this->assertCount(1, $result->broadcast->clicks); // Assert has_previous_page and has_next_page are correct. $this->assertFalse($result->pagination->has_previous_page); - $this->assertTrue($result->pagination->has_next_page); - - // Use pagination to fetch next page. - $result = $this->api->get_broadcasts_stats( - per_page: 1, - after_cursor: $result->pagination->end_cursor - ); - - // Assert broadcasts and pagination exist. - $this->assertDataExists($result, 'broadcast'); - $this->assertPaginationExists($result); - - // Assert a single broadcast was returned. - $this->assertCount(1, $result->broadcasts); - - // Assert has_previous_page and has_next_page are correct. - $this->assertTrue($result->pagination->has_previous_page); - $this->assertTrue($result->pagination->has_next_page); - - // Use pagination to fetch previous page. - $result = $this->api->get_broadcasts_stats( - per_page: 1, - before_cursor: $result->pagination->start_cursor - ); - - // Assert broadcasts and pagination exist. - $this->assertDataExists($result, 'broadcasts'); - $this->assertPaginationExists($result); - - // Assert a single webhook was returned. - $this->assertCount(1, $result->broadcasts); - } - - /** - * Test that get_broadcast_link_clicks() returns the expected data - * when the total count is included. - * - * @since 2.2.1 - * - * @return void - */ - public function testGetBroadcastLinkClicksWithTotalCount() - { - $result = $this->api->get_broadcast_link_clicks( - $_ENV['CONVERTKIT_API_BROADCAST_ID'], - include_total_count: true - ); - - // Assert broadcasts and pagination exist. - $this->assertDataExists($result, 'broadcast'); - $this->assertPaginationExists($result); - - // Assert total count is included. - $this->assertArrayHasKey('total_count', get_object_vars($result->pagination)); - $this->assertGreaterThan(0, $result->pagination->total_count); + $this->assertFalse($result->pagination->has_next_page); } /** From ad4c6a52a39f13f43f92c348f1ad9d3526aa48ac Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Fri, 3 Oct 2025 10:55:12 +0800 Subject: [PATCH 16/17] Reinstate tests --- tests/ConvertKitAPITest.php | 43 +++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index a8a65f0..1761569 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -1775,6 +1775,49 @@ public function testUpdateTagNameWithBlankName() ); } + /** + * Test that get_subscriber_stats() returns the expected data + * when using a valid subscriber ID. + * + * @since 2.2.1 + * + * @return void + */ + public function testGetSubscriberStats() + { + $result = $this->api->get_subscriber_stats( + id: (int) $_ENV['CONVERTKIT_API_SUBSCRIBER_ID'] + ); + $this->assertArrayHasKey('subscriber', get_object_vars($result)); + $this->assertArrayHasKey('id', get_object_vars($result->subscriber)); + $this->assertArrayHasKey('stats', get_object_vars($result->subscriber)); + $this->assertArrayHasKey('sent', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('opened', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('clicked', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('bounced', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('open_rate', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('click_rate', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('last_sent', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('last_opened', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('last_clicked', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('sends_since_last_open', get_object_vars($result->subscriber->stats)); + $this->assertArrayHasKey('sends_since_last_click', get_object_vars($result->subscriber->stats)); + } + + /** + * Test that get_subscriber_stats() throws a ClientException when an invalid + * subscriber ID is specified. + * + * @since 2.2.1 + * + * @return void + */ + public function testGetSubscriberStatsWithInvalidSubscriberID() + { + $this->expectException(ClientException::class); + $result = $this->api->get_subscriber_stats(12345); + } + /** * Test that tag_subscriber_by_email() returns the expected data. * From 4e900445132f83fde6cde77ad9ab53e4e94d2b7b Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Fri, 3 Oct 2025 10:57:44 +0800 Subject: [PATCH 17/17] Reinstate method and tests --- src/ConvertKit_API_Traits.php | 33 +++++++++++++ tests/ConvertKitAPITest.php | 88 +++++++++++++++++++++++++++++++++++ 2 files changed, 121 insertions(+) diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index e08aaee..136009c 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -1258,6 +1258,39 @@ public function get_broadcast_link_clicks( ); } + /** + * List stats for a list of broadcasts. + * + * @param boolean $include_total_count To include the total count of records in the response, use true. + * @param string $after_cursor Return results after the given pagination cursor. + * @param string $before_cursor Return results before the given pagination cursor. + * @param integer $per_page Number of results to return. + * + * @since 2.2.1 + * + * @see https://developers.kit.com/api-reference/broadcasts/get-stats-for-a-list-of-broadcasts + * + * @return false|mixed + */ + public function get_broadcasts_stats( + bool $include_total_count = false, + string $after_cursor = '', + string $before_cursor = '', + int $per_page = 100 + ) { + // Send request. + return $this->get( + 'broadcasts/stats', + $this->build_total_count_and_pagination_params( + [], + $include_total_count, + $after_cursor, + $before_cursor, + $per_page + ) + ); + } + /** * Updates a broadcast. * diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index 1761569..75245a2 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -4327,6 +4327,94 @@ public function testGetBroadcastLinkClicksWithInvalidBroadcastID() $this->api->get_broadcast_link_clicks(12345); } + /** + * Test that get_broadcasts_stats() returns the expected data. + * + * @since 2.2.1 + * + * @return void + */ + public function testGetBroadcastsStats() + { + // Get broadcasts stats. + $result = $this->api->get_broadcasts_stats( + per_page: 1 + ); + + // Assert broadcasts and pagination exist. + $this->assertDataExists($result, 'broadcasts'); + $this->assertPaginationExists($result); + + // Assert a single broadcast was returned. + $this->assertCount(1, $result->broadcasts); + + // Store the Broadcast ID to check it's different from the next broadcast. + $id = $result->broadcasts[0]->id; + + // Assert has_previous_page and has_next_page are correct. + $this->assertFalse($result->pagination->has_previous_page); + $this->assertTrue($result->pagination->has_next_page); + + // Use pagination to fetch next page. + $result = $this->api->get_broadcasts_stats( + per_page: 1, + after_cursor: $result->pagination->end_cursor + ); + + // Assert broadcasts and pagination exist. + $this->assertDataExists($result, 'broadcasts'); + $this->assertPaginationExists($result); + + // Assert a single broadcast was returned. + $this->assertCount(1, $result->broadcasts); + + // Assert the broadcast ID is different from the previous broadcast. + $this->assertNotEquals($id, $result->broadcasts[0]->id); + + // Assert has_previous_page and has_next_page are correct. + $this->assertTrue($result->pagination->has_previous_page); + $this->assertTrue($result->pagination->has_next_page); + + // Use pagination to fetch previous page. + $result = $this->api->get_broadcasts_stats( + per_page: 1, + before_cursor: $result->pagination->start_cursor + ); + + // Assert broadcasts and pagination exist. + $this->assertDataExists($result, 'broadcasts'); + $this->assertPaginationExists($result); + + // Assert a single webhook was returned. + $this->assertCount(1, $result->broadcasts); + + // Assert the broadcast ID matches the first broadcast. + $this->assertEquals($id, $result->broadcasts[0]->id); + } + + /** + * Test that get_broadcasts_stats() returns the expected data + * when the total count is included. + * + * @since 2.2.1 + * + * @return void + */ + public function testGetBroadcastsStatsWithTotalCount() + { + $result = $this->api->get_broadcasts_stats( + include_total_count: true + ); + + // Assert broadcasts and pagination exist. + $this->assertDataExists($result, 'broadcasts'); + $this->assertPaginationExists($result); + + // Assert total count is included. + $this->assertArrayHasKey('total_count', get_object_vars($result->pagination)); + $this->assertGreaterThan(0, $result->pagination->total_count); + } + /** * Test that update_broadcast() throws a ClientException when an invalid * broadcast ID is specified.