Download the PHP package toplan/phpsms without Composer

PhpSms

可能是目前最聪明、优雅的 php 短信发送库了。

phpsms的任务均衡调度功能由toplan/task-balancer提供。

特别感谢以下赞助者:

特点

• 支持内容短信，模版短信，语音验证码，内容语音，模版语音，语音文件。
• 支持发送均衡调度，可按代理器权重值均衡选择服务商发送。
• 支持一个或多个备用代理器(服务商)。
• 支持代理器调度方案热更新，可随时更新/删除/新加代理器。
• 允许推入队列，并自定义队列实现逻辑(与队列系统松散耦合)。
• 灵活的发送前后钩子。
• 内置国内主流服务商的代理器。
• 寄生代理器。

服务商

安装

开发中版本

快速上手

1. 配置

• 配置代理器所需参数

为你需要用到的短信服务商(即代理器)配置必要的参数。可以在config\phpsms.php中键为agents的数组中配置，也可以手动在程序中设置，示例如下：

• 配置代理器调度方案

可在config\phpsms.php中键为scheme的数组中配置。也可以手动在程序中设置，示例如下：

调度方案解析： 如果按照以上配置，那么系统首次会尝试使用Luosimao或YunPian发送短信，且它们被使用的概率分别为2/3和1/3。 如果使用其中一个代理器发送失败，那么会启用备用代理器，按照配置可知备用代理器有YunPian和SmsBao，那么会依次调用直到发送成功或无备用代理器可用。 值得注意的是，如果首次尝试的是YunPian，那么备用代理器将会只使用SmsBao，也就是会排除使用过的代理器。

2. Enjoy it!

3. 在laravel和lumen中使用

• 服务提供器

• 生成配置文件

生成的配置文件为config/phpsms.php，然后在该文件中按提示配置。

• 使用

详见API，示例：

API

API - 全局配置

Sms::scheme([$name[, $scheme]])

设置/获取代理器的调度方案。

调度配置支持热更新，即在应用系统的整个运行过程中都能随时修改。

• 设置

手动设置代理器调度方案(优先级高于配置文件)，如：

• 获取

通过该方法还能获取所有或指定代理器的调度方案，如：

scheme静态方法的更多使用方法见高级调度配置

Sms::config([$name[, $config][, $override]]);

设置/获取代理器的配置数据。

参数配置支持热更新，即在应用系统的整个运行过程中都能随时修改。

• 设置

手动设置代理器的配置数据(优先级高于配置文件)，如：

• 获取

通过该方法还能获取所有或指定代理器的配置参数，如：

Sms::beforeSend($handler[, $override]);

发送前钩子，示例：

更多细节请查看 task-balancer 的 beforeRun 钩子

Sms::beforeAgentSend($handler[, $override]);

代理器发送前钩子，示例：

更多细节请查看 task-balancer 的 beforeDriverRun 钩子

Sms::afterAgentSend($handler[, $override]);

代理器发送后钩子，示例：

更多细节请查看 task-balancer 的 afterDriverRun 钩子

Sms::afterSend($handler[, $override]);

发送后钩子，示例：

更多细节请查看 task-balancer 的 afterRun 钩子

Sms::queue([$enable[, $handler]])

该方法可以设置是否启用队列以及定义如何推送到队列。

$handler匿名函数可使用的参数:

• $sms : Sms实例
• $data : Sms实例中的短信数据，等同于$sms->all()

定义如何推送到队列：

如果已经定义过如何推送到队列，还可以继续设置关闭/开启队列：

获取队列启用情况：

API - 发送相关

Sms::make()

生成发送短信的sms实例，并返回实例。

Sms::voice()

生成发送语音验证码的sms实例，并返回实例。

• 如果你使用Luosimao语音验证码，还需用在配置文件中Luosimao选项中设置voiceApikey。
• 语音文件ID即是在服务商配置的语音文件的唯一编号，比如阿里大鱼语音通知的voice_code。
• 模版语音是另一种语音请求方式，它是通过模版ID和模版数据进行的语音请求，比如阿里大鱼的文本转语音通知。

type($type)

设置实例类型，可选值有Sms::TYPE_SMS和Sms::TYPE_VOICE，返回实例对象。

to($mobile)

设置发送给谁，并返回实例。

template($agentName, $id)

指定代理器设置模版或批量设置，并返回实例。

data($key, $value)

设置模板短信的模板数据，并返回实例对象。

通过template和data方法的组合除了可以实现模版短信的数据填充，还可以实现模版语音的数据填充。

content($text)

设置内容短信的内容，并返回实例对象。

一些内置的代理器(如SmsBao、YunPian、Luosimao)使用的是内容短信(即直接发送短信内容)，那么就需要为它们设置短信内容。

code($code)

设置语音验证码，并返回实例对象。

file($agentName, $id)

设置语音文件，并返回实例对象。

params($agentName, $params)

直接设置参数到服务商提供的原生接口上，并返回实例对象。

all([$key])

获取Sms实例中的短信数据，不带参数时返回所有数据，其结构如下：

agent($name)

临时设置发送时使用的代理器(不会影响备用代理器的正常使用)，并返回实例，$name为代理器名称。

通过该方法设置的代理器将获得绝对优先权，但只对当前短信实例有效。

send()

请求发送短信/语音验证码。

$result数据结构请参看task-balancer

自定义代理器

• step 1

可将配置项(如果有用到)加入到config/phpsms.php中键为agents的数组里。

• step 2

新建一个继承Toplan\PhpSms\Agent抽象类的代理器类，建议代理器类名为FooAgent，建议命名空间为Toplan\PhpSms。

如果类名不为FooAgent或者命名空间不为Toplan\PhpSms，在使用该代理器时则需要指定代理器类，详见高级调度配置。

• step 3

实现相应的接口，可选的接口有:

高级调度配置

代理器的高级调度配置可以通过配置文件(config/phpsms.php)中的scheme项目配置，也可以通过scheme静态方法设置。 值得注意的是，高级调度配置的值的数据结构是数组。

指定代理器类

如果你自定义了一个代理器，类名不为FooAgent或者命名空间不为Toplan\PhpSms， 那么你还可以在调度配置时指定你的代理器使用的类。

• 配置方式：

通过配置值中agentClass键来指定类名。

• 示例：

寄生代理器

如果你既不想使用内置的代理器，也不想创建文件写自定义代理器，那么寄生代理器或许是个好的选择， 无需定义代理器类，只需在调度配置时定义好发送短信和语音验证码的方式即可。

• 配置方式：

可以配置的发送过程有:

• 示例：

Todo

• [ ] 重新实现云通讯代理器，去掉lib/CCPRestSmsSDK.php
• [ ] 重新实现云之讯代理器，去掉lib/Ucpaas.php
• [ ] 升级云片接口到v2版本

License

MIT