PHPackages                             surpaimb/laravel-sms - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. surpaimb/laravel-sms

ActiveLibrary

surpaimb/laravel-sms
====================

A mobile phone number validation solution based on laravel

00PHP

Since Mar 18Pushed 5y ago1 watchersCompare

[ Source](https://github.com/surpaimb/laravel-sms)[ Packagist](https://packagist.org/packages/surpaimb/laravel-sms)[ RSS](/packages/surpaimb-laravel-sms/feed)WikiDiscussions master Synced 2d ago

READMEChangelogDependenciesVersions (1)Used By (0)

Laravel Sms
===========

[](#laravel-sms)

[![StyleCI](https://camo.githubusercontent.com/f4474e6fdecd197fd481296de2d3471c3efff008f6376467e5a039564f463c0d/68747470733a2f2f7374796c6563692e696f2f7265706f732f33363731333134322f736869656c64)](https://styleci.io/repos/36713142)[![Latest Stable Version](https://camo.githubusercontent.com/c351ff8e5eecf74bfee80e95fbeb7d1d859ba3bc41b00570d1417d4a3db8287c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7375727061696d622f6c61726176656c2d736d732e737667)](https://packagist.org/packages/surpaimb/laravel-sms)[![Total Downloads](https://camo.githubusercontent.com/f2fbe58ec8868f2934a530de81c95f3b665ab6c588c979b64861cb7840c3211b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7375727061696d622f6c61726176656c2d736d732e737667)](https://packagist.org/packages/surpaimb/laravel-sms)

一个基于`Laravel`框架的功能强大的手机号合法性验证解决方案。

### 1. 关于2.0

[](#1-关于20)

`laravel-sms` 2.0是基于[surpaimb/phpsms](https://github.com/surpaimb/phpsms)开发的适用于`Laravel`框架的手机号验证解决方案。 `phpsms`为`laravel-sms`提供了全套的短信发送机制，而且`phpsms`也有自己的 service provider ，也就是说你完全可以在`Laravel`框架下无障碍的独立使用`phpsms`。 这也是为什么使用`laravel-sms`会在项目中生成两个配置文件(`phpsms.php`和`laravel-sms.php`)的原因。

> `config/phpsms.php`负责配置代理器参数以及规划如何最优调度代理器(由phpsms提供)， `config/laravel-sms.php`负责验证码发送/验证模块的配置(由laravel-sms提供)。

### 2. why me

[](#2-why-me)

为了更进一步提高开发效率，`laravel-sms`为`Laravel`框架定制好了如下功能：

- 可扩展的[发送前数据验证](#%E5%8F%91%E9%80%81%E5%89%8D%E6%95%B0%E6%8D%AE%E9%AA%8C%E8%AF%81)
- 集成[验证码发送与验证模块](#%E9%AA%8C%E8%AF%81%E7%A0%81%E6%A8%A1%E5%9D%97)，从此告别重复写验证码短信发送与校验的历史
- 灵活的[动态验证规则](#4-%E5%8A%A8%E6%80%81%E9%AA%8C%E8%AF%81%E8%A7%84%E5%88%99)
- 可选的[数据库日志](#%E6%95%B0%E6%8D%AE%E5%BA%93%E6%97%A5%E5%BF%97)
- 可选的[短信队列](#%E7%9F%AD%E4%BF%A1%E9%98%9F%E5%88%97)
- 验证码发送与验证模块的[无session支持](#%E6%97%A0%E4%BC%9A%E8%AF%9D%E6%94%AF%E6%8C%81)

### 3. 如何快速开始?

[](#3-如何快速开始)

上面提了这么多特性，那么如何快速上手并体验一下验证码发送与验证呢?只需要依次完成以下三个步骤即可。

- step1: [安装](#%E5%AE%89%E8%A3%85)
- step2: [准备工作](#%E5%87%86%E5%A4%87%E5%B7%A5%E4%BD%9C)
- step3: [验证码模块](#%E9%AA%8C%E8%AF%81%E7%A0%81%E6%A8%A1%E5%9D%97)

公告
==

[](#公告)

- QQ群:159379848
- 旧版本更新到2.6.4+版本时，建议更新原有的`config/laravel-sms.php`和`laravel-sms.js`文件(如果有用到)
- 如果是Laravel 5.1版本，则需要在`config/laravel-sms.php`文件中注释掉`middleware`
- 开发调试过程中，如果需要查看短信发送结果的详细信息，建议打开[数据库日志](#%E6%95%B0%E6%8D%AE%E5%BA%93%E6%97%A5%E5%BF%97)

安装
==

[](#安装)

在项目根目录下运行如下composer命令:

```
//推荐
composer require surpaimb/laravel-sms:~2.6

//安装开发中版本
composer require surpaimb/laravel-sms:dev-master
```

准备工作
====

[](#准备工作)

### 1.注册服务提供器

[](#1注册服务提供器)

在config/app.php文件中providers数组里加入：

```
Surpaimb\PhpSms\PhpSmsServiceProvider::class,
Surpaimb\Sms\SmsManagerServiceProvider::class,
```

在config/app.php文件中的aliases数组里加入

```
'PhpSms' => Surpaimb\PhpSms\Facades\Sms::class,
'SmsManager' => Surpaimb\Sms\Facades\SmsManager::class,
```

### 2.参数配置

[](#2参数配置)

- 生成配置文件和migration文件

```
php artisan vendor:publish --provider="Surpaimb\PhpSms\PhpSmsServiceProvider"
php artisan vendor:publish --provider="Surpaimb\Sms\SmsManagerServiceProvider"
```

> 这里会生成两个配置文件，分别为phpsms.php和laravel-sms.php。

- 配置代理器参数

在config/phpsms.php的`agents`数组中，找到你想要使用的代理器，并填写好配置信息。

- 代理器均衡调度

在config/phpsms.php中设置代理器的均衡调度方案。

```
'scheme' => [
    //被使用概率为2/3
    'Luosimao' => '20',

    //被使用概率为1/3，且为备用代理器
    'YunPian' => '10 backup',

    //仅为备用代理器
    'YunTongXun' => '0 backup',
];
```

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

发送前数据验证
=======

[](#发送前数据验证)

### 1. 声明

[](#1-声明)

当客户端向服务器端请求发送验证码短信/语音时，服务器端需要对接收到的数据(本库将其称为`field`)进行验证，只有在所有需验证的数据都通过了验证才会向第三方服务提供商发起请求。 对于每项你想验证的`field`，不管是使用静态验证规则还是[动态验证规则](#4-%E5%8A%A8%E6%80%81%E9%AA%8C%E8%AF%81%E8%A7%84%E5%88%99)，都需要提前到配置文件(`config/laravel-sms.php`)中声明，并做好必要的配置。

> 本文档中所说的`服务器端`是我们自己的应用系统，而非第三方短信服务提供商。

#### 配置项

[](#配置项)

对于每项数据，都有以下几项可设置:

配置项必填说明isMobile否是否为手机号码enable是是否需要进行验证default否默认静态验证规则staticRules否所有静态验证规则#### 示例

[](#示例)

```
'validation' => [
    //内置的mobile参数的验证配置
    'mobile' => [
        'isMobile'    => true,
        'enable'      => true,
        'default'     => 'mobile_required',
        'staticRules' => [
            'mobile_required' => 'required|zh_mobile',
            ...
        ],
    ],
    //自定义你可能需要验证的字段
    'image_captcha' => [
        'enable' => true,
    ],
],
```

### 2. 使用

[](#2-使用)

静态验证规则和动态验证规则的使用方法一致。

#### 客户端

[](#客户端)

通过`{field}_rule`参数告知服务器`{field}`参数需要使用的验证规则的名称。 比如`mobile_rule`参数可以告知服务器在验证`mobile`参数时使用什么验证规则， `image_captcha_rule`参数可以告知服务器在验证`image_captcha`参数时使用什么验证规则。

#### 服务器端

[](#服务器端)

[示例见此](#3-%E6%9C%8D%E5%8A%A1%E5%99%A8%E7%AB%AF%E5%90%88%E6%B3%95%E6%80%A7%E9%AA%8C%E8%AF%81)

验证码模块
=====

[](#验证码模块)

可以直接访问`http[s]://your-domain/laravel-sms/info`查看该模块是否启用，并可在该页面里观察验证码短信发送状态，方便你进行调试。

> 如果是api应用(无session)需要在上述地址后面加上`?access_token=xxxx`

### 1. \[服务器端\]配置短信内容/模板

[](#1-服务器端配置短信内容模板)

#### 短信内容

[](#短信内容)

如果你使用了内容短信，则需要设置`content`的值。

> 配置文件为config/laravel-sms.php

```
'content' => function ($code, $minutes, $input) {
    return '【signature】您的验证码是' . $code . '，有效期为' . $minutes . '分钟，请尽快验证。';
}
```

#### 模版id

[](#模版id)

如果你使用了模板短信，需要配置到使用到的代理器的模板标示符。

> 配置文件为config/laravel-sms.php

```
'templates' => [
    'YunTongXun' => '短信模版id',
    'Alidayu'    => ['短信模版id', '语音模版id'],
]
```

#### 模版数据

[](#模版数据)

如果你使用了模板短信，需要配置准备使用的模版数据。

> 配置文件为config/laravel-sms.php

```
'data' => [
    'code' => function ($code) {
        return $code;
    },
    ...
],
```

### 2. \[浏览器端\]请求发送验证码短信

[](#2-浏览器端请求发送验证码短信)

该包已经封装好浏览器端的基于jQuery(zepto)的发送插件，只需要为发送按钮添加扩展方法即可实现发送短信。

> js文件在本库的js文件夹中，请复制到项目资源目录。

```

$('#sendVerifySmsButton').sms({
    //laravel csrf token
    token       : "{{csrf_token()}}",
    //请求间隔时间
    interval    : 60,
    //请求参数
    requestData : {
        //手机号
        mobile : function () {
            return $('input[name=mobile]').val();
        },
        //手机号的检测规则
        mobile_rule : 'mobile_required'
    }
});

```

> laravel-sms.js 的更多用法请[见此](#laravel-smsjs)

### 3. \[服务器端\]合法性验证

[](#3-服务器端合法性验证)

用户填写验证码并提交表单到服务器时，在你的控制器中需要验证手机号和验证码是否正确，你只需要加上如下代码即可：

```
use SmsManager;
...

//验证数据
$validator = Validator::make($request->all(), [
    'mobile'     => 'required|confirm_mobile_not_change|confirm_rule:mobile_required',
    'verifyCode' => 'required|verify_code',
    //more...
]);
if ($validator->fails()) {
   //验证失败后建议清空存储的发送状态，防止用户重复试错
   SmsManager::forgetState();
   return redirect()->back()->withErrors($validator);
}
```

> `confirm_mobile_not_change`, `verify_code`, `confirm_rule`的详解请参看[Validator扩展](#validator%E6%89%A9%E5%B1%95)

Validator扩展
===========

[](#validator扩展)

#### zh\_mobile

[](#zh_mobile)

检测标准的中国大陆手机号码。

#### confirm\_mobile\_not\_change

[](#confirm_mobile_not_change)

检测用户提交的手机号是否变更。

#### verify\_code

[](#verify_code)

检测验证码是否合法且有效，如果验证码错误，过期或超出尝试次数都无法验证通过。

#### confirm\_rule:$ruleName

[](#confirm_rulerulename)

检测验证规则是否合法，后面跟的第一个参数为待检测的验证规则的名称。 如果不填写参数`$ruleName`（不写冒号才表示不填写哦），系统会尝试设置其为前一个访问路径的path部分。

数据库日志
=====

[](#数据库日志)

> 开发调试过程中，如果需要查看短信发送结果的详细信息，建议打开数据库日志。

### 1. 生成数据表

[](#1-生成数据表)

运行如下命令在数据库中生成`laravel_sms`表。

```
php artisan migrate
```

### 2. 开启权限

[](#2-开启权限)

在配置文件`config/laravel-sms.php`中设置`dbLogs`为`true`。

```
'dbLogs' => true,
```

短信队列
====

[](#短信队列)

### 1. 启用/关闭队列

[](#1-启用关闭队列)

`laravel-sms`已实现的短信队列默认是关闭的，判断当前队列状态：

```
$enable = PhpSms::queue(); //true of false
```

开启/关闭队列的示例如下：

```
//开启队列:
PhpSms::queue(true);

//关闭队列:
PhpSms::queue(false);
```

如果你开启了队列，需要运行如下命名监听队列

```
php artisan queue:listen
```

### 2. 队列自定义

[](#2-队列自定义)

如果你运行过`php artisan app:name`修改应用名称，或者需要自己实现队列工作逻辑，那么你需要进行自定义队列Job或者自定义队列流程（任选一种）。

- 方式1：自定义队列Job

该方式只需要你自己实现一个Job class，然后在`config/laravel-sms.php`中键为`queueJob`处配置你使用的Job class。 值得注意的是你的Job class构造函数的第一个参数是`Surpaimb\PhpSms\Sms`的实例，发送时你只需要调用他的`send()`方法即可。

- 方式2：自定义队列流程

在发送短信前，你可以完全重新定义你的队列流程！

```
//example:
PhpSms::queue(function($sms, $data){
    //假设如此推入队列:
    $this->dispatch(new YourQueueJobClass($sms));
});
```

无会话支持
=====

[](#无会话支持)

### 1. 服务器端准备

[](#1-服务器端准备)

在`config/laravel-sms.php`中配置路由器组中间件`middleware`。

```
//example:
'middleware' => ['api'],
```

### 2. Access Token

[](#2-access-token)

Access Token值建议设置在请求头中的`Access-Token`上，当然也可以带在请求参数`access_token`中。

> 根据你的实际应用场景，也可考虑将手机号作为`access_token`。

### 3. 请求地址

[](#3-请求地址)

- 短信: `scheme://host/laravel-sms/verify-code`
- 语音: `scheme://host/laravel-sms/voice-verify`

### 4. 默认参数

[](#4-默认参数)

参数名必填说明mobile是手机号码mobile\_rule否手机号检测规则### 5. 响应数据

[](#5-响应数据)

参数名说明success是否请求发送成功type类型message详细信息API
===

[](#api)

`laravel-sms`提供的所有功能都是由该章节的接口和`phpsms`的接口实现的。 虽然通过配置文件可以完成基本所有的常规需求，但是对于更加变态（个性化）的需求， 可能需要在`laravel-sms`的基础上做定制化的开发，在这种情况下阅读该章节或许能给你提供帮助，否则可以忽略该章节。

```
use SmsManager;
```

### 1. 发送前校验

[](#1-发送前校验)

#### validateSendable()

[](#validatesendable)

校验是否可进行发送。如果校验未通过，返回数据中会包含错误信息。

```
$result = SmsManager::validateSendable();
```

#### validateFields(\[$input\]\[, $validation\])

[](#validatefieldsinput-validation)

校验数据合法性。如果校验未通过，返回数据中会包含错误信息。

```
//使用内置的验证逻辑
$result = SmsManager::validateFields();

//自定义验证逻辑
$result = SmsManager::validateFields(function ($fields, $rules) {
    //在这里做你的验证处理，并返回结果...
    //如：
    return Validator::make($fields, $rules);
});
```

### 2. 发送

[](#2-发送)

#### requestVerifySms()

[](#requestverifysms)

请求发送验证码短信。

```
$result = SmsManager::requestVerifySms();
```

#### requestVoiceVerify()

[](#requestvoiceverify)

请求发送语音验证码。

```
$result = SmsManager::requestVoiceVerify();
```

### 3. 发送状态

[](#3-发送状态)

#### state(\[$key\]\[, $default\])

[](#statekey-default)

获取当前的发送状态（非持久化的）。

```
//example:
$state = SmsManager::state();
```

#### retrieveState(\[$key\])

[](#retrievestatekey)

获取持久化存储的发送状态，即存储到`session`或缓存中的状态数据。

```
$state = SmsManager::retrieveState();
```

#### updateState($name, $value)

[](#updatestatename-value)

更新持久化存储的发送状态。

```
SmsManager::updateState('key', 'value');
SmsManager::updateState([
    'key' => 'value'
]);
```

#### forgetState()

[](#forgetstate)

删除持久化存储的发送状态。

```
SmsManager::forgetState();
```

### 4. 动态验证规则

[](#4-动态验证规则)

#### storeRule($field\[, $name\], $rule);

[](#storerulefield-name-rule)

定义客户端数据（字段）的动态验证规则。

```
//方式1:
//如果不设置name，那么name默认为当前访问路径的path部分
SmsManager::storeRule('mobile', 'required|zh_mobile|unique:users,mobile,NULL,id,account_id,1');

//方式2:
SmsManager::storeRule('mobile', 'myRuleName', 'required|zh_mobile|unique:users,mobile,NULL,id,account_id,1');

//方式3
SmsManager::storeRule('mobile', [
    'myRuleName' => 'required|zh_mobile|unique:users,mobile,NULL,id,account_id,1',
    'myRuleName2' => ...,
]);
```

> 存储的动态验证规则可通过访问`http[s]://your-domain/laravel-sms/info`查看。 动态验证规则的名称最好不要和静态验证规则同名,因为静态验证规则的优先级更高。

#### retrieveRule($field\[, $name\])

[](#retrieverulefield-name)

获取字段的指定名称的动态验证规则。

```
$rule = SmsManager::retrieveRule('mobile', 'myRuleName');
```

#### retrieveRules($field)

[](#retrieverulesfield)

获取字段的所有动态验证规则。

```
$rules = SmsManager::retrieveRules('mobile');
```

#### forgetRule($field\[, $name\])

[](#forgetrulefield-name)

删除字段的指定名称的动态验证规则。

```
SmsManager::forgetRule('mobile', 'myRuleName');
```

#### forgetRules($field)

[](#forgetrulesfield)

删除字段的所有动态验证规则。

```
SmsManager::forgetRules('mobile');
```

### 5. 客户端数据

[](#5-客户端数据)

#### input(\[$key\]\[, $default\])

[](#inputkey-default)

获取客户端传递来的数据。客户端数据会自动注入到配置文件(`laravel-sms.php`)中闭包函数的`$input`参数中。

```
$mobileRuleName = SmsManager::input('mobile_rule');
$all = SmsManager::input();
```

### 6. 其它

[](#6-其它)

#### closure($closure)

[](#closureclosure)

序列化闭包。

```
SmsManager::closure(function () {
    //do someting...
});
```

#### laravel-sms.js

[](#laravel-smsjs)

```
$('#sendVerifySmsButton').sms({
    //laravel csrf token
    //该token仅为laravel框架的csrf验证,不是access_token!
    token       : "{{csrf_token()}}",

    //请求时间间隔
    interval    : 60,

    //语音验证码
    voice       : false,

    //请求参数
    requestData : {
        //手机号
        mobile: function () {
            return $('input[name=mobile]').val();
        },
        //手机号的检测规则
        mobile_rule: 'mobile_required'
    },

    //消息展示方式(默认为alert)
    notify      : function (msg, type) {
        alert(msg);
    },

    //语言包
    language    : {
        sending    : '短信发送中...',
        failed     : '请求失败，请重试',
        resendable : '{{seconds}} 秒后再次发送'
    }
});
```

License
=======

[](#license)

MIT

###  Health Score

15

—

LowBetter than 3% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity0

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity30

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/db9f9ae93fc176f3ec8de00c0f6cccda365a5e0b2a01192fc6373663667a7bb7?d=identicon)[surpaimb](/maintainers/surpaimb)

### Embed Badge

![Health badge](/badges/surpaimb-laravel-sms/health.svg)

```
[![Health](https://phpackages.com/badges/surpaimb-laravel-sms/health.svg)](https://phpackages.com/packages/surpaimb-laravel-sms)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)