README

我找不到一个适合的简单PHP库来使用MailChimp v3 API，因此决定自己创建一个。
目前它对 campaigns（包括一些 actions）、lists 和相应的 members 提供了基本支持。目前未包含测试，所以如果您遇到任何意外结果，请创建一个问题。

安装

您可以通过编辑（或创建）您的 composer.json 来安装此库。

{
	"require": {
		"faimmedia/mailchimp-v3-api": "*"
	}
}

然后运行 composer update 或 composer install。

用法

在 example 文件夹中还有一些其他示例。所有方法都可以在下文中找到。

以下所有示例都需要使用您的API密钥初始化MailChimp类。API密钥是一个32位长度的哈希，后跟您的MailChimp数据中心位置，由连字符分隔。您可以在以下位置获取API密钥： https://us14.admin.mailchimp.com/account/api/。

$apiKey = '02699f222d95d4dfc53b9f7960b2fa6e-us1';

$mailchimp = new FaimMedia\MailChimp($apiKey);

有关所有API端点、所需和允许的字段，请参阅MailChimp API文档页面： https://developer.mailchimp.com/documentation/mailchimp/reference/overview/。

活动

创建新的活动

$campaign = $mailchimp->campaigns()->create([
	'settings' => [
		'subject_line' => 'My newsletter',
		'from_name'    => 'My company',
		'reply_to'     => 'newsletter@mycompany.com',
	],
	'type'     => 'regular',
]);

获取所有现有活动

$campaigns = $mailchimp->campaigns()->getAll();

通过ID获取活动

$campaign = $mailchimp->campaigns()->getById($campaignId);
// or
$campaign = $mailchimp->campaigns($campaignId);

活动内容

设置活动的内容

$campaign->setContentItem([
	'html' => 'HTML content of my campaign',
	'text' => 'Text content of my campaign'
]);

获取活动的内容

$content = $campaign->getContentItem();
echo $content->getHtml();
echo $content->getText();

活动操作

发送活动

$campaign->actions()->send();

为活动发送测试邮件

$campaign->actions()->test();

安排活动

安排方法只接受一个 DateTime 对象作为第一个参数。

$datetime = new \DateTime('2018-02-01 01:00:00');

$campaign->actions()->schedule($datetime);

取消安排活动

$campaign->actions->unschedule();

列表

创建新的列表

$list = $mailchimp->lists()->create([
	'name'     => 'Test newsletter list',
	'contact'  => [
		'company'  => 'FaimMedia.nl',
		'address1' => 'PO Box 1540',
		'city'     => 'NIJMEGEN',
		'state'    => 'GL',
		'zip'      => '6501 BM',
		'country'  => 'NL',
	],
	'permission_reminder' => 'You signed up for updates on our website',
	'campaign_defaults'   => [
		'from_name'    => 'FaimMedia.nl',
		'from_email'   => 'john.doe@repo.github.com',
		'subject'      => 'Newsletter',
		'language'     => 'NL',
	],
	'email_type_option' => false,
]);

返回值： ListItem 对象

获取所有现有列表

$lists = $mailchimp->lists()->getAll();

返回值： Lists 对象

通过ID获取列表

$list = $mailchimp->lists()->getById($listId);
// or
$list = $mailchimp->campaigns($listId);

返回值： ListItem 对象

列表成员

此类及其方法可以用于订阅或取消订阅列表成员。当添加成员或更新现有成员的订阅状态时，不会检查成员是否存在。如果已经存在，将覆盖提供的数据，如果不存在，将使用提供的订阅状态创建新成员。

添加一个列表成员（订阅者）

如果希望将单个订阅者添加到列表，可以使用 add 方法。如果希望一次将多个成员添加到列表，建议使用 multi 方法而不是 add 方法。与 add 方法为每个电子邮件地址发起新的请求不同，multi 可以一次发送一批发送电子邮件地址。

$member = $list->members()->add('johndoe@repo.github.com');

返回值： ListMemberItem 对象

如果希望包含其他字段，可以指定一个数组作为第一个参数。

$member = $list->members()->add([
	'email_address' => 'john.doe@repo.github.com',
	'merge_fields'  => [
		'FNAME' => 'John',
		'LNAME' => 'Doe',
	],
]);

返回值： ListMemberItem 对象

订阅多个列表成员

如果希望将多个成员添加到列表，可以使用 multi 方法。

$members = $list->members()->multi([
	'john.doe@repo.github.com',
	'jane.doe@repo.githib.com',
]);

此方法还提供了一种包含多个字段的方式，在这种情况下，可以将电子邮件地址指定为数组键。

