Skip to content

Commit 4ed298f

Browse files
n7studiosn7studios
authored
Merge pull request #118 from Kit/add-subscribers-filter
Add `filter_subscribers` method
2 parents efe6b32 + 22e59f1 commit 4ed298f

7 files changed

Lines changed: 369 additions & 22 deletions

File tree

‎.env.dist.testing‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
CONVERTKIT_API_BROADCAST_ID="8697158"
2+
CONVERTKIT_API_CUSTOM_FIELD_ID="264073"
23
CONVERTKIT_API_FORM_ID="2765139"
34
CONVERTKIT_API_FORM_ID_2="2780977"
45
CONVERTKIT_API_LEGACY_FORM_URL="https://app.convertkit.com/landing_pages/470099"

‎.env.example‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ CONVERTKIT_OAUTH_CLIENT_ID=
1111
CONVERTKIT_OAUTH_CLIENT_SECRET=
1212
CONVERTKIT_OAUTH_REDIRECT_URI="https://convertkit-github.local/wp-admin/options-general.php?page=_wp_convertkit_settings"
1313
CONVERTKIT_API_BROADCAST_ID="8697158"
14+
CONVERTKIT_API_CUSTOM_FIELD_ID="264073"
1415
CONVERTKIT_API_FORM_ID="2765139"
1516
CONVERTKIT_API_FORM_ID_2="2780977"
1617
CONVERTKIT_API_LEGACY_FORM_URL="https://app.convertkit.com/landing_pages/470099"

‎phpcs.xml‎

Lines changed: 1 addition & 1 deletion
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="150"/>
75+
<property name="lineLimit" value="160"/>
7676
<property name="absoluteLineLimit" value="0"/>
7777
</properties>
7878
</rule>

‎src/ConvertKit_API.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -348,13 +348,13 @@ public function get_resource(string $url)
348348
/**
349349
* Performs an API request using Guzzle.
350350
*
351-
* @param string $endpoint API Endpoint.
352-
* @param string $method Request method.
353-
* @param array<string, bool|integer|float|string|null|array<int|string, float|integer|string|array<string|string>>> $args Request arguments.
351+
* @param string $endpoint API Endpoint.
352+
* @param string $method Request method.
353+
* @param array<string, bool|integer|float|string|null|array<int|string, bool|integer|float|string|array<mixed>>> $args Request arguments.
354354
*
355355
* @throws \Exception If JSON encoding arguments failed.
356356
*
357-
* @return mixed|object
357+
* @return false|mixed
358358
*/
359359
public function request(string $endpoint, string $method, array $args = [])
360360
{

‎src/ConvertKit_API_Traits.php‎

Lines changed: 120 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -945,6 +945,74 @@ public function create_subscribers(array $subscribers, string $callback_url = ''
945945
);
946946
}
947947

