Skip to content

Commit 503cfea

Browse files
n7studiosn7studios
authored
Merge pull request #74 from ConvertKit/v4-api-oauth
v4 API: OAuth
2 parents 3e3a04b + d079068 commit 503cfea

9 files changed

+6018
-2300
lines changed

‎.github/workflows/tests.yml

+7-4
Original file line numberDiff line numberDiff line change
@@ -47,10 +47,13 @@ jobs:
4747
path: .env.dist.testing
4848
contents: |
4949
50-
CONVERTKIT_API_KEY=${{ secrets.CONVERTKIT_API_KEY }}
51-
CONVERTKIT_API_SECRET=${{ secrets.CONVERTKIT_API_SECRET }}
52-
CONVERTKIT_API_KEY_NO_DATA=${{ secrets.CONVERTKIT_API_KEY_NO_DATA }}
53-
CONVERTKIT_API_SECRET_NO_DATA=${{ secrets.CONVERTKIT_API_SECRET_NO_DATA }}
50+
CONVERTKIT_OAUTH_ACCESS_TOKEN=${{ secrets.CONVERTKIT_OAUTH_ACCESS_TOKEN }}
51+
CONVERTKIT_OAUTH_REFRESH_TOKEN=${{ secrets.CONVERTKIT_OAUTH_REFRESH_TOKEN }}
52+
CONVERTKIT_OAUTH_ACCESS_TOKEN_NO_DATA=${{ secrets.CONVERTKIT_OAUTH_ACCESS_TOKEN_NO_DATA }}
53+
CONVERTKIT_OAUTH_REFRESH_TOKEN_NO_DATA=${{ secrets.CONVERTKIT_OAUTH_REFRESH_TOKEN_NO_DATA }}
54+
CONVERTKIT_OAUTH_CLIENT_ID=${{ secrets.CONVERTKIT_OAUTH_CLIENT_ID }}
55+
CONVERTKIT_OAUTH_CLIENT_SECRET=${{ secrets.CONVERTKIT_OAUTH_CLIENT_SECRET }}
56+
CONVERTKIT_OAUTH_REDIRECT_URI=${{ secrets.CONVERTKIT_OAUTH_REDIRECT_URI }}
5457
write-mode: append
5558

5659
# Rename .env.dist.testing to .env, so PHPUnit reads it for tests.

‎MIGRATION.md

