tegic/sms

v2.0 2020-06-22 08:14 UTC

This package is not auto-updated.

Last update: 2022-06-21 15:51:26 UTC


README

📲 一款满足你的多种发送需求的短信发送组件

本组件是由 overtrue/easy-sms 改造,支持hyperf组件,直达连接: https://github.com/overtrue/easy-sms/blob/master/README.md

特点

  1. 支持目前市面多家服务商
  2. 一套写法兼容所有平台
  3. 简单配置即可灵活增减服务商
  4. 内置多种服务商轮询策略、支持自定义轮询策略
  5. 统一的返回值格式,便于日志与监控
  6. 自动轮询选择可用的服务商
  7. 更多等你去发现与改进...

平台支持

环境需求

  • PHP >= 7.0

安装

$ composer require "hyperf-libraries/sms"
$ php bin/hyperf.php vendor:publish hyperf-libraries/sms

使用

use HyperfLibraries\Sms\Sms;

$config = [
    // HTTP 请求的超时时间(秒)
    'timeout' => 5.0,

    // 默认发送配置
    'default' => [
        // 网关调用策略,默认:顺序调用
        'strategy' => \HyperfLibraries\Sms\Strategies\OrderStrategy::class,

        // 默认可用的发送网关
        'gateways' => [
            'yunpian', 'aliyun',
        ],
    ],
    // 可用的网关配置
    'gateways' => [
        'yunpian' => [
            'api_key' => '',
        ],
        'aliyun' => [
            'access_key_id' => '',
            'access_key_secret' => '',
            'sign_name' => '',
        ],
        //...
    ],
];

/**
 * @var SmsInterface
 */
public $sms;

public function __construct(SmsInterface $sms)
{
    $this->sms = $sms;
}

public function index()
{
    $result = $this->sms->send('18759557749', [
        'content'  => '', // 短信内容
        'template' => '', // 模板ID
        'data' => [
            'code' => 6379 //验证码
        ]
    ]);
    return $result;
}

短信内容

由于使用多网关发送,所以一条短信要支持多平台发送,每家的发送方式不一样,但是我们抽象定义了以下公用属性:

  • content 文字内容,使用在像云片类似的以文字内容发送的平台
  • template 模板 ID,使用在以模板ID来发送短信的平台
  • data 模板变量,使用在以模板ID来发送短信的平台

所以,在使用过程中你可以根据所要使用的平台定义发送的内容。

$sms->send(13188888888, [
    'content'  => '您的验证码为: 6379',
    'template' => 'SMS_001',
    'data' => [
        'code' => 6379
    ],
]);

你也可以使用闭包来返回对应的值:

$sms->send(13188888888, [
    'content'  => function($gateway){
        return '您的验证码为: 6379';
    },
    'template' => function($gateway){
        return 'SMS_001';
    },
    'data' => function($gateway){
        return [
            'code' => 6379
        ];
    },
]);

你可以根据 $gateway 参数类型来判断返回值,例如:

$sms->send(13188888888, [
    'content'  => function($gateway){
        if ($gateway->getName() == 'yunpian') {
            return '云片专用验证码:1235';
        }
        return '您的验证码为: 6379';
    },
    'template' => function($gateway){
        if ($gateway->getName() == 'aliyun') {
            return 'TP2818';
        }
        return 'SMS_001';
    },
    'data' => function($gateway){
        return [
            'code' => 6379
        ];
    },
]);

发送网关

默认使用 default 中的设置来发送,如果某一条短信你想要覆盖默认的设置。在 send 方法中使用第三个参数即可:

$easySms->send(13188888888, [
    'content'  => '您的验证码为: 6379',
    'template' => 'SMS_001',
    'data' => [
        'code' => 6379
    ],
 ], ['yunpian', 'juhe']); // 这里的网关配置将会覆盖全局默认值

返回值

由于使用多网关发送,所以返回值为一个数组,结构如下:

[
    'yunpian' => [
        'gateway' => 'yunpian',
        'status' => 'success',
        'result' => [...] // 平台返回值
    ],
    'juhe' => [
        'gateway' => 'juhe',
        'status' => 'failure',
        'exception' => \HyperfLibraries\Sms\Exceptions\GatewayErrorException 对象
    ],
    //...
]

如果所选网关列表均发送失败时,将会抛出 HyperfLibraries\Sms\Exceptions\NoGatewayAvailableException 异常,你可以使用 $e->results 获取发送结果。

