README

MAILCHIMP API 3.0 PHP
- 安装
- 实例化
- OAuth
- 构造请求
  - GET
  - POST
  - PATCH & PUT
  - DELETE
- 处理响应
- 回调
- 方法图表 (*不包括动词)
- Wiki - 查看更深入的文档

MAILCHIMP API 3.0 PHP

这是一个用于与 MailChimp API 3.0 交互的 PHP 库

此库假设您对 MailChimp 应用及其相关函数有基本了解。

安装

对于 Composer，运行

composer require jhut89/mailchimp3php

或者，您可以在项目的 composer.json 中添加一个 require 行，用于 jhut89/mailchimp3php 包。

然后运行 composer update 并使用以下命令将 composer 自动加载器添加到您的项目中

require "vendor/autoload.php";

然后您可以使用 use 语句引入 Mailchimp 类

use MailchimpAPI\Mailchimp;

实例化

$mailchimp = new Mailchimp('123abc123abc123abc123abc-us0');

要实例化，您需要一个 Mailchimp 类的新实例，其参数为您的 MailChimp 账户的 API 密钥。

OAuth

如果您使用 OAuth 来获取访问令牌，此库可以为您处理“握手”。

您必须首先将用户发送到您的应用的 authorize_uri。您可以通过调用静态的 Mailchimp::getAuthUrl() 来获取此 URL

$client_id =   '12345676543';
$redirect_url =  'https://www.some-domain.com/callback_file.php';

Mailchimp::getAuthUrl($client_id, $redirect_url);

可选地，如果您需要将状态信息随请求一起传递，以便回调响应可以正确路由，您可以包含一个状态参数

$client_id =   '12345676543';
$redirect_url =  'https://www.some-domain.com/callback_file.php';

// state information encoded into a string to be included in the URL, for example data encoded in a JWT token
$state = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'; 

Mailchimp::getAuthUrl($client_id, $redirect_url, $state);

从那里，用户将输入他们的用户名和密码以批准您的应用，并将带有 code 的重定向到您设置的 redirect_uri

有了这个 code，您现在可以从 MailChimp 获取访问令牌。为此，您需要像这样调用静态的 Mailchimp::oauthExchange() 方法

$code = 'abc123abc123abc123abc123';
$client_id =   '12345676543';
$client_secret =  '789xyz789xyz789xyz789xyz';
$redirect_url =  'https://www.some-domain.com/callback_file.php';

Mailchimp::oauthExchange($code, $client_id, $client_secret, $redirect_url);

如果握手成功，则此方法将返回一个包含您的 API 密钥的字符串，例如：123abc123abc123abc123abc123abc-us0。现在可以使用此 API 密钥来实例化您的 Mailchimp 类，就像我们上面所做的那样。

构造请求

一旦实例化了 Mailchimp 类，您就可以开始构造请求。构造请求是通过将方法“链接”到 $mailchimp 实例来完成的。在这种情况下，“链”通常以请求的 HTTP 动词结束。

GET

如何检索列表集合的示例

$mailchimp
    ->lists()
    ->get();

通过将您想要的实例的唯一标识符作为参数传递给适当的方法，可以检索实例。例如，如果我想从上面的例子中检索列表实例，我只需将 list_id 传递给 lists() 方法的唯一参数，就像这样

$mailchimp
    ->lists('1a2b3c4d')
    ->get();

链中每个位置的方法取决于前一个方法返回的内容。例如，如果我想从我的账户中检索列表的订阅者，我会这样做

$mailchimp
    ->lists('1a2b3c4d')
    ->members()
    ->get();

请注意，我向 lists() 方法提供了一个 list_id，因为没有其他方式可以从列表集合中检索订阅者列表。然而，上述请求只会从成员集合中返回10个订阅者实例。这是因为MailChimp的API使用分页（请参阅这里的文档），默认为count=10和offset=0。这个库允许你通过将它们作为参数传递给GET()方法来修改查询字符串参数。我们这样做是通过提供一个键值对数组，其中键是要提供/修改的查询参数，值是参数的值。例如，如果我想从我的列表中检索第二页的前100个订阅者，我可以这样做：

