v4 API: OAuth

.github/workflows/tests.yml

@@ -47,10 +47,13 @@ jobs:
           path: .env.dist.testing
           contents: |
 
-            CONVERTKIT_API_KEY=${{ secrets.CONVERTKIT_API_KEY }}
-            CONVERTKIT_API_SECRET=${{ secrets.CONVERTKIT_API_SECRET }}
-            CONVERTKIT_API_KEY_NO_DATA=${{ secrets.CONVERTKIT_API_KEY_NO_DATA }}
-            CONVERTKIT_API_SECRET_NO_DATA=${{ secrets.CONVERTKIT_API_SECRET_NO_DATA }}
+            CONVERTKIT_OAUTH_ACCESS_TOKEN=${{ secrets.CONVERTKIT_OAUTH_ACCESS_TOKEN }}
+            CONVERTKIT_OAUTH_REFRESH_TOKEN=${{ secrets.CONVERTKIT_OAUTH_REFRESH_TOKEN }}
+            CONVERTKIT_OAUTH_ACCESS_TOKEN_NO_DATA=${{ secrets.CONVERTKIT_OAUTH_ACCESS_TOKEN_NO_DATA }}
+            CONVERTKIT_OAUTH_REFRESH_TOKEN_NO_DATA=${{ secrets.CONVERTKIT_OAUTH_REFRESH_TOKEN_NO_DATA }}
+            CONVERTKIT_OAUTH_CLIENT_ID=${{ secrets.CONVERTKIT_OAUTH_CLIENT_ID }}
+            CONVERTKIT_OAUTH_CLIENT_SECRET=${{ secrets.CONVERTKIT_OAUTH_CLIENT_SECRET }}
+            CONVERTKIT_OAUTH_REDIRECT_URI=${{ secrets.CONVERTKIT_OAUTH_REDIRECT_URI }}
           write-mode: append
 
       # Rename .env.dist.testing to .env, so PHPUnit reads it for tests.

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.  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`:
+
+```php
+$api = new \ConvertKit_API\ConvertKit_API(
+    clientID: '<your_oauth_client_id>',
+    clientSecret: '<your_oauth_client_secret>',
+    accessToken: '<your_oauth_access_token>'
+);
+```
+
+## 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()`

README.md

@@ -4,9 +4,14 @@ The ConvertKit PHP SDK provides convinient access to the ConvertKit API from app
 
 It includes a pre-defined set of methods for interacting with the API.
 
-## Requirements
+## Version Guidance
 
-PHP 7.4 and later.
+| SDK Version | API Version | API Authentication | PHP Version  |
+|-------------|-------------|--------------------|--------------|
+| 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
 
@@ -34,6 +39,104 @@ If you use Composer, these dependencies should be handled automatically.
 
 ## Getting Started
 
+### 2.x (v4 API, OAuth, PHP 8.0+)
+
+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).
+require_once 'vendor/autoload.php';
+
+// Initialize the API class.
+$api = new \ConvertKit_API\ConvertKit_API(
+    clientID: '<your_oauth_client_id>',
+    clientSecret: '<your_oauth_client_secret>'
+);
+
+// Redirect to begin the OAuth process.
+header('Location: '.$api->get_oauth_url('<your_redirect_uri>'));
+```
+
+Once the user grants your application access to their ConvertKit account, they'll be redirected to your Redirect URI with an authorization code. For example:
+
+`your-redirect-uri?code=<auth_code>`
+
+At this point, your application needs to exchange the authorization code for an access token and refresh token.
+
+```php
+$result = $api->get_access_token(
+    authCode: '<auth_code>',
+    redirectURI: '<your_redirect_uri>'
+);
+```
+
+`$result` is an array comprising of:
+- `access_token`: The access token, used to make authenticated requests to the API
+- `refresh_token`: The refresh token, used to fetch a new access token once the current access token has expired
+- `created_at`: When the access token was created
+- `expires_in`: The number of seconds from `created_at` that the access token will expire
+
+Once you have an access token, re-initialize the API class with it:
+
+```php
+// Initialize the API class.
+$api = new \ConvertKit_API\ConvertKit_API(
+    clientID: '<your_oauth_client_id>',
+    clientSecret: '<your_oauth_client_secret>',
+    accessToken: '<your_access_token>'
+);
+```
+
+To refresh an access token:
+
+```php
+$result = $api->refresh_token(
+    refreshToken: '<your_refresh_token>',
+    redirectURI: '<your_redirect_uri>'
+);
+```
+
+`$result` is an array comprising of:
+- `access_token`: The access token, used to make authenticated requests to the API
+- `refresh_token`: The refresh token, used to fetch a new access token once the current access token has expired
+- `created_at`: When the access token was created
+- `expires_in`: The number of seconds from `created_at` that the access token will expire
+
+Once you have refreshed the access token i.e. obtained a new access token, re-initialize the API class with it:
+
+```php
+// Initialize the API class.
+$api = new \ConvertKit_API\ConvertKit_API(
+    clientID: '<your_oauth_client_id>',
+    clientSecret: '<your_oauth_client_secret>',
+    accessToken: '<your_new_access_token>'
+);
+```
+
+API requests may then be performed:
+
+```php
+$result = $api->add_subscriber_to_form(12345, '[email protected]');
+```
+
+To determine whether a new entity / relationship was created, or an existing entity / relationship updated, inspect the HTTP code of the last request:
+
+```php
+$result = $api->add_subscriber_to_form(12345, '[email protected]');
+$code = $api->getResponseInterface()->getStatusCode(); // 200 OK if e.g. a subscriber already added to the specified form, 201 Created if the subscriber added to the specified form for the first time.
+```
+
+The PSR-7 response can be fetched and further inspected, if required - for example, to check if a header exists:
+
+```php
+$result = $api->add_subscriber_to_form(12345, '[email protected]');
+$api->getResponseInterface()->hasHeader('Content-Length'); // Check if the last API request included a `Content-Length` header
+```
+
+### 1.x (v3 API, API Key and Secret, PHP 7.4+)
+
 Get your ConvertKit API Key and API Secret [here](https://app.convertkit.com/account/edit) and set it somewhere in your application.
 
 ```php

phpcs.xml

@@ -72,7 +72,7 @@
     <!-- Permit slightly longer line lengths -->
     <rule ref="Generic.Files.LineLength">
         <properties>
-            <property name="lineLimit" value="130"/>
+            <property name="lineLimit" value="150"/>
             <property name="absoluteLineLimit" value="0"/>
         </properties>
     </rule>

phpstan.neon.dist

@@ -6,9 +6,4 @@ parameters:
 
     # Should not need to edit anything below here
     # Rule Level: https://phpstan.org/user-guide/rule-levels
-    level: 8
-
-    # Ignore the following errors, as PHPStan either does not have registered symbols for them yet,
-    # or the symbols are inaccurate.
-    ignoreErrors:
-        - '#\$headers of class GuzzleHttp\\Psr7\\Request constructor expects#'
+    level: 8

phpstan.neon.example

@@ -6,9 +6,4 @@ parameters:
 
     # Should not need to edit anything below here
     # Rule Level: https://phpstan.org/user-guide/rule-levels
-    level: 8
-
-    # Ignore the following errors, as PHPStan either does not have registered symbols for them yet,
-    # or the symbols are inaccurate.
-    ignoreErrors:
-        - '#\$headers of class GuzzleHttp\\Psr7\\Request constructor expects#'
+    level: 8