你也可以使用 $e 提供的更多便捷方法:

$e->getResults();               // 返回所有 API 的结果,结构同上
$e->getExceptions();            // 返回所有调用异常列表
$e->getException($gateway);     // 返回指定网关名称的异常对象
$e->getLastException();         // 获取最后一个失败的异常对象 

自定义网关

本拓展已经支持用户自定义网关,你可以很方便的配置即可当成与其它拓展一样的使用:

$config = [
    ...
    'default' => [
        'gateways' => [
            'mygateway', // 配置你的网站到可用的网关列表
        ],
    ],
    'gateways' => [
        'mygateway' => [...], // 你网关所需要的参数,如果没有可以不配置
    ],
];

$sms = new Sms($config);

// 注册
$sms->extend('mygateway', function($gatewayConfig){
    // $gatewayConfig 来自配置文件里的 `gateways.mygateway`
    return new MyGateway($gatewayConfig);
});

$sms->send(13188888888, [
    'content'  => '您的验证码为: 6379',
    'template' => 'SMS_001',
    'data' => [
        'code' => 6379
    ],
]);

国际短信

国际短信与国内短信的区别是号码前面需要加国际码,但是由于各平台对国际号码的写法不一致,所以在发送国际短信的时候有一点区别:

use HyperfLibraries\Sms\PhoneNumber;

// 发送到国际码为 31 的国际号码
$number = new PhoneNumber(13188888888, 31);

$easySms->send($number, [
    'content'  => '您的验证码为: 6379',
    'template' => 'SMS_001',
    'data' => [
        'code' => 6379
    ],
]);

定义短信

你可以根据发送场景的不同,定义不同的短信类,从而实现一处定义多处调用,你可以继承 Overtrue\EasySms\Message 来定义短信模型:

<?php

use HyperfLibraries\Sms\Message;
use HyperfLibraries\Sms\GatewayInterface;
use HyperfLibraries\Sms\OrderStrategy;

class OrderPaidMessage extends Message
{
    protected $order;
    protected $strategy = OrderStrategy::class;           // 定义本短信的网关使用策略,覆盖全局配置中的 `default.strategy`
    protected $gateways = ['alidayu', 'yunpian', 'juhe']; // 定义本短信的适用平台,覆盖全局配置中的 `default.gateways`

    public function __construct($order)
    {
        $this->order = $order;
    }

    // 定义直接使用内容发送平台的内容
    public function getContent(GatewayInterface $gateway = null)
    {
        return sprintf('您的订单:%s, 已经完成付款', $this->order->no);    
    }

    // 定义使用模板发送方式平台所需要的模板 ID
    public function getTemplate(GatewayInterface $gateway = null)
    {
        return 'SMS_003';
    }

    // 模板参数
    public function getData(GatewayInterface $gateway = null)
    {
        return [
            'order_no' => $this->order->no    
        ];    
    }
}

发送自定义短信:

$order = ...;
$message = new OrderPaidMessage($order);

$sms->send(13188888888, $message);

各平台配置说明

阿里云

短信内容使用 template + data

    'aliyun' => [
        'access_key_id' => '',
        'access_key_secret' => '',
        'sign_name' => '',
    ],

阿里云Rest

短信内容使用 template + data

    'aliyunrest' => [
        'app_key' => '',
        'app_secret_key' => '',
        'sign_name' => '',
    ],

云片

短信内容使用 content

    'yunpian' => [
        'api_key' => '',
        'signature' => '【默认签名】', // 内容中无签名时使用
    ],

Submail

短信内容使用 data

    'submail' => [
        'app_id' => '',
        'app_key' => '',
        'project' => '', // 默认 project,可在发送时 data 中指定
    ],

螺丝帽

短信内容使用 content

    'luosimao' => [
        'api_key' => '',
    ],

容联云通讯

短信内容使用 template + data

    'yuntongxun' => [
        'app_id' => '',
        'account_sid' => '',
        'account_token' => '',
        'is_sub_account' => false,
    ],

互亿无线

短信内容使用 content

    'huyi' => [
        'api_id' => '',
        'api_key' => '',
        'signature' => '',
    ],

聚合数据

短信内容使用 template + data

    'juhe' => [
        'app_key' => '',
    ],

SendCloud

短信内容使用 template + data

    'sendcloud' => [
        'sms_user' => '',
        'sms_key' => '',
        'timestamp' => false, // 是否启用时间戳
    ],

百度云

