README

通过 Goyya Mobile 发送单条短消息的简单 API 封装。

安装

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

使用

自动加载和命名空间

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

发送单条短信

API 客户端认证

对 Goyya Mobile Web 服务进行 API 客户端认证需要有效的账户 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-bit 默认字母表，以确保您的内容在接收者的手机上按预期显示。

$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提供不同类型的异常。

• 在调用setter时，如果传入的参数无效，将抛出\InvalidArgumentException异常。
• 如果请求Goyya Mobile提供商的webservice失败（无论何种原因），将抛出ChromaX\CommonException子类异常。

您可以在GitHub上找到有关PHP通用异常的更多信息。

所有异常都有特定的代码，以便您正确处理这些异常。

完整示例

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 Mobile简单API采用MIT许可证。