README

通过Goyya Mobile发送单条短消息的简单API抽象。

安装

{
   	"require": {
        "chroma-x/goyyamobile": "~4.0"
    }
}

用法

自动加载和命名空间

require_once('path/to/vendor/autoload.php');

发送单条短消息

API客户端认证

对Goyya Mobile web服务的认证需要有效的账户ID和密码或有效的认证令牌。

通过账户凭据进行API客户端认证

$shortMessage = new ChromaX\GoyyaMobile\Message();
$shortMessage
	->setAccountId('GOYYA_ACCOUNT_ID')
	->setAccountPassword('GOYYA_ACCOUNT_PASSWORD');

通过认证令牌进行API客户端认证

$shortMessage = new ChromaX\GoyyaMobile\Message();
$shortMessage->setAuthToken('GOYYA_AUTH_TOKEN');

调试模式

如果您启用调试模式，您的消息将被提交到您的Goyya Mobile提供商，但不会传输给接收者。

默认情况下，调试模式是禁用的。

$shortMessage->setDebugMode(true);

准备消息元数据

设置元数据需要以下属性。

• 接收者手机号码，使用国际格式，例如 +4915112345678
• 发送者的姓名或手机号码，使用国际格式。发送者信息应仅包含字符 [a-z,A-Z,0-9]，不允许有空格。手机号码允许长度最多16位，以 00 开头。发送者姓名允许长度最多11字节。
• 如果您想将短消息的提交延迟到特定时间，您可以调用 setSubmissionDate(YOUR_DESIRED_TIMESTAMP) 方法，并通过调用 setDelayedSubmission(true) 启用延迟提交。
• 如果您的账户未绑定到特定计划，您可以选择您想要使用（并付费）的计划。使用以下其中一个类常量作为参数调用 setSubmissionPlan 方法。
  • ChromaX\GoyyaMobile\Message::PLAN_BASIC
  • ChromaX\GoyyaMobile\Message::PLAN_ECONOMY
  • ChromaX\GoyyaMobile\Message::PLAN_QUALITY

注意：请检查您的计划，以确保您可以使用姓名而不是手机号码发送短消息。
默认情况下，延迟提交是禁用的。
默认计划是 ChromaX\GoyyaMobile\Message::PLAN_BASIC。

$shortMessage
	->setReceiver('RECEIVER_MOBILE_NUMBER')
	->setSender('SENDER_NAME_OR_MOBILE_NUMBER')
	->setDelayedSubmission(true)
	->setSubmissionDate(strtotime('+6 hours'))
	->setSubmissionPlan(ChromaX\GoyyaMobile\Message::PLAN_QUALITY);

设置消息内容

通过配置消息类型和内容来设置消息内容。

• 消息类型定义了内容如何被处理。通过使用以下类常量之一调用 setMessageType 方法来控制消息内容应如何传递。
  • ChromaX\GoyyaMobile\Message::MESSAGE_TYPE_TEXT_SMS 允许发送 160 字节。设置超过此范围的内容将抛出 ChromaX\GoyyaMobile\Exception\InvalidArgumentException 异常。
  • ChromaX\GoyyaMobile\Message::MESSAGE_TYPE_OVERLONG_SMS 允许发送超过 160 字节的内容。如果需要，内容将在多个消息中提交。
  • ChromaX\GoyyaMobile\Message::MESSAGE_TYPE_UTF8_SMS 允许发送超过 160 字节的 Unicode 字符。
• 消息内容将按照 setMessageType 中定义的方式进行处理。

默认消息类型为 ChromaX\GoyyaMobile\Message::MESSAGE_TYPE_TEXT_SMS。
请检查 GSM 7 位默认字母表，以确保您的文本在接收者的手机上按预期显示。

$shortMessage
	->setMessageType(ChromaX\GoyyaMobile\Message::MESSAGE_TYPE_OVERLONG_SMS)
	->setMessage('Curabitur blandit tempus porttitor. ÄÖÜß~');

提交消息

通过调用 submit 方法提交消息。

$shortMessage->submit();

获取提交信息

成功提交后，将提供 Goyya Mobile 消息 ID 和实际提交的消息数量。

$messageId = $shortMessage->getMessageId();
$messageCount = $shortMessage->getMessageCount();

异常处理

Goyya Mobile 简单 API 提供了不同类型的异常。

• 当调用设置器时使用无效参数将抛出 \InvalidArgumentException 异常。
• 如果请求 Goyya Mobile 提供商的 web 服务失败，将抛出 ChromaX\CommonException 子类异常。

您可以在 GitHub 上的 PHP Common Exceptions 中找到更多信息。

所有异常都有一个特定的代码，以便您能够正确处理异常。

完整示例

require_once('path/to/vendor/autoload.php');

use ChromaX\CommonException;

try {
	$shortMessage = new ChromaX\GoyyaMobile\Message();
	$shortMessage
		->setAccountId('GOYYA_ACCOUNT_ID')
		->setAccountPassword('GOYYA_ACCOUNT_PASSWORD')
		->setDebugMode(true)
		->setReceiver('RECEIVER_MOBILE_NUMBER')
		->setSender('SENDER_NAME_OR_MOBILE_NUMBER')
		->setDelayedSubmission(true)
		->setSubmissionDate(strtotime('+6 hours'))
		->setSubmissionPlan(ChromaX\GoyyaMobile\Message::PLAN_QUALITY)
		->setMessageType(ChromaX\GoyyaMobile\Message::MESSAGE_TYPE_OVERLONG_SMS)
		->setMessage('Curabitur blandit tempus porttitor. ÄÖÜß~')
		->submit();
	echo 'Message ID ' . $shortMessage->getMessageId() . PHP_EOL;
	echo 'Message count ' . $shortMessage->getMessageCount() . PHP_EOL;
} catch (\InvalidArgumentException $exception) {
	echo $exception->getMessage() . PHP_EOL;
	echo $exception->getCode() . PHP_EOL;
} catch (CommonException\NetworkException\Base\NetworkException $exception) {
	echo $exception->getMessage() . PHP_EOL;
	echo $exception->getCode() . PHP_EOL;
} catch (CommonException\ApiException\Base\ApiException $exception) {
	echo $exception->getMessage() . PHP_EOL;
	echo $exception->getCode() . PHP_EOL;
}

贡献

对我们项目的贡献总是非常受欢迎。
但：请遵循在 CONTRIBUTING.md 文档中记录的贡献指南。

待办事项

• 用一些单元测试装饰代码库。
• 发布贡献指南。
• 用基于TokenAuth的认证代替使用账户ID和密码作为凭证。
• 通过添加一些其他有用的方法扩展基本API，例如删除待处理消息和发送批量消息。

许可证

PHP Goyya移动简单API遵循MIT许可证。