短信内容使用 template + data

    'baidu' => [
        'ak' => '',
        'sk' => '',
        'invoke_id' => '',
        'domain' => '',
    ],

华信短信平台

短信内容使用 content

    'huaxin' => [
        'user_id'  => '',
        'password' => '',
        'account'  => '',
        'ip'       => '',
        'ext_no'   => '',
    ],

253云通讯(创蓝)

短信内容使用 content

    'chuanglan' => [
        'account' => '',
        'password' => '',
        
        // 国际短信时必填
        'intel_account' => '',
        'intel_password' => '',

        // \HyperfLibraries\Sms\Gateways\ChuanglanGateway::CHANNEL_VALIDATE_CODE  => 验证码通道(默认)
        // \HyperfLibraries\Sms\Gateways\ChuanglanGateway::CHANNEL_PROMOTION_CODE => 会员营销通道
        'channel'  => \HyperfLibraries\Sms\Gateways\ChuanglanGateway::CHANNEL_VALIDATE_CODE, 

        // 会员营销通道 特定参数。创蓝规定:api提交营销短信的时候,需要自己加短信的签名及退订信息
        'sign' => '【通讯云】',
        'unsubscribe' => '回TD退订', 
    ],

融云

短信分为两大类,验证类和通知类短信。 发送验证类短信使用 template + data

    'rongcloud' => [
        'app_key' => '',
        'app_secret' => '',
    ]

天毅无线

短信内容使用 content

    'tianyiwuxian' => [
        'username' => '', //用户名
        'password' => '', //密码
        'gwid' => '', //网关ID
    ]

twilio

短信使用 content
发送对象需要 使用+添加区号

    'twilio' => [
        'account_sid' => '', // sid
        'from' => '', // 发送的号码 可以在控制台购买
        'token' => '', // apitoken
    ],

腾讯云 SMS

短信内容使用 content

    'qcloud' => [
        'sdk_app_id' => '', // SDK APP ID
        'app_key' => '', // APP KEY
        'sign_name' => '', // 短信签名,如果使用默认签名,该字段可缺省(对应官方文档中的sign)
    ],

阿凡达数据

短信内容使用 template + data

    'avatardata' => [
        'app_key' => '', // APP KEY
    ],

华为云 SMS

短信内容使用 template + data

    'huawei' => [
        'endpoint' => '', // APP接入地址
        'app_key' => '', // APP KEY
        'app_secret' => '', // APP SECRET
        'from' => [
            'default' => '1069012345', // 默认使用签名通道号
            'custom' => 'csms12345', // 其他签名通道号 可以在 data 中定义 from 来指定
            'abc' => 'csms67890', // 其他签名通道号
            ...
        ],
        'callback' => '' // 短信状态回调地址
    ],

使用默认签名通道 default

$sms->send(13188888888, [
    'template' => 'SMS_001',
    'data' => [
        6379
    ],
]);

使用指定签名通道

$sms->send(13188888888, [
    'template' => 'SMS_001',
    'data' => [
        6379,
        'from' => 'custom' // 对应 config 中的 from 数组中 custom
    ],
]);

网易云信

短信内容使用 template + data

    'yunxin' => [
        'app_key' => '',
        'app_secret' => '',
        'code_length' => 4, // 随机验证码长度,范围 4~10,默认为 4
        'need_up' => false, // 是否需要支持短信上行
    ],
$sms->send(18888888888, [
    'template' => 'SMS_001',    // 不填则使用默认模板
    'data' => [
        'code' => 8946, // 如果设置了该参数,则 code_length 参数无效
        'action' => 'sendCode', // 默认为 `sendCode`,校验短信验证码使用 `verifyCode`
    ],
]);

云之讯

短信内容使用 template + data

    'yunzhixun' => [
        'sid' => '',
        'token' => '',
        'app_id' => '',
    ],
$sms->send(18888888888, [
    'template' => 'SMS_001',
    'data' => [
        'params' => '8946,3',   // 模板参数,多个参数使用 `,` 分割,模板无参数时可为空
        'uid' => 'hexianghui',  // 用户 ID,随状态报告返回,可为空
        'mobiles' => '18888888888,188888888889',    // 批量发送短信,手机号使用 `,` 分割,不使用批量发送请不要设置该参数
    ],
]);

凯信通

短信内容使用 content

    'kingtto'  => [
        'userid'   => '',
        'account'  => '',
        'password' => '',
    ],
$sms->send(18888888888, [
    'content'  => '您的验证码为: 6379',
]);