$mailchimp
    ->lists('1a2b3c4d')
    ->members()
    ->get([
        "count" => "100", 
        "offset" => "100"
    ]);

这相当于对以下内容进行GET请求：

Https://us0.api.mailchimp.com/3.0/lists/1a2b3c4d/members?count=100&offset=100

进一步来说，我们可以通过向members()方法提供members_hash（小写地址的md5散列）来检索单个列表成员。如下所示：

$mailchimp
    ->lists('1a2b3c4d')
    ->members('8bdbf060209f35b52087992a3cbdf4d7')
    ->get();

或者，你可以提供联系人的电子邮件地址作为字符串，而不是提供md5散列作为members()函数的标识符，这个库会为你进行散列。如下所示：

$mailchimp
    ->lists('1a2b3c4d')
    ->members('example@domain.com')
    ->get();

你可以在这里深入了解GET请求：https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Get-Requests

POST

虽然能够从您的账户中检索数据是很好的，但我们还需要能够发布新数据。这可以通过在链的末尾调用POST()方法来实现。例如，将地址订阅到列表看起来像这样：

$post_params = [
    'email_address'=>'example@domain.com', 
    'status'=>'subscribed'
];

$mailchimp
    ->lists('1a2b3c4d')
    ->members()
    ->post($post_params);

在这种情况下，我不会向members()提供标识符，因为我想要向其集合中发布。请注意，发布数据是一个键值对数组，代表我要传递给MailChimp API的参数。请确保您提供了要发布到的端点所需的所有必填字段。请检查MailChimp的文档以了解所需的参数。非必填参数可以添加到发布数据中，MailChimp将忽略任何不可用的参数。以下是一个向列表添加订阅者并添加一些非必填参数的示例：

$merge_values = [
    "FNAME" => "John",
    "LNAME" => "Doe"
];

$post_params = [
    "email_address" => "example@domain.com", 
    "status" => "subscribed", 
    "email_type" => "html", 
    "merge_fields" => $merge_values
]

$mailchimp
    ->lists('1a2b3c4d')
    ->members()
    ->post($post_params);

你可以在这里深入了解POST请求：https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Post-Requests

PATCH & PUT

这个库以与POST请求类似的方式处理PUT和PATCH请求。这意味着PUT()和PATCH()都接受一个键值对数组，代表你希望修改/提供给MailChimp的数据。例如，如果我要修复上面订阅的订阅者，以有新的名字，这将如下所示。

$mailchimp
    ->lists('1a2b3c4d')
    ->members('a1167f5be2df7113beb69c95ebcdb2fd')
    ->patch([
        "merge_fields" => ["FNAME" => "Jane"]
    ]);

你可以在这里深入了解PATCH和PUT请求：https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Patch-&-Put-Requests

DELETE

使用DELETE()方法从MailChimp中删除记录，其构建方式类似于GET请求。如果我想删除上述订阅者，我会这样做：

$mailchimp
    ->lists('1a2b3c4d')
    ->members('a1167f5be2df7113beb69c95ebcdb2fd')
    ->delete();

你可以在这里深入了解DELETE请求：https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Delete-Requests

处理响应

以HTTP动词命名的名称方法，如get()、post()、patch()、put()或delete()，会向MailChimp的A.P.I.发送网络请求。如果请求成功，这些方法将返回一个MailchimpResponse实例。建议您熟悉这个类，因为其中包含许多针对响应不同部分的修饰符和获取器。

我们可以使用多个获取器来与我们的MailchimpResponse实例交互。一些常用的获取器包括

$response->deserialize(); // returns a deserialized (to php object) resource returned by API
$response->getHttpCode(); // returns an integer representation of the HTTP response code
$response->getHeaders(); // returns response headers as an array of key => value pairs
$response->getBody(); // return the raw text body of the response

