minchao/mitake-php

三竹簡訊 PHP SDK

mitake-php

mitake-php 是三竹簡訊 SMS HTTP API 的非官方 PHP Client SDK（僅支援台灣行動電話號碼），使用這個 SDK 前， 請確認您已申請三竹簡訊 HTTP Function Call 功能，若您想在 Laravel 下使用，請參考 mitake-laravel 提供的 Service provider

執行環境

• PHP >= 5.6
• Guzzle requirements

安裝

推薦使用 Composer 安裝 mitake-php

$ composer require minchao/mitake-php

使用

Mitake client

實例化 Mitake client，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 Port 上啟動 webhook 服務， 並自動透過 Let's Encrypt 建立 SSL 憑證

Command:

$ VIRTUAL_HOST=your.domain.name \
  LETSENCRYPT_HOST=your.domain.name \
  [email protected] \
  docker-compose up

Logs:

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

FAQ

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

A：這是因為 OpenSSL 已不支援 TLS 1.1 以下版本，建議使用長簡訊方法來傳送簡訊，請參考 Issue #4 的說明。

注意：使用 HTTP 或已棄用的 TLS 協議來傳送簡訊，會將傳輸資料暴露外洩的風險之中。

License

See the LICENSE file for license rights and limitations (MIT).

mitake-php's Issues

ssl error

PHP Fatal error: Uncaught GuzzleHttp\Exception\ConnectException: cURL error 35: error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure (see http://curl.haxx.se/libcurl/c/libcurl-errors.html) in /home/yun_chen/project/mitake-php/vendor/guzzlehttp/guzzle/src/Handler/CurlFactory.php:185

Stack trace:
#0 /home/yun_chen/project/mitake-php/vendor/guzzlehttp/guzzle/src/Handler/CurlFactory.php(149): GuzzleHttp\Handler\CurlFactory::createRejection(Object(GuzzleHttp\Handler\EasyHandle), Array)
#1 /home/yun_chen/project/mitake-php/vendor/guzzlehttp/guzzle/src/Handler/CurlFactory.php(102): GuzzleHttp\Handler\CurlFactory::finishError(Object(GuzzleHttp\Handler\CurlHandler), Object(GuzzleHttp\Handler\EasyHandle), Object(GuzzleHttp\Handler\CurlFactory))

#2 /home/yun_chen/project/mitake-php/vendor/guzzlehttp/guzzle/src/Handler/CurlHandler.php(43): GuzzleHttp\Handler\CurlFactory::finish(Object(GuzzleHttp\Handler\CurlHandler), Object(GuzzleHttp\Handler\EasyHandle), Object(GuzzleHttp\Handler\CurlFactory))

#3 /home/yun_chen/proj in /home/yun_chen/project/mitake-php/vendor/guzzlehttp/guzzle/src/Handler/CurlFactory.php on line 185

ssl long message

三竹的人跟我說明長簡訊的部份是使用 tls1.2 ，我剛剛測試過是沒問題的，我回家會發 pr 修正此問題。

另外他們也有說明，如果長簡訊在70個字裡面一樣算1點，是否要為了安全性短簡訊改成使用長簡訊發送

API endpoint updated

今天經實測，API 端點已經被更新為 http://smsapi.mitake.com.tw
且許多子 path 都有重新設置，建議向三竹方要一份全新文件調整此 sdk。

AppVeyor cannot download PHP

Logs:

$php_version_file = $Env:php_archive_directory + '\php-' + $requested_php_version + '.zip'
If ((Test-Path $php_version_file) -eq $False) { appveyor-retry appveyor DownloadFile $php_version_url -FileName $php_version_file }
Downloading php-7.0.29.zip (598 bytes)...100%

https://ci.appveyor.com/project/minchao/mitake-php/build/1.0.10/job/ye3vh5b4r080m1ep#L18

References:

• https://www.appveyor.com/docs/how-to/download-file/