From f6563c95cf2556f352644d98356738bac7631982 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Thu, 11 Apr 2024 14:48:19 +0100 Subject: [PATCH 1/4] First draft of migration guide --- MIGRATION.md | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 MIGRATION.md diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..9f3f47c --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,121 @@ +# Migrating from v1.x SDK (v3 API) to v2.x SDK (v4 API) + +Whilst every best effort is made to minimise the number of breaking changes, some breaking changes exist to ensure improved method naming conventions and compatibility with OAuth authentication and the v4 API. + +This guide is designed to cover changes that developers may need to make to their existing implementation when upgrading to the v2 SDK. + +## PHP Version + +The minimum supported PHP version is `8.0`. Users on older PHP versions should continue to use the v1 SDK. + +## Authentication + +Authentication is now via OAuth. Refer to the README file for an implementation guide. + +Initializing the `ConvertKit_API` class now accepts a `clientID`, `clientSecret` and `accessToken` in place of the existing `api_key` and `api_secret`: + +```php +$api = new \ConvertKit_API\ConvertKit_API( + clientID: '', + clientSecret: '', + accessToken: '' +); +``` + +## Pagination + +For list based endpoints which fetch data from the API (such as broadcasts, custom fields, subscribers, tags, email templates, forms, purchases etc.), cursor based pagination is used. The following parameters can be specified in the API methods: + +- `per_page`: Defines the number of results to return, with a maximum value of 100 +- `after_cursor`: When specified, returns the next page of results based on the current result's `pagination->end_cursor` value +- `before_cursor`: When specified, returns the previous page of results based on the current result's `pagination->start_cursor` value + +## Accounts + +- Added: `get_account_colors()` +- Added: `update_account_colors()` +- Added: `get_creator_profile()` +- Added: `get_email_stats()` +- Added: `get_growth_stats()` + +## Broadcasts + +- Updated: `get_broadcasts()` supports pagination +- Updated: `create_broadcast()`: +-- `email_layout_template` is now `email_template_id`. To fetch the ID of the account's email templates, refer to `get_email_templates()` +-- `preview_text` option added +-- `subscriber_filter` option added +- Updated: `update_broadcast()` +-- `email_layout_template` is now `email_template_id`. To fetch the ID of the account's email templates, refer to `get_email_templates()` +-- `preview_text` option added +-- `subscriber_filter` option added +- Changed: `destroy_broadcast()` is renamed to `delete_broadcast()` + +## Custom Fields + +- Added: `create_custom_fields()` to create multiple custom fields in a single request +- Updated: `get_custom_fields()` supports pagination + +## Subscribers + +- Added: `create_subscriber()`. The concept of creating a subscriber via a form, tag or sequence is replaced with this new method. The subscriber can then be subscribed to resources (forms, tag, sequences) as necessary. +- Added: `create_subscribers()` to create multiple subscribers in a single request +- Added: `get_subscribers()` +- Changed: `unsubscribe()` is now `unsubscribe_by_email()`. Use `unsubscribe()` for unsubscribing by a subscriber ID +- Updated: `get_subscriber_tags()` supports pagination + +## Tags + +- Added: `create_tags()` to create multiple tags in a single request +- Updated: `get_tags()` supports pagination +- Updated: `get_tag_subscriptions()`: +-- supports pagination +-- supports filtering by subscribers by dates, covering `created_after`, `created_before`, `tagged_after` and `tagged_before` +-- `sort_order` is no longer supported +- Changed: `tag_subscriber()` is now `tag_subscriber_by_email()`. Use `tag_subscriber()` for tagging by subscriber ID + +## Email Templates + +- Added: `get_email_templates()` + +## Forms + +- Updated: `get_forms()`: +-- supports pagination +-- only returns active forms by default. Use the `status` parameter to filter by `active`, `archived`, `trashed` or `all` +- Updated: `get_landing_pages()`: +-- supports pagination +-- only returns active landing pages by default. Use the `status` parameter to filter by `active`, `archived`, `trashed` or `all` +- Updated: `get_form_subscriptions()`: +-- supports pagination +-- supports filtering by subscribers by dates, covering `created_after`, `created_before`, `added_after` and `added_before` +-- `sort_order` is no longer supported +- Changed: `add_subscriber_to_form()` is now `add_subscriber_to_form_by_email()`. Use `add_subscriber_to_form()` for adding subscriber to form by subscriber ID + +## Purchases + +- Updated: `create_purchase()` now supports named parameters for purchase data, instead of an `$options` array +- Changed: `list_purchases()` is now `get_purchases()`, with pagination support + +## Segments + +- Added: `get_segments()` + +## Sequences + +- Changed: `add_subscriber_to_sequence()` is now `add_subscriber_to_sequence_by_email()`. Use `add_subscriber_to_sequence()` for adding a subscriber to a sequence by subscriber ID +- Updated: `get_sequences()` supports pagination +- Updated: `get_sequence_subscriptions()`: +-- supports pagination +-- supports filtering by subscribers by dates, covering `created_after`, `created_before`, `added_after` and `added_before` +-- `sort_order` is no longer supported + +## Webhooks + +- Added: `get_webhooks()` +- Changed: `destroy_webhook()` is now `delete_webhook()` + +## Other + +- Removed: `form_subscribe()` was previously deprecated. Use `add_subscriber_to_form()` or `add_subscriber_to_form_by_email()` +- Removed: `add_tag()` was previously deprecated. Use `tag_subscriber()` or `tag_subscriber_by_email()` \ No newline at end of file From f327145b4f886ffa92a2f2ab5891e6be143b975a Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Thu, 11 Apr 2024 14:48:41 +0100 Subject: [PATCH 2/4] Update wording on how to register an OAuth application --- README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 4579b3d..78ec3b8 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +== README.MD + # ConvertKit SDK PHP The ConvertKit PHP SDK provides convinient access to the ConvertKit API from applications written in the PHP language. @@ -39,7 +41,9 @@ If you use Composer, these dependencies should be handled automatically. ### 2.x (v4 API, OAuth, PHP 8.0+) -Please reach out to ConvertKit to set up an OAuth application for you. We'll provide you with your Client ID and Secret. +First, register your OAuth application in the `OAuth Applications` section at https://app.convertkit.com/account_settings/advanced_settings. + +Using the supplied Client ID and secret, redirect the user to ConvertKit to grant your application access to their ConvertKit account. ```php // Require the autoloader (if you're using a PHP framework, this may already be done for you). @@ -50,11 +54,8 @@ $api = new \ConvertKit_API\ConvertKit_API( clientID: '', clientSecret: '' ); -``` -To begin the OAuth process, redirect the user to ConvertKit to grant your application access to their ConvertKit account. - -```php +// Redirect to begin the OAuth process. header('Location: '.$api->get_oauth_url('')); ``` From fb4759478589bbdc2b1bb491a1e3ef245d2e5b7f Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Thu, 11 Apr 2024 14:53:17 +0100 Subject: [PATCH 3/4] Added links between readme and migration guide --- MIGRATION.md | 2 +- README.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 9f3f47c..6d6e830 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -10,7 +10,7 @@ The minimum supported PHP version is `8.0`. Users on older PHP versions should ## Authentication -Authentication is now via OAuth. Refer to the README file for an implementation guide. +Authentication is now via OAuth. It's recommended to refer to the README file's [`Getting Started`](README.md#2x-v4-api-oauth-php-80) section for implementation. Initializing the `ConvertKit_API` class now accepts a `clientID`, `clientSecret` and `accessToken` in place of the existing `api_key` and `api_secret`: diff --git a/README.md b/README.md index 78ec3b8..b2bd177 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ -== README.MD - # ConvertKit SDK PHP The ConvertKit PHP SDK provides convinient access to the ConvertKit API from applications written in the PHP language. @@ -13,6 +11,8 @@ It includes a pre-defined set of methods for interacting with the API. | 1.x | v3 | API Key and Secret | 7.4+ | | 2.x | v4 | OAuth | 8.0+ | +Refer to [this guide](MIGRATION.md) for changes when upgrading to the v2 SDK. + ## Composer You can install this PHP SDK via [Composer](http://getcomposer.org/). Run the following command: From c5ac174ac8230229227ac231d0b3f4808b812aa4 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Thu, 11 Apr 2024 14:55:46 +0100 Subject: [PATCH 4/4] Fixed indenting of sub bullet points --- MIGRATION.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 6d6e830..0a9fadb 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -42,13 +42,13 @@ For list based endpoints which fetch data from the API (such as broadcasts, cust - Updated: `get_broadcasts()` supports pagination - Updated: `create_broadcast()`: --- `email_layout_template` is now `email_template_id`. To fetch the ID of the account's email templates, refer to `get_email_templates()` --- `preview_text` option added --- `subscriber_filter` option added + - `email_layout_template` is now `email_template_id`. To fetch the ID of the account's email templates, refer to `get_email_templates()` + - `preview_text` option added + - `subscriber_filter` option added - Updated: `update_broadcast()` --- `email_layout_template` is now `email_template_id`. To fetch the ID of the account's email templates, refer to `get_email_templates()` --- `preview_text` option added --- `subscriber_filter` option added + - `email_layout_template` is now `email_template_id`. To fetch the ID of the account's email templates, refer to `get_email_templates()` + - `preview_text` option added + - `subscriber_filter` option added - Changed: `destroy_broadcast()` is renamed to `delete_broadcast()` ## Custom Fields @@ -69,9 +69,9 @@ For list based endpoints which fetch data from the API (such as broadcasts, cust - Added: `create_tags()` to create multiple tags in a single request - Updated: `get_tags()` supports pagination - Updated: `get_tag_subscriptions()`: --- supports pagination --- supports filtering by subscribers by dates, covering `created_after`, `created_before`, `tagged_after` and `tagged_before` --- `sort_order` is no longer supported + - supports pagination + - supports filtering by subscribers by dates, covering `created_after`, `created_before`, `tagged_after` and `tagged_before` + - `sort_order` is no longer supported - Changed: `tag_subscriber()` is now `tag_subscriber_by_email()`. Use `tag_subscriber()` for tagging by subscriber ID ## Email Templates @@ -81,15 +81,15 @@ For list based endpoints which fetch data from the API (such as broadcasts, cust ## Forms - Updated: `get_forms()`: --- supports pagination --- only returns active forms by default. Use the `status` parameter to filter by `active`, `archived`, `trashed` or `all` + - supports pagination + - only returns active forms by default. Use the `status` parameter to filter by `active`, `archived`, `trashed` or `all` - Updated: `get_landing_pages()`: --- supports pagination --- only returns active landing pages by default. Use the `status` parameter to filter by `active`, `archived`, `trashed` or `all` + - supports pagination + - only returns active landing pages by default. Use the `status` parameter to filter by `active`, `archived`, `trashed` or `all` - Updated: `get_form_subscriptions()`: --- supports pagination --- supports filtering by subscribers by dates, covering `created_after`, `created_before`, `added_after` and `added_before` --- `sort_order` is no longer supported + - supports pagination + - supports filtering by subscribers by dates, covering `created_after`, `created_before`, `added_after` and `added_before` + - `sort_order` is no longer supported - Changed: `add_subscriber_to_form()` is now `add_subscriber_to_form_by_email()`. Use `add_subscriber_to_form()` for adding subscriber to form by subscriber ID ## Purchases @@ -106,9 +106,9 @@ For list based endpoints which fetch data from the API (such as broadcasts, cust - Changed: `add_subscriber_to_sequence()` is now `add_subscriber_to_sequence_by_email()`. Use `add_subscriber_to_sequence()` for adding a subscriber to a sequence by subscriber ID - Updated: `get_sequences()` supports pagination - Updated: `get_sequence_subscriptions()`: --- supports pagination --- supports filtering by subscribers by dates, covering `created_after`, `created_before`, `added_after` and `added_before` --- `sort_order` is no longer supported + - supports pagination + - supports filtering by subscribers by dates, covering `created_after`, `created_before`, `added_after` and `added_before` + - `sort_order` is no longer supported ## Webhooks