例如，如果我有一个API密钥，但想获取其账户相关的联系邮箱

$mailchimp = new Mailchimp('123abc123abc123abc123abc-us0');
$account = $mailchimp
    ->account()
    ->get()
    
$contact_email = $account
    ->deserialize()
    ->email
    
print $contact_email; // outputs something like "example@domain.com"

您可以在这里深入了解如何处理响应：https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Handling-A-Response

方法图表（*不包括动词）

  mailchimp()                       
  |                                 
  |----account()                    
  |                                 
  |----apps()                       
  |                                 
  |----automations()                
  |    |                            
  |    |----removedSubscribers()    
  |    |----emails()                
  |         |                       
  |         |---queue()*             
  |         |---pauseAll()*         
  |         |---startAll()*        
  |                                 
  |----batches()                    
  |                                 
  |----batchWebhooks()              
  |                                 
  |----campaignFolders()            
  |                                 
  |----campaigns()                  
  |    |                            
  |    |----cancel()*                
  |    |----pause()*                 
  |    |----replicate()*             
  |    |----resume()*                
  |    |----scedule()*              
  |    |----send()*                  
  |    |----test()*                  
  |    |----unschedule()*            
  |    |----checklist()             
  |    |----feedback()              
  |    |----content()
  |
  |----connectedSites()
  |    |
  |    |----verifyScriptInstallation()*               
  |                                 
  |----conversations()              
  |    |                            
  |    |----messages()              
  |                                 
  |----ecommStores()                
  |    |                            
  |    |----customers()             
  |    |----products()              
  |    |    |                       
  |    |    |----variants()         
  |    |    |----images()           
  |    |     
  |    |----promoRules()
  |    |    |
  |    |    |----promoCodes()
  |    |                   
  |    |----orders()                
  |    |    |                       
  |    |    |----lines()            
  |    |                            
  |    |----carts()                 
  |         |                       
  |         |----lines()
  |
  |----facebookAds()            
  |                                 
  |----fileManagerFiles()           
  |                                 
  |----fileManagerFolders()
  |
  |----googleAds()
  |
  |----landingPages()
  |    |
  |    |----publish()*
  |    |----unpublish()*
  |    |----content()         
  |                                 
  |----lists()                      
  |    |                            
  |    |----batchSubscribe()*             
  |    |----webhooks()              
  |    |----signupForms()           
  |    |----mergeFields()           
  |    |----growthHistory()         
  |    |----clients()               
  |    |----activity()              
  |    |----abuseReports()          
  |    |----segments()              
  |    |    |                       
  |    |    |----batch()*            
  |    |    |----members()          
  |    |                            
  |    |----members()               
  |    |    |                       
  |    |    |---notes()             
  |    |    |---goals()             
  |    |    |---activity()
  |    |    |---tags()          
  |    |                            
  |    |----interestCategories()    
  |         |                       
  |         |----interests()        
  |    
  |----ping()
  |                             
  |----reports()                    
  |    |                            
  |    |----unsubscribes()          
  |    |----subReports()            
  |    |----sentTo()                
  |    |----locations()             
  |    |----emailActivity() 
  |    |----googleAnalytics()
  |    |----openDetails()        
  |    |----eepurl()                
  |    |----domainPerformance()     
  |    |----advice()                
  |    |----abuse()                 
  |    |----clickReports()          
  |         |                       
  |         |----members()          
  |                                 
  |----searchCampaigns()            
  |                                 
  |----searchMembers()              
  |                                 
  |----templateFolders()            
  |                                 
  |----templates()                  
  |    |                            
  |    |----defaultContent()        
  |                             
  |----verifiedDomains()
       |
       |----verify()

*请参阅MailChimp的API文档，了解哪些动词适用于哪些场景。

**带有*标记的方法会进行网络请求

**请关注更新，欢迎Fork或Pull Request。Wiki中有更多关于贡献的信息。

jhut89 / mailchimp3php

维护者

详细信息