948+
/**
949+
* Filter subscribers based on engagement.
950+
*
951+
* @param array<int, array<string, mixed>> $all Array of filter conditions where ALL must be met (AND logic). Each condition can have.
952+
* - 'type' (string).
953+
* - 'count_greater_than' (int|null).
954+
* - 'count_less_than' (int|null).
955+
* - 'after' (\DateTime|null).
956+
* - 'before' (\DateTime|null).
957+
* - 'any' (array<int|string, mixed>|null).
958+
* @param boolean $include_total_count To include the total count of records in the response, use true.
959+
* @param string $after_cursor Return results after the given pagination cursor.
960+
* @param string $before_cursor Return results before the given pagination cursor.
961+
* @param integer $per_page Number of results to return.
962+
*
963+
* @since 2.4.0
964+
*
965+
* @see https://developers.kit.com/api-reference/subscribers/filter-subscribers-based-on-engagement
966+
*
967+
* @return mixed
968+
*/
969+
public function filter_subscribers(
970+
array $all = [],
971+
bool $include_total_count = false,
972+
string $after_cursor = '',
973+
string $before_cursor = '',
974+
int $per_page = 100
975+
) {
976+
$options = [];
977+
978+
foreach ($all as $condition) {
979+
$option = [];
980+
981+
if (array_key_exists('count_greater_than', $condition) && $condition['count_greater_than'] !== null) {
982+
$option['count_greater_than'] = $condition['count_greater_than'];
983+
}
984+
985+
if (array_key_exists('count_less_than', $condition) && $condition['count_less_than'] !== null) {
986+
$option['count_less_than'] = $condition['count_less_than'];
987+
}
988+
989+
if (array_key_exists('after', $condition) && $condition['after'] instanceof \DateTime) {
990+
$option['after'] = $condition['after']->format('Y-m-d');
991+
}
992+
993+
if (array_key_exists('before', $condition) && $condition['before'] instanceof \DateTime) {
994+
$option['before'] = $condition['before']->format('Y-m-d');
995+
}
996+
997+
if (array_key_exists('any', $condition) && !empty($condition['any'])) {
998+
$option['any'] = (array) $condition['any'];
999+
}
1000+
1001+
$options[] = $option;
1002+
}//end foreach
1003+
1004+
return $this->post(
1005+
'subscribers/filter',
1006+
$this->build_total_count_and_pagination_params(
1007+
['all' => $options],
1008+
$include_total_count,
1009+
$after_cursor,
1010+
$before_cursor,
1011+
$per_page
1012+
)
1013+
);
1014+
}
1015+
9481016
/**
9491017
* Get the ConvertKit subscriber ID associated with email address if it exists.
9501018
* Return false if subscriber not found.
@@ -1468,6 +1536,8 @@ public function create_webhook(string $url, string $event, string $parameter = '
14681536
case 'subscriber.subscriber_bounce':
14691537
case 'subscriber.subscriber_complain':
14701538
case 'purchase.purchase_create':
1539+
case 'custom_field.field_created':
1540+
case 'custom_field.field_deleted':
14711541
$eventData = ['name' => $event];
14721542
break;
14731543

@@ -1508,6 +1578,13 @@ public function create_webhook(string $url, string $event, string $parameter = '
15081578
];
15091579
break;
15101580

1581+
case 'custom_field.field_value_updated':
1582+
$eventData = [
1583+
'name' => $event,
1584+
'custom_field_id' => $parameter,
1585+
];
1586+
break;
1587+
15111588
default:
15121589
throw new \InvalidArgumentException(sprintf('The event %s is not supported', $event));
15131590
}//end switch
@@ -1617,6 +1694,36 @@ public function create_custom_fields(array $labels, string $callback_url = '')
16171694
);
16181695
}
16191696

1697+
/**
1698+
* Bulk update subscriber custom field values
1699+
*
1700+
* @param array<array<string,string|integer>> $custom_field_values Array of custom field values to update.
1701+
* - 'subscriber_id' (int) Subscriber ID.
1702+
* - 'subscriber_custom_field_id' (int) Custom Field ID.
1703+
* - 'value' (string|integer) Value to update.
1704+
* @param string $callback_url URL to notify for large batch size when async processing complete.
1705+
*
1706+
* @since 2.4.0
1707+
*
1708+
* @see https://developers.kit.com/api-reference/custom-fields/bulk-update-subscriber-custom-field-values
1709+
*
1710+
* @return mixed|object
1711+
*/
1712+
public function update_subscriber_custom_field_values(array $custom_field_values, string $callback_url = '')
1713+
{
1714+
// Build parameters.
1715+
$options = ['custom_field_values' => $custom_field_values];
1716+
if (!empty($callback_url)) {
1717+
$options['callback_url'] = $callback_url;
1718+
}
1719+
1720+
// Send request.
1721+
return $this->post(
1722+
'bulk/custom_fields/subscribers',
1723+
$options
1724+
);
1725+
}
1726+
16201727
/**
16211728
* Update a custom field.
16221729
*
@@ -1854,15 +1961,15 @@ public function strip_html_head_body_tags(string $markup)
18541961
/**
18551962
* Adds total count and pagination parameters to the given array of existing API parameters.
18561963
*
1857-
* @param array<string, string|integer|bool> $params API parameters.
1858-
* @param boolean $include_total_count Return total count of records.
1859-
* @param string $after_cursor Return results after the given pagination cursor.
1860-
* @param string $before_cursor Return results before the given pagination cursor.
1861-
* @param integer $per_page Number of results to return.
1964+
* @param array<string, string|integer|boolean|list<array<string, mixed>>> $params API parameters.
1965+
* @param boolean $include_total_count Return total count of records.
1966+
* @param string $after_cursor Return results after the given pagination cursor.
1967+
* @param string $before_cursor Return results before the given pagination cursor.
1968+
* @param integer $per_page Number of results to return.
18621969
*
18631970
* @since 2.0.0
18641971
*
1865-
* @return array<string, string|integer|bool>
1972+
* @return array<string, string|int|bool|list<array<string, mixed>>>
18661973
*/
18671974
private function build_total_count_and_pagination_params(
18681975
array $params = [],
@@ -1888,8 +1995,8 @@ private function build_total_count_and_pagination_params(
18881995
/**
18891996
* Performs a GET request to the API.
18901997
*
1891-
* @param string $endpoint API Endpoint.
1892-
* @param array<string, int|string|boolean|array<string, int|string>|string> $args Request arguments.
1998+
* @param string $endpoint API Endpoint.
1999+
* @param array<string, int|string|boolean|array<string, int|string>|list<array<string, mixed>>> $args Request arguments.
18932000
*
18942001
* @return false|mixed
18952002
*/
@@ -1901,8 +2008,8 @@ public function get(string $endpoint, array $args = [])
19012008
/**
19022009
* Performs a POST request to the API.
19032010
*
1904-
* @param string $endpoint API Endpoint.
1905-
* @param array<string, bool|integer|float|string|null|array<int|string, float|integer|string|array<string|string>>> $args Request arguments.
2011+
* @param string $endpoint API Endpoint.
2012+
* @param array<string, bool|integer|float|string|null|array<int|string, array<string|mixed>|boolean|integer|float|string>> $args Request arguments.
19062013
*
19072014
* @return false|mixed
19082015
*/
@@ -1940,9 +2047,9 @@ public function delete(string $endpoint, array $args = [])
19402047
/**
19412048
* Performs an API request.
19422049
*
1943-
* @param string $endpoint API Endpoint.
1944-
* @param string $method Request method.
1945-
* @param array<string, bool|integer|float|string|null|array<int|string, float|integer|string|array<string|string>>> $args Request arguments.
2050+
* @param string $endpoint API Endpoint.
2051+
* @param string $method Request method.
2052+
* @param array<string, bool|integer|float|string|null|array<int|string, bool|integer|float|string|array<string, mixed>>> $args Request arguments.
19462053
*
19472054
* @throws \Exception If JSON encoding arguments failed.
19482055
*

‎tests/ConvertKitAPIKeyTest.php‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -475,6 +475,33 @@ public function testCreateCustomFields()
475475
$result = $this->api->create_custom_fields($labels);
476476
}
477477

478+
/**
479+
* Test that update_subscriber_custom_field_values() throws a ClientException
480+
* as this is only supported using OAuth.
481+
*
482+
* @since 2.4.0
483+
*
484+
* @return void
485+
*/
486+
public function testUpdateSubscriberCustomFieldValues()
487+
{
488+
$this->expectException(ClientException::class);
489+
$result = $this->api->update_subscriber_custom_field_values(
490+
[
491+
[
492+
'subscriber_id' => 1,
493+
'subscriber_custom_field_id' => (int) $_ENV['CONVERTKIT_API_CUSTOM_FIELD_ID'],
494+
'value' => '100',
495+
],
496+
[
497+
'subscriber_id' => 2,
498+
'subscriber_custom_field_id' => (int) $_ENV['CONVERTKIT_API_CUSTOM_FIELD_ID'],
499+
'value' => '200',
500+
],
501+
]
502+
);
503+
}
504+
478505
/**
479506
* Test that get_purchases() throws a ClientException
480507
* as this is only supported using OAuth.

0 commit comments

Comments
 (0)