README

一个正在开发的非官方库，用于辅助与Text Marketer API的交互。

需求

PHP 7.3 或更高版本
ext-mbstring
ext-dom

Composer

composer require nessworthy\textmarketer

示例用法

设置
创建并发送短信
- 安排短信
- 删除已安排的短信
处理和转移余额
- 获取当前余额
- 通过账户ID或凭据转移余额
关键词可用性
群组管理
投递报告
账户管理
异常和错误处理

设置

$apiCredentials = new \Nessworthy\TextMarketer\Authentication\Simple('api_username', 'api_password');
$httpClient = new \GuzzleHttp\Client();

$textMarketer = new \Nessworthy\TextMarketer\TextMarketer($apiCredentials, $httpClient);

参数

凭据 - 实现 \Nessworthy\TextMarketer\Authentication
端点（可选） - 发送消息时使用的text marketer端点。应该是以下之一
- \Nessworthy\TextMarketer\TextMarketer::ENDPOINT_PRODUCTION（默认）
- \Nessworthy\TextMarketer\TextMarketer::ENDPOINT_SANDBOX
HTTP客户端（可选） - 发送请求的HTTP客户端。
- 期望是 GuzzleHttp\ClientInterface 的实现。
- 默认情况下，使用 GuzzleHttp\Client 的实例。

创建并发送短信

$messageCommand = new \Nessworthy\TextMarketer\Message\SendMessage(
    'This is a test message', // Your SMS Message.
    ['447777777777'],         // The array of contact numbers.
    'TestCompanyInc',         // Who the message was sent from.
    'testmessage',            // Optional: Tag your message for delivery report filtering.
    24,                       // Optional: Mark the message as time-sensitive: Should only be sent if it is within X hours.
    true,                     // Optional: If true, if any recipient is matched in your STOP group the message will not be sent.
    'myTxtUsEmail@address.com'// Optional: Your txtUS enterprise email (txtUS accounts only).
);

$deliveryResult = $textMarketer->sendMessage($messageCommand);

if ($deliveryResult->isSent()) {
    echo 'Message sent with the ID of ' . $deliveryResult->getMessageId();
} elseif ($deliveryResult->isQueued()) {
    echo 'Message queued with the ID of ' . $deliveryResult->getMessageId();
} elseif ($deliveryResult->isScheduled()) {
    echo 'Is scheduled with the ID of ' . $deliveryResult->getScheduledId();
}

安排短信

$scheduledDate = (new DateTimeImmutable)->modify('+1 month');
$deliveryResult = $textMarketer->sendScheduledMessage($messageCommand, $scheduledDate);

删除已安排的短信

// Scheduled message ID can be found from the delivery result for scheduled messages:
// $scheduledMessageId = $deliveryResult->getScheduledId();
$textMarketer->deleteScheduledMessage($scheduledMessageId);

处理和转移余额

获取当前余额

echo sprintf('I have %d remaining credits!', $textMarketer->getCreditCount());

通过账户ID或凭据转移余额

$transferResult = $textMarketer->transferCreditsToAccountById(100, $someAccountId);

// Or by credentials:

$destinationCredentials = new \Nessworthy\TextMarketer\Authentication\Simple('username', 'password'));
$transferResult = $textMarketer->transferCreditsToAccountByCredentials(100, $destinationCredentials);

echo sprintf(
    'I had %d credits. After transferring, I now have %d!',
    $transferResult->getSourceCreditsBeforeTransfer(),
    $transferResult->getSourceCreditsAfterTransfer()
);
echo '<br>';
echo sprintf(
    'The target account had %d credits. After transferring, it now has %d!',
    $transferResult->getTargetCreditsBeforeTransfer(),
    $transferResult->getTargetCreditsAfterTransfer()
);

关键词可用性

$keyword = 'mykeyword';
$keywordAvailability = $textMarketer->checkKeywordAvailability($keyword);