$members = $list->members()->multi([
	'john.doe@repo.github.com' => [
		'merge_fields' => [
			'FNAME' => 'John',
			'LNAME' => 'Doe',
		],
	],
	'jane.doe@repo.github.com' => [
		'merge_fields' => [
			'FNAME' => 'Jane',
			'LNAME' => 'Doe',
		],
	],
]);

返回值： ListMembers 对象

获取列表成员

$member = $list->members()->getByEmail('john.doe@repo.github.com');

返回值： ListMemberItem 对象

更改列表成员的状态

此方法更改列表成员状态并立即保存。

$member->setStatus('unsubscribed');

返回值： ListMemberItem 对象

项目

获取属性

所有返回 AbstractItem 实例（CampaignItem、ListItem、ListMemberItem）都可以轻松地返回属性。所有属性都可以通过调用驼峰式字段前缀的 get 方法来访问。例如，如果您想获取 email_address 字段，可以使用 getEmailAddress 方法。

foreach($members as $member) {
	echo $member->getId();
	echo $member->getEmailAddress();
	echo $member->getMergeFields()->getFNAME();
	echo $member->getMergeFields()->getLNAME();

// or

	echo $member->id;
	echo $member->emailAddress;
	echo $member->mergeFields->FNAME;
	echo $member->mergeFields->LNAME;
}

如果值是数组，可以将方法的第一参数传递以获取该数组的键。

$member->getMergeFields('FNAME');

如果您想通过其 snakecase 键获取属性，可以使用 get 方法。

$member->get('id');
$member->get('email_address');
$member->get('merge_fields')->get('FNAME');
$member->get('merge_fields')->get('LNAME');

为了更轻松地获取订阅者的名称，有几个内置方法。

$member->getFirstName();
// alias of $member->getMergeFields()->getFNAME();

$member->getLastName();
// alias of $member->getMergeFields()->getLNAME();

获取所有属性

使用 toArray 方法，获取所有属性的数组。

$campaign->toArray();
$member->toArray();
$list->toArray();

删除项

您可以使用 delete 方法删除项。此方法在成功时返回 true，或在失败时抛出 Exception。处于 发送 状态的活动无法被删除。此外，与活动相关联的列表也无法被删除，在这种情况下，您需要先删除活动。

$list->delete();

$campaign->delete();

订阅成员可以被删除，但根据 MailChimp API 文档，这不推荐。更好的做法是更新当前成员并将其 状态 更改为 未订阅。

$member->delete();

// better to unsubscribe

$member->setStatus('unsubscribed');

更新项

首先获取您想要更新的项。

// campaigns
$campaign = $mailchimp->campaigns()->getById();

// lists
$list = $mailchimp->lists()->getById('ag43fe');

// members
$list->members()->getByEmail('john.doe@repo.github.com');

更新需要更改的字段。如果您使用重载属性（$campaign->type = 'html'），它期望一个驼峰式字段，而 set 方法期望常规蛇形字段。

// campaigns
	$campaign->type = 'plaintext';
	// or
	$campaign->set('type', 'plaintext');
	// or
	$campaign->set([
		'settings' => [
			'subject_line' => 'New subject line',
			'title'        => 'Updated campaign title',
		]
	]);

// lists
	$list->name = 'Updated list name';
	// or
	$list->set('name', 'Updated list name');
	// or
	$list->set([
		'name'       => 'Updated list name',
		'visibility' => 'prv',
	]);

// members
	$member->status = 'cleaned';
	// or
	$member->set('status', 'cleaned');
	// or
	$member->set([
		'status'       => 'cleaned',
		'merge_fields' => [
			'FNAME' => 'Test',
		],
	]);

请注意，以这种方式修改多维属性将不起作用，例如

$campaign->settings->subjectLine = 'Updated campaign title';

您需要将数组提供给第一个属性。

$campaign->settings = [
	'subject_line' => 'Updated campaign subject line',
];

新数组将与旧数组合并，因此如果您省略了某个字段（在此示例中，为 title 字段），则将保留原始的 title。

如果您不想这样做，可以向 set 方法传递一个额外的参数。这样，数组将不会被合并，而是被覆盖。

$campaign->set('settings', [
	'subject_line' => 'Updated campaign subject line',
], false);

保存项

$campaign->save();

$list->save();

$member->save();

方法

将很快提供...
目前请参阅所有示例，它们包含了大多数方法。

异常

所有异常都是从 MailChimpException 扩展的。

ItemException

当找不到项时抛出。

SaveException

在保存项时发生错误时抛出。

RequestException

当 MailChimp API 请求出现问题（可能是请求本身失败或 MailChimp API 返回意外响应）时抛出。