告别繁琐API对接：如何使用Composer轻松集成HelpScoutAPI

<code class="bash">composer require helpscout/api "^3.0"</code>

<code class="php">require_once 'vendor/autoload.php';</code>

<code class="php">use HelpScout\Api\ApiClientFactory;
use HelpScout\Api\Http\Authenticator;

// 创建 API 客户端实例
$client = ApiClientFactory::createClient();

// 方式一：使用客户端凭证 (推荐，客户端会自动按需获取和刷新令牌)
$appId = '你的 Help Scout App ID';
$appSecret = '你的 Help Scout App Secret';
$client->useClientCredentials($appId, $appSecret);

// 方式二：直接设置访问令牌 (如果你已经有了令牌)
// $client->setAccessToken('你的访问令牌');

// 方式三：使用刷新令牌获取新的访问令牌
// $refreshToken = '你的刷新令牌';
// $client->useRefreshToken($appId, $appSecret, $refreshToken);

// 自动刷新过期令牌的例子：提供一个回调函数来持久化新令牌
$clientWithRefresh = ApiClientFactory::createClient([], function (Authenticator $authenticator) {
    // 这里可以将 $authenticator->accessToken() 和 $authenticator->refreshToken() 存储起来
    echo '新的访问令牌: ' . $authenticator->accessToken() . PHP_EOL;
});
$clientWithRefresh->useClientCredentials($appId, $appSecret); // 触发令牌获取</code>

<code class="php">use HelpScout\Api\Customers\Customer;
use HelpScout\Api\Customers\CustomerFilters;
use HelpScout\Api\Customers\Entry\Email;
use HelpScout\Api\Exception\ValidationErrorException;

// 获取单个客户
$customerId = 12345; // 假设的客户ID
$customer = $client->customers()->get($customerId);
echo "客户姓名: " . $customer->getFirstName() . " " . $customer->getLastName() . PHP_EOL;

// 列表查询客户，并可添加过滤条件
$filter = (new CustomerFilters())
    ->byFirstName('张')
    ->byLastName('三');
$customers = $client->customers()->list($filter);
foreach ($customers as $cust) {
    echo "找到客户: " . $cust->getFirstName() . " " . $cust->getLastName() . PHP_EOL;
}

// 创建一个新客户
$newCustomer = new Customer();
$newCustomer->setFirstName('李');
$newCustomer->setLastName('四');
$email = new Email();
$email->setValue('li.si@example.com');
$email->setType('work');
$newCustomer->addEmail($email);

try {
    $newCustomerId = $client->customers()->create($newCustomer);
    echo "新客户创建成功，ID: " . $newCustomerId . PHP_EOL;
} catch (ValidationErrorException $e) {
    echo "创建客户失败: " . print_r($e->getError()->getErrors(), true) . PHP_EOL;
}

// 更新客户信息
$customerToUpdate = $client->customers()->get($newCustomerId); // 先获取要更新的客户
$customerToUpdate->setFirstName('李明');
$client->customers()->update($customerToUpdate);
echo "客户信息更新成功！" . PHP_EOL;</code>

<code class="php">use HelpScout\Api\Conversations\Conversation;
use HelpScout\Api\Conversations\Threads\CustomerThread;
use HelpScout\Api\Customers\Customer;
use HelpScout\Api\Entity\Collection;

// 获取单个会话，并预加载相关信息
$conversationId = 67890; // 假设的会话ID
$request = (new \HelpScout\Api\Conversations\ConversationRequest())
    ->withMailbox()
    ->withPrimaryCustomer()
    ->withThreads();
$conversation = $client->conversations()->get($conversationId, $request);
echo "会话主题: " . $conversation->getSubject() . PHP_EOL;
echo "会话邮箱: " . $conversation->getMailbox()->getName() . PHP_EOL;

// 创建一个新会话 (模拟客户发送邮件)
$customerForNewConvo = new Customer();
$customerForNewConvo->addEmail('new.customer@example.com');

$thread = new CustomerThread();
$thread->setCustomer($customerForNewConvo);
$thread->setText('你好，我对你们的产品很感兴趣，能提供更多信息吗？');

$newConversation = new Conversation();
$newConversation->setSubject('新客户咨询：产品信息');
$newConversation->setStatus('active');
$newConversation->setType('email');
$newConversation->setMailboxId(123456); // 你的邮箱ID
$newConversation->setCustomer($customerForNewConvo);
$newConversation->setThreads(new Collection([$thread]));

try {
    $createdConvoId = $client->conversations()->create($newConversation);
    echo "新会话创建成功，ID: " . $createdConvoId . PHP_EOL;
} catch (ValidationErrorException $e) {
    echo "创建会话失败: " . print_r($e->getError()->getErrors(), true) . PHP_EOL;
}</code>

<code class="php">use HelpScout\Api\Exception\AuthenticationException;
use HelpScout\Api\Exception\ValidationErrorException;
use HelpScout\Api\Http\Client\Exception\RequestException;

try {
    // 尝试执行一个可能出错的 API 操作
    // 例如，尝试用无效的 ID 获取客户
    $client->customers()->get(999999999);
} catch (AuthenticationException $e) {
    echo "认证失败：请检查 App ID 和 Secret。" . PHP_EOL;
} catch (ValidationErrorException $e) {
    echo "请求验证失败：";
    var_dump($e->getError()->getErrors());
} catch (RequestException $e) {
    // 其他 HTTP 错误，如网络问题、服务器错误等
    echo "API 请求发生错误: " . $e->getMessage() . PHP_EOL;
} catch (\Exception $e) {
    // 捕获所有其他未知异常
    echo "发生未知错误: " . $e->getMessage() . PHP_EOL;
}</code>

<code class="php">use HelpScout\Api\Entity\PagedCollection;

/** @var PagedCollection $users */
$users = $client->users()->list();

echo "总页数: " . $users->getTotalPageCount() . PHP_EOL;
echo "当前页码: " . $users->getPageNumber() . PHP_EOL;

// 遍历当前页的用户
foreach ($users as $user) {
    echo "用户姓名: " . $user->getFirstName() . " " . $user->getLastName() . PHP_EOL;
}

// 加载下一页
if ($users->hasNextPage()) {
    $nextUsers = $users->getNextPage();
    echo "加载了下一页，用户数量: " . count($nextUsers) . PHP_EOL;
}

// 你也可以直接获取特定页
$page3Users = $users->getPage(3);
echo "第3页用户数量: " . count($page3Users) . PHP_EOL;</code>