echo sprintf(
    'The keyword "%s" %s available! It %s been recycled (used previously).',
    $keyword,
    ($keywordAvailability->isAvailable() ? 'is' : 'is not'),
    ($keywordAvailability->isRecycled() ? 'has' : 'has not')
);

群组管理

获取您的群组列表

$groupCollection = $textMarketer->getGroupsList();

echo sprintf(
    'I have %s groups!',
    $groupCollection->isEmpty() ? 'no' : $groupCollection->getTotal()
);

echo '<br>';
echo 'Here is a summary of each group:';
foreach ($groupCollection->asArray() as $groupSummary) {
    echo sprintf(
        'Group name: %s (ID: %d) has %s numbers. It %s a stop group!',
        $groupSummary->getName(),
        $groupSummary->getId(),
        $groupSummary->getNumberCount(),
        $groupSummary->isStopGroup() ? 'IS' : 'IS NOT'
    );
    echo '<br/>';
}

将一个或多个号码添加到群组

$numbersToAdd = new Nessworthy\TextMarketer\Message\Part\PhoneNumberCollection([
    '44700000000',
    '44700000001',
    '44700000002',
]);

$result = $textMarketer->addNumbersToGroup('MyGroupNameOrID', $numbersToAdd);

// Of the numbers - which ones were actually added to the list.
echo 'Added numbers: ' . $textMarketer->getTotalAddedNumbers();
echo 'Numbers added:<br>' . implode('<br>',$textMarketer->getAddedNumbers();
echo '<br>';

// Of the numbers - which ones were not added because they were on a STOP list.
echo 'Stopped numbers: ' . $textMarketer->getTotalStoppedNumbers();
echo 'Numbers added:<br>' . implode('<br>',$textMarketer->getStoppedNumbers();
echo '<br>';

// Of the numbers - which ones were not added because they were already on it.
echo 'Duplicated numbers: ' . $textMarketer->getTotalDuplicateNumbers();
echo 'Numbers added:<br>' . implode('<br>',$textMarketer->getDuplicateNumbers();

创建新群组

$group = $textMarketer->createGroup('mygroup');

echo sprintf(
    'A new group was created by the name "%s" with an assigned ID of "%d"! The group %s a stop group.',
    $group->getName(),
    $group->getId(),
    $group->isStopGroup() ? 'IS' : 'IS NOT'
);

// You can also use getNumberCount() and getNumbers(), which will return 0 and an empty array, respectively.

获取现有群组信息

$group = $textMarketer->getGroupInformation('mygroup');

echo sprintf(
    'The group is called "%s" with an assigned ID of "%d"! The group %s a stop group.',
    $group->getName(),
    $group->getId(),
    $group->isStopGroup() ? 'IS' : 'IS NOT'
);

echo '<br/>';

echo sprintf(
    'The group has %d numbers. Here they are:<br>%s',
    $group->getNumberCount(),
    implode('<br>', $group->getNumbers())
);

投递报告

$reportCollection = $textMarketer->getDeliveryReportList();

echo sprintf(
    'I have %s reports in total!',
    $reportCollection->isEmpty() ? 'no' : $reportCollection->getTotal()
);

foreach ($reportCollection->asArray() as $report) {
    echo '<br>';
    echo sprintf(
        'Report %s (last updated: %s) has extension %s.',
        $report->getName(),
        $report->getLastUpdated->format('d-m-Y H:i:s'),
        $report->getExtension()
    );
}

所有与报告相关的调用都以上述相同的格式返回结果。

按报告名称筛选

$reportCollection = $textMarketer->getDeliveryReportListByName('ReportName');

按报告名称和日期范围筛选

$from = new DateTimeImmutable();
$to = $from->modify('-1 week');
$dateRange = new \Nessworthy\TextMarketer\DateRange($from, $to);
$reportCollection = $textMarketer->getDeliveryReportListByNameAndDateRange('ReportName', $dateRange);

按报告名称和标签筛选

$from = new DateTimeImmutable();
$reportCollection = $textMarketer->getDeliveryReportListByNameAndTag('ReportName', 'mytag');

按报告名称、标签和日期范围筛选

$from = new DateTimeImmutable();
$to = $from->modify('-1 week');
$dateRange = new \Nessworthy\TextMarketer\DateRange($from, $to);
$reportCollection = $textMarketer->getDeliveryReportListByNameTagAndDateRange('ReportName', 'mytag', $dateRange);

账户管理

这里的所有方法都返回 Nessworthy\TextMarketer\Account\AccountInformation 的实例。这些对象包含账户和API凭据 - 不要缓存或以其他方式保存它们！

获取您的账户信息

$accountInformation = $textMarketer->getAccountInformation();

echo 'Account ID: ' . $accountInformation->getId();
echo '<br>Company Name: ' . $accountInformation->getCompanyName();
echo '<br>Account Created At: ' . $accountInformation->getCreatedDate()->format('d/m/Y H:i:s');
echo '<br>Remaining Credits: ' . $accountInformation->getRemainingCredits();
echo '<br>Notification Email: ' . $accountInformation->getNotificationEmail();
echo '<br>Notification Mobile Number: ' . $accountInformation->getNotificationMobile();
echo '<br>Account Username: ' . $accountInformation->getUiUserName();
echo '<br>Account Password: ' . $accountInformation->getUiPassword();
echo '<br>API Username: ' . $accountInformation->getApiUserName();
echo '<br>API Password: ' . $accountInformation->getApiPassword();

按账户ID获取账户信息

注意：账户ID应按字符串输入。

$accountInformation = $textMarketer->getAccountInformationForAccountId($accountId);

更新您的账户信息

注意：无法更新其他账户的信息 - 您必须使用他们的凭据。

UpdateAccountInformation 的所有字段都是可选的 - 当您不想更改特定字段时，传递 null。

更新账户信息时有一些限制。有关您可以使用的内容，请参阅此处。

$newAccountDetails = new Nessworthy\TextMarketer\Account\UpdateAccountInformation(
    'uiusername',               // The new UI Username.
    'uipassword',               // The new UI Password.
    'apiusername',              // The new API Username.
    'apipassword',              // The new API Password.
    'Company Name',             // The new company name.
    'notification@email.com',   // The new notification email address.
    '447000000000',             // The new notification mobile number.
);

$updatedAccountInformation = $textMarketer->updateAccountInformation($newAccountDetails);

创建新子账户

注意：默认情况下禁用创建新账户 - 您需要联系TextMarketer启用此功能。与更新账户一样，您至少需要提供一个通知电子邮件地址或通知手机号码。

这些字段受与更新账户信息时相同的限制。

$subAccount = new Nessworthy\TextMarketer\Account\CreateSubAccount(
    'uiusername',              // The new account's username
    'uipassword',              // Optional: The new account's password. If null is given, a random password will be generated.
    'Company Name',            // The new account's company name.
    'notification@email.com',  // Optional: The new account's notification email address.
    '447000000000',            // Optional: The new account's notification mobile number.
    false,                     // Whether to use the same pricing as the parent account.
    'PROMOCODE'                // Optional: A promo code for the account if you have one.
);

异常和错误处理

// All exceptions extend \Nessworthy\TextMarketer\TextMarketerException.
try {
    // Send a text marketer request.
} catch (\Nessworthy\TextMarketer\Endpoint\EndpointException $e) {
    // $e->getMessage() and $e->getCode() return the first message & message code.
    // Or for all errors...
    foreach ($e->getAllEndpointErrors() as $error) {
        error_log(sprintf('TextMarketer Message Error: [%s] %s', $error->getCode(), $error->getMessage()));         
    }
}

nessworthy / textmarketer

维护者

详细信息