Skip to content

Commit 774d670

Browse files
n7studiosn7studios
authored
Merge pull request #44 from ConvertKit/tag-functions
Add Tag API functions
2 parents 9729e6d + 80d80b1 commit 774d670

File tree

4 files changed

+519
-7
lines changed

4 files changed

+519
-7
lines changed

‎.env.dist.testing‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ CONVERTKIT_API_LEGACY_FORM_URL="https://app.convertkit.com/landing_pages/470099"
33
CONVERTKIT_API_LANDING_PAGE_URL="https://cheerful-architect-3237.ck.page/cc5eb21744"
44
CONVERTKIT_API_LEGACY_LANDING_PAGE_URL="https://app.convertkit.com/landing_pages/470103"
55
CONVERTKIT_API_SEQUENCE_ID="1030824"
6+
CONVERTKIT_API_TAG_NAME="wordpress"
67
CONVERTKIT_API_TAG_ID="2744672"
78
CONVERTKIT_API_SUBSCRIBER_EMAIL="[email protected]"
89
CONVERTKIT_API_SUBSCRIBER_ID="1579118532"

‎.env.example‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ CONVERTKIT_API_LEGACY_FORM_URL="https://app.convertkit.com/landing_pages/470099"
77
CONVERTKIT_API_LANDING_PAGE_URL="https://cheerful-architect-3237.ck.page/cc5eb21744"
88
CONVERTKIT_API_LEGACY_LANDING_PAGE_URL="https://app.convertkit.com/landing_pages/470103"
99
CONVERTKIT_API_SEQUENCE_ID="1030824"
10+
CONVERTKIT_API_TAG_NAME="wordpress"
1011
CONVERTKIT_API_TAG_ID="2744672"
1112
CONVERTKIT_API_SUBSCRIBER_EMAIL="[email protected]"
1213
CONVERTKIT_API_SUBSCRIBER_ID="1579118532"

‎src/ConvertKit_API.php‎

Lines changed: 159 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -321,17 +321,101 @@ public function get_sequence_subscriptions(
321321
}
322322

323323
/**
324-
* Adds a tag to a subscriber
324+
* Gets all tags.
325+
*
326+
* @since 1.0.0
327+
*
328+
* @see https://developers.convertkit.com/#list-tags
329+
*
330+
* @return false|mixed
331+
*/
332+
public function get_tags()
333+
{
334+
return $this->get_resources('tags');
335+
}
336+
337+
/**
338+
* Creates a tag.
339+
*
340+
* @param string $tag Tag Name.
341+
*
342+
* @since 1.0.0
343+
*
344+
* @see https://developers.convertkit.com/#create-a-tag
345+
*
346+
* @return false|mixed
347+
*/
348+
public function create_tag(string $tag)
349+
{
350+
return $this->post(
351+
'tags',
352+
[
353+
'api_key' => $this->api_key,
354+
'tag' => ['name' => $tag],
355+
]
356+
);
357+
}
358+
359+
/**
360+
* Tags a subscriber with the given existing Tag.
361+
*
362+
* @param integer $tag_id Tag ID.
363+
* @param string $email Email Address.
364+
* @param string $first_name First Name.
365+
* @param array<string, string> $fields Custom Fields.
366+
*
367+
* @see https://developers.convertkit.com/#tag-a-subscriber
368+
*
369+
* @return false|mixed
370+
*/
371+
public function tag_subscriber(
372+
int $tag_id,
373+
string $email,
374+
string $first_name = '',
375+
array $fields = []
376+
) {
377+
// Build parameters.
378+
$options = [
379+
'api_secret' => $this->api_secret,
380+
'email' => $email,
381+
];
382+
383+
if (!empty($first_name)) {
384+
$options['first_name'] = $first_name;
385+
}
386+
if (!empty($fields)) {
387+
$options['fields'] = $fields;
388+
}
389+
390+
// Send request.
391+
return $this->post(
392+
sprintf('tags/%s/subscribe', $tag_id),
393+
$options
394+
);
395+
}
396+
397+
/**
398+
* Adds a tag to a subscriber.
325399
*
326400
* @param integer $tag Tag ID.
327401
* @param array<string, mixed> $options Array of user data.
328402
*
403+
* @deprecated 1.0.0 Use tag_subscriber($tag_id, $email, $first_name, $fields).
404+
*
405+
* @see https://developers.convertkit.com/#tag-a-subscriber
406+
*
329407
* @throws \InvalidArgumentException If the provided arguments are not of the expected type.
330408
*
331409
* @return false|object
332410
*/
333411
public function add_tag(int $tag, array $options)
334412
{
413+
// This function is deprecated in 1.0, as we prefer functions with structured arguments.
414+
trigger_error(
415+
'add_tag() is deprecated in 1.0. Use tag_subscribe($tag_id, $email, $first_name, $fields) instead.',
416+
E_USER_NOTICE
417+
);
418+
335419
if (!is_int($tag)) {
336420
throw new \InvalidArgumentException();
337421
}
@@ -348,6 +432,80 @@ public function add_tag(int $tag, array $options)
348432
);
349433
}
350434

435+
/**
436+
* Removes a tag from a subscriber.
437+
*
438+
* @param integer $tag_id Tag ID.
439+
* @param integer $subscriber_id Subscriber ID.
440+
*
441+
* @since 1.0.0
442+
*
443+
* @see https://developers.convertkit.com/#remove-tag-from-a-subscriber
444+
*
445+
* @return false|mixed
446+
*/
447+
public function remove_tag_from_subscriber(int $tag_id, int $subscriber_id)
448+
{
449+
return $this->delete(
450+
sprintf('subscribers/%s/tags/%s', $subscriber_id, $tag_id),
451+
[
452+
'api_secret' => $this->api_secret,
453+
]
454+
);
455+
}
456+
457+
/**
458+
* Removes a tag from a subscriber by email address.
459+
*
460+
* @param integer $tag_id Tag ID.
461+
* @param string $email Subscriber email address.
462+
*
463+
* @since 1.0.0
464+
*
465+
* @see https://developers.convertkit.com/#remove-tag-from-a-subscriber-by-email
466+
*
467+
* @return false|mixed
468+
*/
469+
public function remove_tag_from_subscriber_by_email(int $tag_id, string $email)
470+
{
471+
return $this->post(
472+
sprintf('tags/%s/unsubscribe', $tag_id),
473+
[
474+
'api_secret' => $this->api_secret,
475+
'email' => $email,
476+
]
477+
);
478+
}
479+
480+
/**
481+
* List subscriptions to a tag
482+
*
483+
* @param integer $tag_id Tag ID.
484+
* @param string $sort_order Sort Order (asc|desc).
485+
* @param string $subscriber_state Subscriber State (active,cancelled).
486+
* @param integer $page Page.
487+
*
488+
* @see https://developers.convertkit.com/#list-subscriptions-to-a-tag
489+
*
490+
* @return false|mixed
491+
*/
492+
public function get_tag_subscriptions(
493+
int $tag_id,
494+
string $sort_order = 'asc',
495+
string $subscriber_state = 'active',
496+
int $page = 1
497+
) {
498+
return $this->get(
499+
sprintf('tags/%s/subscriptions', $tag_id),
500+
[
501+
'api_secret' => $this->api_secret,
502+
'sort_order' => $sort_order,
503+
'subscriber_state' => $subscriber_state,
504+
'page' => $page,
505+
]
506+
);
507+
}
508+
351509
/**
352510
* Gets a resource index
353511
* Possible resources: forms, landing_pages, subscription_forms, tags

0 commit comments

Comments
 (0)