README

mitake-php 是三竹簡訊 SMS HTTP API 的非官方 PHP 客户端 SDK（仅支持台湾手机号码），在使用此 SDK 之前，请确认您已申请三竹簡訊 HTTP Function Call 功能，如果您想在 Laravel 下使用，请参考 mitake-laravel 提供的 Service provider

执行环境

PHP >= 5.6
Guzzle 需求

安装

推荐使用 Composer 安装 mitake-php

$ composer require minchao/mitake-php

使用

Mitake 客户端

实例化 Mitake 客户端，USERNAME 和 PASSWORD 分别填写您申请的三竹簡訊账号和密码

<?php

require_once __DIR__ . '/vendor/autoload.php';

$client = new \Mitake\Client('USERNAME', 'PASSWORD');

示例

调用 Mitake API

查询账户余额

查询当前账户剩余点数

$resp = $client->queryAccountPoint();

发送单条短信

发送短信前，请先通过 Message 类创建短信内容，然后调用 API 的 send() 方法发送

$message = (new \Mitake\Message\Message())
    ->setDstaddr('0987654321')
    ->setSmbody('Hello, 世界');
$resp = $client->send($message);

发送多条短信

若要一次发送多条短信，请先创建要发送的 Message objects 数组，然后调用 API 的 sendBatch() 方法发送

$resp = $client->sendBatch([$message1, $message2]);

发送单条长短信

发送长短信前，请先通过 LongMessage 类创建短信内容，然后调用 API 的 sendLongMessage() 方法发送

$message = (new \Mitake\Message\LongMessage())
    ->setDstaddr('0987654321')
    ->setSmbody('Hello, 世界');
$resp = $client->sendLongMessage($message);

发送多条长短信

若要一次发送多条长短信，请先创建要发送的 LongMessage objects 数组，然后调用 API 的 sendLongMessageBatch() 方法发送

$resp = $client->sendLongMessageBatch([$message1, $message2]);

查询短信发送状态

查询时请带上短信发送后返回的 msgid

$resp = $client->queryMessageStatus(['MESSAGE_ID1', 'MESSAGE_ID2]);

取消预约发送短信

取消时请带上短信 msgid

$resp = $client->cancelMessageStatus(['MESSAGE_ID1', 'MESSAGE_ID2]);

使用 webhook 接收发送状态

发送短信时如果设置了 response 网址，短信服务器就会在发送状态更新时以 HTTP GET 方法通知指定的 response 网址，您可以参考 webhook 中的示例来接收短信发送状态

短信设置 response 网址：

$message->setResponse('https://your.domain.name/callback');

创建 webhook：

$app = new Slim\App();

$app->get('/callback', function (Request $request, Response $response, $args) {
    $params = parse_query($request->getUri()->getQuery());
    if (isset($params['msgid'])) {
        $receipt = new Receipt();
        $receipt->setMsgid($params['msgid']);
        // ...
    }
}

开发

开发工具

本项目提供 Command Line Developer Tools，供您在开发时作为测试工具使用

指令：

$ bin/mitake
Developer Tools

Usage:
  command [options] [arguments]

Options:
  -h, --help                       Display this help message
  -q, --quiet                      Do not output any message
  -V, --version                    Display this application version
      --ansi                       Force ANSI output
      --no-ansi                    Disable ANSI output
  -n, --no-interaction             Do not ask any interactive question
  -u, --username[=USERNAME]        Mitake Username
  -p, --password[=PASSWORD]        Mitake Password
  -c, --credentials[=CREDENTIALS]  Mitake Credentials
  -v|vv|vvv, --verbose             Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  balance  Retrieve your account balance
  help     Displays help for a command
  list     Lists commands
  send     Send an message
  status   Fetch the status of specific messages

使用示例如下：

$ bin/mitake send -u USERNAME -p PASSWORD -d 0987654321 -b 'Hello, 世界'
{
    "results": [
        {
            "msgid": "1234567890",
            "statuscode": "1"
        }
    ],
    "accountPoint": "999"
}

使用 Docker Compose 启动 webhook 服务

请设置环境变量 VIRTUAL_HOST、LETSENCRYPT_HOST 与 LETSENCRYPT_EMAIL，Docker Compose 会在本机的 443 端口上启动 webhook 服务，并自动通过 Let's Encrypt 建立SSL证书

Command

$ VIRTUAL_HOST=your.domain.name \
  LETSENCRYPT_HOST=your.domain.name \
  LETSENCRYPT_EMAIL=username@mail.com \
  docker-compose up

日志

webhook | 172.18.0.3 - - [01/Oct/2017:05:17:34 +0000] "GET /callback?msgid=1234567890&dstaddr=0987654321&dlvtime=20171001112328&donetime=20171001112345&statusstr=DELIVRD&statuscode=0&StatusFlag=4 HTTP/2.0" 200 156 "-" "Mozilla/5.0"

执行测试

执行 phpcs 与 phpunit 测试

$ composer run check

常见问题解答

Q：遇到 PHP Fatal error: Uncaught GuzzleHttp\Exception\ConnectException: cURL error 35

A：这是因为 OpenSSL 已不支持 TLS 1.1 以下版本，建议使用长短信方法来发送短信，请参考 Issue #4 的说明。

注意：使用 HTTP 或已弃用的 TLS 协议来发送短信，会将传输数据暴露在外部泄露的风险之中。

许可

有关许可权利和限制，请参阅 LICENSE 文件（MIT）。

minchao / mitake-php

维护者

详细信息