+121
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Migrating from v1.x SDK (v3 API) to v2.x SDK (v4 API)
2+
3+
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.
4+
5+
This guide is designed to cover changes that developers may need to make to their existing implementation when upgrading to the v2 SDK.
6+
7+
## PHP Version
8+
9+
The minimum supported PHP version is `8.0`. Users on older PHP versions should continue to use the v1 SDK.
10+
11+
## Authentication
12+
13+
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.
14+
15+
Initializing the `ConvertKit_API` class now accepts a `clientID`, `clientSecret` and `accessToken` in place of the existing `api_key` and `api_secret`:
16+
17+
```php
18+
$api = new \ConvertKit_API\ConvertKit_API(
19+
clientID: '<your_oauth_client_id>',
20+
clientSecret: '<your_oauth_client_secret>',
21+
accessToken: '<your_oauth_access_token>'
22+
);
23+
```
24+
25+
## Pagination
26+
27+
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:
28+
29+
- `per_page`: Defines the number of results to return, with a maximum value of 100
30+
- `after_cursor`: When specified, returns the next page of results based on the current result's `pagination->end_cursor` value
31+
- `before_cursor`: When specified, returns the previous page of results based on the current result's `pagination->start_cursor` value
32+
33+
## Accounts
34+
35+
- Added: `get_account_colors()`
36+
- Added: `update_account_colors()`
37+
- Added: `get_creator_profile()`
38+
- Added: `get_email_stats()`
39+
- Added: `get_growth_stats()`
40+
41+
## Broadcasts
42+
43+
- Updated: `get_broadcasts()` supports pagination
44+
- Updated: `create_broadcast()`:
45+
- `email_layout_template` is now `email_template_id`. To fetch the ID of the account's email templates, refer to `get_email_templates()`
46+
- `preview_text` option added
47+
- `subscriber_filter` option added
48+
- Updated: `update_broadcast()`
49+
- `email_layout_template` is now `email_template_id`. To fetch the ID of the account's email templates, refer to `get_email_templates()`
50+
- `preview_text` option added
51+
- `subscriber_filter` option added
52+
- Changed: `destroy_broadcast()` is renamed to `delete_broadcast()`
53+
54+
## Custom Fields
55+
56+
- Added: `create_custom_fields()` to create multiple custom fields in a single request
57+
- Updated: `get_custom_fields()` supports pagination
58+
59+
## Subscribers
60+
61+
- 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.
62+
- Added: `create_subscribers()` to create multiple subscribers in a single request
63+
- Added: `get_subscribers()`
64+
- Changed: `unsubscribe()` is now `unsubscribe_by_email()`. Use `unsubscribe()` for unsubscribing by a subscriber ID
65+
- Updated: `get_subscriber_tags()` supports pagination
66+
67+
## Tags
68+
69+
- Added: `create_tags()` to create multiple tags in a single request
70+
- Updated: `get_tags()` supports pagination
71+
- Updated: `get_tag_subscriptions()`:
72+
- supports pagination
73+
- supports filtering by subscribers by dates, covering `created_after`, `created_before`, `tagged_after` and `tagged_before`
74+
- `sort_order` is no longer supported
75+
- Changed: `tag_subscriber()` is now `tag_subscriber_by_email()`. Use `tag_subscriber()` for tagging by subscriber ID
76+
77+
## Email Templates
78+
79+
- Added: `get_email_templates()`
80+
81+
## Forms
82+
83+
- Updated: `get_forms()`:
84+
- supports pagination
85+
- only returns active forms by default. Use the `status` parameter to filter by `active`, `archived`, `trashed` or `all`
86+
- Updated: `get_landing_pages()`:
87+
- supports pagination
88+
- only returns active landing pages by default. Use the `status` parameter to filter by `active`, `archived`, `trashed` or `all`
89+
- Updated: `get_form_subscriptions()`:
90+
- supports pagination
91+
- supports filtering by subscribers by dates, covering `created_after`, `created_before`, `added_after` and `added_before`
92+
- `sort_order` is no longer supported
93+
- 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
94+
95+
## Purchases
96+
97+
- Updated: `create_purchase()` now supports named parameters for purchase data, instead of an `$options` array
98+
- Changed: `list_purchases()` is now `get_purchases()`, with pagination support
99+
100+
## Segments
101+
102+
- Added: `get_segments()`
103+
104+
## Sequences
105+
106+
- 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
107+
- Updated: `get_sequences()` supports pagination
108+
- Updated: `get_sequence_subscriptions()`:
109+
- supports pagination
110+
- supports filtering by subscribers by dates, covering `created_after`, `created_before`, `added_after` and `added_before`
111+
- `sort_order` is no longer supported
112+
113+
## Webhooks
114+
115+
- Added: `get_webhooks()`
116+
- Changed: `destroy_webhook()` is now `delete_webhook()`
117+
118+
## Other
119+
120+
- Removed: `form_subscribe()` was previously deprecated. Use `add_subscriber_to_form()` or `add_subscriber_to_form_by_email()`
121+
- Removed: `add_tag()` was previously deprecated. Use `tag_subscriber()` or `tag_subscriber_by_email()`

‎README.md

+105-2
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,14 @@ The ConvertKit PHP SDK provides convinient access to the ConvertKit API from app
44

55
It includes a pre-defined set of methods for interacting with the API.
66

7-
## Requirements
7+
## Version Guidance
88

9-
PHP 7.4 and later.
9+
| SDK Version | API Version | API Authentication | PHP Version |
10+
|-------------|-------------|--------------------|--------------|
11+
| 1.x | v3 | API Key and Secret | 7.4+ |
12+
| 2.x | v4 | OAuth | 8.0+ |
13+
14+
Refer to [this guide](MIGRATION.md) for changes when upgrading to the v2 SDK.
1015

1116
## Composer
1217

@@ -34,6 +39,104 @@ If you use Composer, these dependencies should be handled automatically.
3439

3540
## Getting Started
3641

42+
### 2.x (v4 API, OAuth, PHP 8.0+)
43+
44+
First, register your OAuth application in the `OAuth Applications` section at https://app.convertkit.com/account_settings/advanced_settings.
45+
46+
Using the supplied Client ID and secret, redirect the user to ConvertKit to grant your application access to their ConvertKit account.
47+
48+
```php
49+
// Require the autoloader (if you're using a PHP framework, this may already be done for you).
50+
require_once 'vendor/autoload.php';
51+
52+
// Initialize the API class.
53+
$api = new \ConvertKit_API\ConvertKit_API(
54+
clientID: '<your_oauth_client_id>',
55+
clientSecret: '<your_oauth_client_secret>'
56+
);
57+
58+
// Redirect to begin the OAuth process.
59+
header('Location: '.$api->get_oauth_url('<your_redirect_uri>'));
60+
```
61+
62+
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:
63+
64+
`your-redirect-uri?code=<auth_code>`
65+
66+
At this point, your application needs to exchange the authorization code for an access token and refresh token.
67+
68+
```php
69+
$result = $api->get_access_token(
70+
authCode: '<auth_code>',
71+
redirectURI: '<your_redirect_uri>'
72+
);
73+
```
74+
75+
`$result` is an array comprising of:
76+
- `access_token`: The access token, used to make authenticated requests to the API
77+
- `refresh_token`: The refresh token, used to fetch a new access token once the current access token has expired
78+
- `created_at`: When the access token was created
79+
- `expires_in`: The number of seconds from `created_at` that the access token will expire
80+
81+
Once you have an access token, re-initialize the API class with it:
82+
83+
```php
84+
// Initialize the API class.
85+
$api = new \ConvertKit_API\ConvertKit_API(
86+
clientID: '<your_oauth_client_id>',
87+
clientSecret: '<your_oauth_client_secret>',
88+
accessToken: '<your_access_token>'
89+
);
90+
```
91+
92+
To refresh an access token:
93+
94+
```php
95+
$result = $api->refresh_token(
96+
refreshToken: '<your_refresh_token>',
97+
redirectURI: '<your_redirect_uri>'
98+
);
99+
```
100+
101+
`$result` is an array comprising of:
102+
- `access_token`: The access token, used to make authenticated requests to the API
103+
- `refresh_token`: The refresh token, used to fetch a new access token once the current access token has expired
104+
- `created_at`: When the access token was created
105+
- `expires_in`: The number of seconds from `created_at` that the access token will expire
106+
107+
Once you have refreshed the access token i.e. obtained a new access token, re-initialize the API class with it:
108+
109+
```php
110+
// Initialize the API class.
111+
$api = new \ConvertKit_API\ConvertKit_API(
112+
clientID: '<your_oauth_client_id>',
113+
clientSecret: '<your_oauth_client_secret>',
114+
accessToken: '<your_new_access_token>'
115+
);
116+
```
117+
118+
API requests may then be performed:
119+
120+
```php
121+
$result = $api->add_subscriber_to_form(12345, '[email protected]');
122+
```
123+
124+
To determine whether a new entity / relationship was created, or an existing entity / relationship updated, inspect the HTTP code of the last request:
125+
126+
```php
127+
$result = $api->add_subscriber_to_form(12345, '[email protected]');
128+
$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.
129+
```
130+
131+
The PSR-7 response can be fetched and further inspected, if required - for example, to check if a header exists:
132+
133+
```php
134+
$result = $api->add_subscriber_to_form(12345, '[email protected]');
135+
$api->getResponseInterface()->hasHeader('Content-Length'); // Check if the last API request included a `Content-Length` header
136+
```
137+
138+
### 1.x (v3 API, API Key and Secret, PHP 7.4+)
139+
37140
Get your ConvertKit API Key and API Secret [here](https://app.convertkit.com/account/edit) and set it somewhere in your application.
38141

39142
```php

‎phpcs.xml

+1-1
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@
7272
<!-- Permit slightly longer line lengths -->
7373
<rule ref="Generic.Files.LineLength">
7474
<properties>
75-
<property name="lineLimit" value="130"/>
75+
<property name="lineLimit" value="150"/>
7676
<property name="absoluteLineLimit" value="0"/>
7777
</properties>
7878
</rule>

‎phpstan.neon.dist

+1-6
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,4 @@ parameters:
66

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

‎phpstan.neon.example

+1-6
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,4 @@ parameters:
66

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

0 commit comments

Comments
 (0)