Easy SMS

https://github.com/overtrue/easy-sms
Admin
Easy SMS is a multi-channel SMS sending component for PHP that supports more than 40 service...
Tokens:70,745
Snippets:439
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### EasySms Usage Example

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/EasySms.md

Demonstrates initializing the EasySms instance with configuration and sending a message, including an example of overriding gateway settings during the call.

```php
use Overtrue\EasySms\EasySms;

$easySms = new EasySms([
    'timeout' => 5.0,
    'default' => [
        'strategy' => \Overtrue\EasySms\Strategies\OrderStrategy::class,
        'gateways' => ['yunpian', 'aliyun'],
    ],
    'gateways' => [
        'yunpian' => ['api_key' => '...'],
        'aliyun'  => ['access_key_id' => '', 'access_key_secret' => '', 'sign_name' => ''],
    ],
]);

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

// 发送时覆盖网关及配置
$easySms->send(13188888888, $message, ['yunpian' => ['signature' => '【示例】']]);
```

--------------------------------

### Install easy-sms with Composer

Source: https://github.com/overtrue/easy-sms/wiki/Home

Install the easy-sms package via Composer. Run this in your terminal.

```shell
$ composer require "overtrue/easy-sms"
```

--------------------------------

### ChuanglanGateway: configuration example

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Gateways-Core.md

Example configuration for the Chuanglan gateway, including international account credentials, channel, sign, and unsubscribe text. For the promotional channel, sign and unsubscribe are required.

```php
'chuanglan' => [
    'account'  => '...',
    'password' => '...',
    'intel_account'  => '...',   // 国际短信时必填
    'intel_password' => '...',
    'channel' => \Overtrue\EasySms\Gateways\ChuanglanGateway::CHANNEL_VALIDATE_CODE,
    'sign' => '【通讯云】',       // 营销通道必填
    'unsubscribe' => '回TD退订',  // 营销通道必填
],
```

--------------------------------

### Send SMS via Volcengine with Template (Example 2)

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Second example of sending an SMS using the Volcengine gateway with a template ID and data parameters. Allows overriding signature, account, and phone numbers.

```php
$easySms->send(18888888888, [
    'template' => 'SMS_123456', // 模板ID
    'data' => [
        "template_param" => ["code" => 1234], // 模板变量参数
        "sign_name" => "yoursignname", // 签名，覆盖配置文件中的sign_name
        "sms_account" => "yoursmsaccount", // 消息组帐号，覆盖配置文件中的sms_account
        "phone_numbers" => "18888888888,18888888889", // 手机号，批量发送，英文的逗号连接多个手机号，覆盖发送方法中的填入的手机号
    ],
]);
```

--------------------------------

### Send SMS via Volcengine with Template (Example 1)

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

First example of sending an SMS using the Volcengine gateway with a template ID and data parameters. The data array contains a single template variable.

```php
$easySms->send(18888888888, [
    'template' => 'SMS_123456', // 模板ID
    'data' => [
       "code" => 1234 // 模板变量
    ],
]);
```

--------------------------------

### Usage example: creating PhoneNumber instances

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/PhoneNumber.md

Shows how to create PhoneNumber objects for domestic and international numbers, including with explicit IDD code or with a '+' prefix. The example also demonstrates passing the number to EasySms::send.

```php
use Overtrue\EasySms\PhoneNumber;

// 国内号码：直接字符串即可（EasySms::send 内部会转换）
$number = new PhoneNumber(13188888888);

// 国际号码：显式区号
$number = new PhoneNumber(13188888888, 31);   // 荷兰区号
// 或带 + 前缀
$number = new PhoneNumber('+8618888888888');

$easySms->send($number, ['content' => 'Hello']);
```

--------------------------------

### Direct usage example with errorlog gateway

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Messenger.md

Demonstrates directly instantiating Messenger and sending a message with the errorlog gateway, showing the expected success result structure.

```php
use Overtrue\EasySms\EasySms;
use Overtrue\EasySms\PhoneNumber;
use Overtrue\EasySms\Message;
use Overtrue\EasySms\Messenger;

$easySms = new EasySms([
    'default' => ['gateways' => ['errorlog']],
    'gateways' => ['errorlog' => ['file' => '/tmp/easy-sms.log']],
]);

$results = (new Messenger($easySms))->send(
    new PhoneNumber(13188888888),
    new Message(['content' => '您的验证码为: 6379']),
    $easySms->getMessenger() && $easySms->strategy()->apply(['errorlog' => []]),
);
// $results['errorlog']['status'] === Messenger::STATUS_SUCCESS
// $results['errorlog']['result']  === ['status' => true, 'file' => '/tmp/easy-sms.log']
```

--------------------------------

### Moduyun send example

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Send a message using the moduyun gateway. The 'template' is the template ID and 'data' provides values for placeholders.

```php
$easySms->send(18888888888, [
    'template' => '5a95****b953',   //短信模板
    'data' => [
        1234,   //模板参数，对应模板的{1}
        30      //模板参数，对应模板的{2}
        //...
    ],
]);
```

--------------------------------

### Usage example: method outputs and gateway formatting

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/PhoneNumber.md

Demonstrates the output of each getter method and json_encode. Notes that different gateways require different number formats (e.g., aliyun uses zero-prefixed, twilio uses universal format) and that each gateway's send() internally calls the appropriate getter.

```php
use Overtrue\EasySms\PhoneNumber;

$number = new PhoneNumber('18888888888', '86');

echo $number->getIDDCode();                // 86
echo $number->getNumber();                 // 18888888888
echo $number->getUniversalNumber();        // +8618888888888
echo $number->getZeroPrefixedNumber();     // 008618888888888
echo $number->getPrefixedIDDCode('+');     // +86
echo $number;                              // +8618888888888
var_dump($number->inChineseMainland());    // true
echo json_encode($number);                 // "+8618888888888"

// 不同网关对号码格式要求不同（如 aliyun 用零前缀，twilio 用 + 通用格式），
// 各网关 send() 内部自行调用对应 getter，无需手动转换。
```

--------------------------------

### Kingtto send example

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Send a message using the kingtto gateway with the 'content' field.

```php
$easySms->send(18888888888, [
    'content'  => '您的验证码为: 6379',
]);
```

--------------------------------

### Qiniu send example

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Send a message using the qiniu gateway. The 'template' is the template ID and 'data' provides values for placeholders.

```php
$easySms->send(18888888888, [
    'template' => '1231234123412341234',
    'data' => [
        'code' => 1234,
    ],
]);
```

--------------------------------

### get method signature of Config

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Config.md

Signature for the get method, which retrieves a value by key with dot-notation support. The default value is returned if the key is not found.

```php
public function get(string $key, mixed $default = null): mixed
```

--------------------------------

### Tencent Cloud SMS send example

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Send a message using the qcloud gateway. The 'template' is the template ID and 'data' provides values for placeholders in order.

```php
$easySms->send(18888888888, [
    'template' => 101234, // 模板ID
    'data' => [
        "a", 'b', 'c', 'd', //按占位顺序给值
    ],
]);
```

--------------------------------

### Yunzhixun send example

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Send a message using the yunzhixun gateway. The 'data' array supports 'params' (comma-separated), 'uid', and optional 'mobiles' for batch sending.

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

--------------------------------

### Smsbao send example

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Send a message using the smsbao gateway with the 'content' field.

```php
$easySms->send(18888888888, [
    'content' => '您的验证码为: 6379',       //短信模板
]);
```

--------------------------------

### Return array structure example

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Messenger.md

Shows the shape of the return value: an array keyed by gateway name, each entry containing 'gateway', 'status', 'template', and either 'result' or 'exception'.

```php
[
    'yunpian' => [
        'gateway'  => 'yunpian',                       // string
        'status'   => 'success',                       // Messenger::STATUS_SUCCESS
        'template' => 'SMS_001',                       // $message->getTemplate(该网关实例)
        'result'   => [ /* 平台原始响应 */ ],            // 网关 send() 返回值
    ],
    'aliyun'  => [
        'gateway'  => 'aliyun',
        'status'   => 'failure',                       // Messenger::STATUS_FAILURE
        'template' => 'SMS_001',
        'exception'=> /* \Throwable 实例 */,
    ],
]
```

--------------------------------

### Send SMS via Weiqucloud with Content

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Example of sending an SMS using the Weiqucloud gateway with a content string. The content includes the message text.

```php
$easySms->send(18888888888, [
    'content'  =>"【已备案签名】您的验证码是 xx。",
]);
```

--------------------------------

### Ucloud send example

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Send a message using the ucloud gateway. The 'template' is the template ID and 'data' provides values for placeholders, including optional 'mobiles' for batch sending.

```php
$easySms->send(18888888888, [
    'template' => 'UTAXXXXX',       //短信模板
    'data' => [
        'code' => 1234,     //模板参数，模板没有参数不用则填写，有多个参数请用数组，[1111,1111]
        'mobiles' =>'',     //同时发送多个手机短信，请用数组[xxx,xxx]
    ],
]);
```

--------------------------------

### Send SMS via ZhiZhuYun with Template

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Example of sending an SMS using the ZhiZhuYun gateway with a template ID and data parameters. The data array maps template variables to values.

```php
$easySms->send(18888888888, [
    'template' => 'SMS_210317****',   //短信模板
    'data' => [
        'code' => '888888',   //模板参数，对应模板的{code}
        //...
    ],
]);
```

--------------------------------

### Yunxin send template notification example

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Send a template notification using the yunxin gateway. The 'action' must be 'sendTemplate' and 'params' provides values for template placeholders.

```php
$easySms->send(18888888888, [
    'template' => 'templateid',    // 模板编号(由客户顾问配置之后告知开发者)
    'data' => [
        'action' => 'sendTemplate', // 默认为 `sendCode`，校验短信验证码使用 `verifyCode`
        'params' => [1,2,3], //短信参数列表，用于依次填充模板
    ],
]);
```

--------------------------------

### Send SMS via Miaoxin with Custom Content

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Example of sending an SMS using the Miaoxin gateway with a custom content string. The content includes the message text.

```php
$easySms->send(18888888888, [
    'content'  => '【秒信】您的验证码是 6379，5 分钟内有效。',
]);
```

--------------------------------

### ArrayAccess behavior of Config (offsetSet and offsetUnset constraints)

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Config.md

Demonstrates how ArrayAccess methods behave: offsetExists checks only top-level keys without dot-notation, offsetGet delegates to get(), offsetSet only updates existing keys, and offsetUnset only deletes existing keys. Shows that setting a new key is silently ignored.

```php
use Overtrue\EasySms\Support\Config;

$config = new Config(['foo' => 'bar']);

var_dump(isset($config['foo']));      // true  （offsetExists）
echo $config['foo'];                  // 'bar' （offsetGet 走 get()）
$config['foo'] = 'baz';               // offsetSet：键存在，更新
$config['new_key'] = 'x';             // offsetSet：键不存在，被忽略
unset($config['foo']);                // offsetUnset：删除
```

--------------------------------

### Yunxin send verification code example

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Send a verification code using the yunxin gateway. The 'code' parameter overrides code_length; 'action' defaults to 'sendCode' and can be 'verifyCode' for verification.

```php
$easySms->send(18888888888, [
    'template' => 'SMS_001',    // 不填则使用默认模板
    'data' => [
        'code' => 8946, // 如果设置了该参数，则 code_length 参数无效
        'action' => 'sendCode', // 默认为 `sendCode`，校验短信验证码使用 `verifyCode`
    ],
]);
```

--------------------------------

### Send SMS via Rongheyun with Template

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Example of sending an SMS using the Rongheyun gateway with a template ID and data parameters. The data array maps template variables to values.

```php
$easySms->send(18888888888, [
    'template' => '31874',   //短信模板
    'data' => [
        'valid_code' => '888888',   //模板参数，对应模板的{valid_code}
        //...
    ],
]);
```

--------------------------------

### Send SMS via Ctyun with Content and Template

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Example of sending an SMS using the Ctyun gateway with content, template ID, and data parameters. The data array contains a code variable.

```php
$easySms->send(18888888888, [
    'content' => $content,
    'template' => 'SMS64124870510', // 模板ID
    'data' => [
        "code" => 123456,
    ],
]);
```

--------------------------------

### Send SMS with YunxinGateway

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Gateways-Simple.md

Example of sending an SMS using the Yunxin gateway. The 'data' array includes 'code' and 'action' (default 'sendCode'); other actions 'verifyCode' and 'sendTemplate' work similarly.

```php
$easySms->send(18888888888, [
    'template' => 'SMS_001',
    'data' => ['code' => 8946, 'action' => 'sendCode'],   // verifyCode / sendTemplate 同理
]);
```

--------------------------------

### Send SMS via Miaoxin with Template

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Example of sending an SMS using the Miaoxin gateway with a template ID and data parameters. The data array is a list of values filled in template parameter order.

```php
$easySms->send(18888888888, [
    'template' => '模板ID',
    'data' => [
        '1234', // 对应模板的 param1、param2…按顺序填充，最多 8 个
        '张三',
    ],
]);
```

--------------------------------

### Create and use a Config instance with dot notation

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Config.md

Shows how to instantiate Config and retrieve values using dot-notation. Demonstrates fallback default values for missing keys.

```php
use Overtrue\EasySms\Support\Config;

$config = new Config([
    'timeout' => 5.0,
    'default' => [
        'strategy' => \Overtrue\EasySms\Strategies\OrderStrategy::class,
        'gateways' => ['yunpian'],
    ],
]);

echo $config->get('timeout');                          // 5.0
echo $config->get('default.strategy');                 // 点号下钻
echo $config->get('gateways.aliyun.timeout', 5.0);     // 兜底 5.0
```

--------------------------------

### Gateway::__construct(array $config)

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Gateway.md

Constructor that accepts a configuration array and wraps it in a Support\Config instance.

```APIDOC
## Gateway::__construct(array $config)

### Description
Initializes the gateway with a configuration array, typically passed from EasySms::createGateway(). The config is wrapped in a Support\Config object.

### Method
Constructor

### Parameters
- **$config** (array) - Required - Gateway configuration array, usually containing 'timeout' and 'options' keys.

### Request Example
```php
$gateway = new \Overtrue\EasySms\Gateways\YunpianGateway([
    'api_key'  => '...',
    'timeout'  => 5.0,
    'options'  => ['verify' => false],
]);
```

### Response
No return value.
```

--------------------------------

### Config::offsetGet

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Config.md

Retrieves a configuration value via array access, supporting dot notation through delegation to get().

```APIDOC
## Config::offsetGet

### Description
Retrieves a configuration value using array access, delegating to the `get` method and thus supporting dot notation.

### Method
offsetGet

### Signature
```php
public function offsetGet(mixed $offset): mixed
```

### Parameters
- **$offset** (mixed) - Required - The key to retrieve, supporting dot notation.

### Return Value
- (mixed) - The configuration value.

### Usage Example
```php
echo $config['foo']; // 'bar'
```

```

--------------------------------

### Configure sending strategy with strategy()

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/EasySms.md

The strategy method retrieves a strategy instance. If no argument is provided, it defaults to the configuration setting or OrderStrategy.

```php
$strategy = $easySms->strategy();                       // 配置默认策略
$strategy = $easySms->strategy('random');               // Overtrue\EasySms\Strategies\RandomStrategy
$order = $strategy->apply(['yunpian' => [], 'aliyun' => []]);
```

--------------------------------

### Gateway constructor accepts config array

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Gateway.md

Constructor that wraps the provided configuration array into a Support\Config instance. The array typically comes from EasySms::createGateway() and already contains timeout and options keys.

```php
public function __construct(array $config)
```

--------------------------------

### Direct gateway usage with YunpianGateway

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Gateway.md

Shows how to use a gateway directly without the EasySms facade. Constructs a YunpianGateway with configuration and calls send() with a PhoneNumber, Message, and the gateway's Config. This bypasses EasySms's validation and singleton caching.

```php
use Overtrue\EasySms\Support\Config;
use Overtrue\EasySms\PhoneNumber;
use Overtrue\EasySms\Message;

// 直接使用某个网关（绕过 EasySms 门面）
$gateway = new \Overtrue\EasySms\Gateways\YunpianGateway([
    'api_key'  => '...',
    'timeout'  => 5.0,
    'options'  => ['verify' => false],
]);

$result = $gateway->send(
    new PhoneNumber('18888888888', '86'),
    new Message(['content' => '您的验证码为: 6379']),
    $gateway->getConfig()
);
```

--------------------------------

### getConfig(): Config

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/EasySms.md

Returns the configuration instance for the EasySms client.

```APIDOC
## getConfig(): Config

### Description
Returns the `Support\Config` instance holding the complete configuration. The config can be accessed using dot notation.

### Method
GET

### Endpoint
`getConfig()`

### Parameters
None.

### Response
#### Success Response (200)
- **Config** (Support\Config) - The configuration instance.

#### Response Example
```json
{
  "config": "Support\\Config instance"
}
```
```

--------------------------------

### Gateway::getConfig()

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Gateway.md

Returns the current Config instance.

```APIDOC
## Gateway::getConfig()

### Description
Returns the Support\Config instance holding the gateway configuration.

### Method
Getter

### Parameters
None

### Response
- **Config** (Support\Config) - The configuration object.
```

--------------------------------

### Configure and send SMS with EasySms and YunPian

Source: https://github.com/overtrue/easy-sms/wiki/GateWays---YunPian

Shows how to set up the EasySms configuration with an error-log gateway and a YunPian gateway, then send a message using the error-log gateway.

```php
use Overtrue\EasySms\EasySms;

$config = [
    'default' => 'error-log',
    'gateways' => [
        /*...*/
        'error-log' => [
            'file' => '/tmp/easy-sms.log',
        ],
        /*...*/
        'yun-pian' => [
            'api_key' => 'xxxxxxxxxxxxxx',
        ],
    ],
];

$easySms = new EasySms($config);

$easySms->gateway('error-log')->send(19188888888, 'hello world!');
```

--------------------------------

### Gateway::setConfig(Config $config)

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Gateway.md

Replaces the configuration object and returns the gateway instance.

```APIDOC
## Gateway::setConfig(Config $config)

### Description
Sets a new Support\Config instance as the gateway configuration. Returns the gateway instance for chaining.

### Method
Setter

### Parameters
- **$config** (Support\Config) - Required - The new configuration object.

### Response
- **$this** (Gateway) - The current gateway instance.
```

--------------------------------

### Config::__construct

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Config.md

Constructor for the Config class, accepting an optional initial configuration array.

```APIDOC
## Config::__construct

### Description
Initializes a new Config instance with an optional initial configuration array.

### Method
__construct

### Signature
```php
public function __construct(array $config = [])
```

### Parameters
- **$config** (array) - Optional - Initial configuration array. Defaults to `[]`.

### Usage Example
```php
$config = new Config(['timeout' => 5.0]);
```

```

--------------------------------

### request() method

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/HasHttpRequest.md

The core request method that dynamically calls the Guzzle client method (e.g., get, post) and unwraps the response. It is protected and used internally by the trait.

```php
protected function request($method, $endpoint, $options = [])
{
    return $this->unwrapResponse($this->getHttpClient($this->getBaseOptions())->{$method}($endpoint, $options));
}
```

--------------------------------

### 容联云通讯配置

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

容联云通讯短信网关配置，使用 template + data 发送短信。需配置 app_id、account_sid、account_token 和 is_sub_account。

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

--------------------------------

### Send SMS via Maap with Template

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Example of sending an SMS using the Maap gateway with a template ID and data parameters. The data array is a list of values for template parameters.

```php
$easySms->send(18888888888, [
    'template' => '356120',   //短信模板
    'data' => [
        '123465'
    ],//模板参数
]);
```

--------------------------------

### 华信短信平台配置

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

华信短信平台网关配置，使用 content 发送短信。需配置 user_id、password、account、ip 和 ext_no。

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

--------------------------------

### Yunzhixun configuration

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Configure the yunzhixun gateway with sid, token, and app_id. Messages use 'template' and 'data'.

```php
    'yunzhixun' => [
        'sid' => '',
        'token' => '',
        'app_id' => '',
    ],
```

--------------------------------

### Handling NoGatewayAvailableException

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Exceptions.md

Catches a `NoGatewayAvailableException` when all gateways fail. Access the fixed error message, iterate over per-gateway exceptions, get the last failure, and retrieve a specific gateway's exception if it exists.

```php
use Overtrue\EasySms\EasySms;
use Overtrue\EasySms\Exceptions\NoGatewayAvailableException;

try {
    $easySms->send(13188888888, $message);
} catch (NoGatewayAvailableException $e) {
    echo $e->getMessage();                     // 固定提示，详见 getExceptions()
    foreach ($e->getExceptions() as $name => $exception) {
        // $exception 可能是 GatewayErrorException、InvalidArgumentException 等
    }
    $last = $e->getLastException();            // 最后失败的异常
    $yunpian = $e->getException('yunpian');    // 指定网关，不存在则 null
}
```

--------------------------------

### Config::get

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Config.md

Retrieves a configuration value by key, supporting dot notation for nested keys and a default fallback.

```APIDOC
## Config::get

### Description
Retrieves a configuration value by key, supporting dot notation for nested keys. Returns a default value if the key is not found.

### Method
get

### Signature
```php
public function get(string $key, mixed $default = null): mixed
```

### Parameters
- **$key** (string) - Required - The key to retrieve, supporting dot notation (e.g., `'gateways.aliyun.timeout'`).
- **$default** (mixed) - Optional - The default value to return if the key is not found. Defaults to `null`.

### Return Value
- (mixed) - The configuration value if found, otherwise the default value.

### Usage Example
```php
echo $config->get('timeout');                          // 5.0
echo $config->get('default.strategy');                 // dot notation
echo $config->get('gateways.aliyun.timeout', 5.0);     // fallback 5.0
```

```

--------------------------------

### EasySms Error Handling

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/EasySms.md

Shows how to catch NoGatewayAvailableException and iterate through individual gateway exceptions.

```php
// 错误处理
use Overtrue\EasySms\EasySms;
use Overtrue\EasySms\Exceptions\NoGatewayAvailableException;

try {
    $easySms->send(13188888888, $message);
} catch (NoGatewayAvailableException $e) {
    foreach ($e->getExceptions() as $gateway => $exception) {
        error_log("{$gateway}: {$exception->getMessage()}");
    }
}
```

--------------------------------

### Extend EasySms with custom gateways using extend()

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/EasySms.md

Register a custom gateway by providing a name and a closure that returns a GatewayInterface instance. Once registered, the gateway can be used in the default configuration.

```php
$easySms->extend('mygateway', function (array $gatewayConfig) {
    return new MyGateway($gatewayConfig);
});

$easySms->send(13188888888, $message); // 'mygateway' 已在 default.gateways 中
```

--------------------------------

### Send SMS via Tinree with Template

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Example of sending an SMS using the Tinree gateway with a template ID and data parameters. The data array is a list of values filled in template variable order.

```php
$easySms->send(18888888888, [
    'template' => '123456', // 模板ID
    'data' => [
        "a", 'b', 'c', //按模板变量占位顺序
    ],
]);
```

--------------------------------

### 云片配置

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

云片短信网关配置，使用 content 发送短信。需配置 api_key 和 signature（默认签名）。

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

--------------------------------

### getName derives gateway name from class

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Gateway.md

Derives the gateway name by removing the namespace prefix and 'Gateway' suffix from the class name, then lowercasing. For example, AliyunGateway becomes 'aliyun' and ErrorlogGateway becomes 'errorlog'. TwilioGateway overrides this to return a fixed 'twilio'.

```php
public function getName()
{
    return \strtolower(str_replace([__NAMESPACE__.'\\', 'Gateway'], '', \get_class($this)));
}
```

--------------------------------

### 互亿无线配置

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

互亿无线短信网关配置，使用 content 发送短信。需配置 api_id、api_key 和 signature。

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

--------------------------------

### Custom gateway using postJson

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/HasHttpRequest.md

Example of a custom gateway that extends the base Gateway class, which already includes the HasHttpRequest trait and the getGuzzleOptions hook. It uses postJson to send an SMS and checks the decoded response for a non-zero code to throw a GatewayErrorException.

```php
// 自定义网关中使用（继承 Gateway 即自带本 trait 与 getGuzzleOptions 钩子）
use Overtrue\EasySms\Gateways\Gateway;
use Overtrue\EasySms\Contracts\MessageInterface;
use Overtrue\EasySms\Contracts\PhoneNumberInterface;
use Overtrue\EasySms\Support\Config;

class MyGateway extends Gateway
{
    public function send(PhoneNumberInterface $to, MessageInterface $message, Config $config)
    {
        $result = $this->postJson('https://example.com/sms', [
            'mobile'  => $to->getUniversalNumber(),
            'content' => $message->getContent($this),
        ]);

        // $result 已是解码后的数组/字符串；处理平台失败：
        if (($result['code'] ?? 0) !== 0) {
            throw new \Overtrue\EasySms\Exceptions\GatewayErrorException($result['msg'], $result['code'], $result);
        }

        return $result;
    }
}
```

--------------------------------

### 螺丝帽配置

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

螺丝帽短信网关配置，使用 content 发送短信。需配置 api_key。

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

--------------------------------

### EasySms::__construct(array $config)

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/EasySms.md

Constructor for the EasySms class. Accepts a configuration array that is wrapped into a Config object.

```APIDOC
## EasySms::__construct(array $config)

### Description
Initializes the EasySms instance with the provided configuration array.

### Method
Constructor

### Signature
```php
public function __construct(array $config)
```

### Parameters
- **$config** (array) - Required - Complete configuration array. See configuration.md for details. Internally wrapped as `new Config($config)`.

### Request Example
```php
$easySms = new EasySms([
    'timeout' => 5.0,
    'default' => [
        'strategy' => \Overtrue\EasySms\Strategies\OrderStrategy::class,
        'gateways' => ['yunpian', 'aliyun'],
    ],
    'gateways' => [
        'yunpian' => ['api_key' => '...'],
        'aliyun'  => ['access_key_id' => '', 'access_key_secret' => '', 'sign_name' => ''],
    ],
]);
```

### Response
No return value.
```

--------------------------------

### 创蓝云智配置

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

创蓝云智网关配置，使用 content 发送普通短信。需配置 account、password、needstatus 和 channel（验证码通道）。

```php
    'chuanglanv1' => [
        'account' => '',
        'password' => '',
        'needstatus' => false,
        'channel' => \Overtrue\EasySms\Gateways\Chuanglanv1Gateway::CHANNEL_NORMAL_CODE,
    ],
```

--------------------------------

### Constructor signature of Config

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Config.md

Defines the constructor for the Config class, accepting an optional array of initial configuration values. The parameter defaults to an empty array.

```php
public function __construct(array $config = [])
```

--------------------------------

### Retrieve a gateway instance with gateway()

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/EasySms.md

Use the gateway method to obtain a GatewayInterface instance. The name parameter supports both hyphens and underscores for naming conventions.

```php
$gateway = $easySms->gateway('aliyun');     // Overtrue\EasySms\Gateways\AliyunGateway
$gateway = $easySms->gateway('error-log');  // 命名规则容忍 -、_
```

--------------------------------

### Gateway::getGuzzleOptions()

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Gateway.md

Returns the Guzzle options, prioritizing explicitly set options, otherwise the gateway config 'options'.

```APIDOC
## Gateway::getGuzzleOptions()

### Description
Returns the Guzzle request options. The value is determined by: explicitly set options via setGuzzleOptions(), otherwise the gateway config 'options' (merged from top-level options by createGateway()).

### Method
Getter

### Parameters
None

### Response
- **options** (array) - The Guzzle options array.
```

--------------------------------

### 创蓝云智变量短信配置

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

创蓝云智变量短信网关配置，使用 template + data 发送短信。需配置 account、password、needstatus 和 channel（变量通道）。

```php
    'chuanglanv1' => [
        'account' => '',
        'password' => '',
        'needstatus' => false,
        'channel' => \Overtrue\EasySms\Gateways\Chuanglanv1Gateway::CHANNEL_VARIABLE_CODE,
    ],
```

--------------------------------

### 捕获 EasySms 发送异常（NoGatewayAvailableException / InvalidArgumentException / GatewayErrorException）

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/errors.md

捕获多网关发送时的 NoGatewayAvailableException 和配置错误 InvalidArgumentException，以及直接调用单个网关时的 GatewayErrorException。注意：Messenger::send() 内部会捕获任意异常记录为 failure，因此多网关流程中单个网关的异常不会直接冒泡，而是汇总进 NoGatewayAvailableException::getExceptions()。

```php
use Overtrue\EasySms\EasySms;
use Overtrue\EasySms\Exceptions\NoGatewayAvailableException;

$easySms = new EasySms($config);

try {
    $results = $easySms->send(13188888888, [
        'content'  => '您的验证码为: 6379',
        'template' => 'SMS_001',
        'data'     => ['code' => 6379],
    ]);
} catch (NoGatewayAvailableException $e) {
    // 全部网关失败：每个网关的失败详情
    $e->getResults();              // 完整结果数组（结构与 Messenger 返回一致）
    $e->getExceptions();           // gateway => exception 映射
    $e->getException('yunpian');   // 单个网关异常（GatewayErrorException 等）
    $e->getLastException();        // 最后失败的异常
} catch (\Overtrue\EasySms\Exceptions\InvalidArgumentException $e) {
    // 配置错误（不存在的网关名、非法策略、网关参数缺失等）
}

// 直接调用单个网关时，平台错误以 GatewayErrorException 传播：
try {
    $easySms->gateway('aliyun')->send($phoneNumber, $message, $config);
} catch (\Overtrue\EasySms\Exceptions\GatewayErrorException $e) {
    $e->getMessage();  // 平台错误描述
    $e->getCode();     // 平台错误码
    $e->raw;           // 平台原始响应（公开属性）
}
```

--------------------------------

### 天毅无线配置

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

天毅无线短信网关配置，使用 content 发送短信。需配置 username、password 和 gwid。

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

--------------------------------

### 聚合数据配置

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

聚合数据短信网关配置，使用 template + data 发送短信。需配置 app_key。

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

--------------------------------

### strategy()

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/EasySms.md

Resolves and returns a strategy instance by name or the configured default.

```APIDOC
## `strategy(?string $strategy = null): StrategyInterface`

### Description
Gets the strategy instance based on the provided strategy name or the configured default. Resolves the strategy class by checking the exact class name, then the `Overtrue\EasySms\Strategies` namespace, and throws an `InvalidArgumentException` if not found. The instance is cached by class name.

### Signature
`strategy(?string $strategy = null): StrategyInterface`

### Parameters
- **$strategy** (`?string`) - Optional - The strategy name. Defaults to the configured `default.strategy`, or `OrderStrategy::class` if not set.

### Returns
`StrategyInterface` instance.

### Exceptions
- `InvalidArgumentException` - With message `"Unsupported strategy \"...\""` if the strategy class cannot be resolved.

### Example
```php
$strategy = $easySms->strategy();                       // Configured default strategy
$strategy = $easySms->strategy('random');               // Overtrue\EasySms\Strategies\RandomStrategy
$order = $strategy->apply(['yunpian' => [], 'aliyun' => []]);
```

```

--------------------------------

### 融云配置

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

融云短信网关配置，使用 template + data 发送验证类短信。需配置 app_key 和 app_secret。

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

--------------------------------

### 直接实例化 RandomStrategy 使用

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Strategies.md

独立使用 RandomStrategy 的 apply 方法，传入网关映射，返回随机排列的网关名数组。

```php
// 直接实例化使用
use Overtrue\EasySms\Strategies\RandomStrategy;

$order = (new RandomStrategy())->apply([
    'yunpian' => ['api_key' => '...'],
    'aliyun'  => ['access_key_id' => '...'],
]);
// 返回类似 ['aliyun', 'yunpian'] 的随机排列
```

--------------------------------

### Constructor signature for Messenger

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/Messenger.md

The constructor accepts an EasySms instance, which is used in send() to retrieve or create gateways via $this->easySms->gateway($gateway).

```php
public function __construct(EasySms $easySms)
```

--------------------------------

### extend()

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/EasySms.md

Registers a custom gateway with a closure factory for later use.

```APIDOC
## `extend(string $name, \Closure $callback): static`

### Description
Registers a custom gateway via a closure factory. The factory receives the gateway configuration (including merged `timeout` and `options`) and must return a `GatewayInterface` instance. Returns `$this` for chaining.

### Signature
`extend(string $name, \Closure $callback): static`

### Parameters
- **$name** (`string`) - Required - The custom gateway name.
- **$callback** (`\Closure`) - Required - Factory closure that receives an array configuration and returns a `GatewayInterface`.

### Returns
`$this` (static) for fluent chaining.

### Throws
- `InvalidArgumentException` - If the factory does not return a `GatewayInterface` (raised by `createGateway()`).

### Example
```php
$easySms->extend('mygateway', function (array $gatewayConfig) {
    return new MyGateway($gatewayConfig);
});

$easySms->send(13188888888, $message); // 'mygateway' is already in default.gateways
```

```

--------------------------------

### getBaseOptions() method

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/HasHttpRequest.md

Builds the base Guzzle options by merging the optional getGuzzleOptions() hook with base_uri and timeout (default 5.0). It checks for the existence of getBaseUri() and getTimeout() methods.

```php
protected function getBaseOptions()
{
    $options = method_exists($this, 'getGuzzleOptions') ? $this->getGuzzleOptions() : [];

    return \array_merge($options, [
        'base_uri' => method_exists($this, 'getBaseUri') ? $this->getBaseUri() : '',
        'timeout' => method_exists($this, 'getTimeout') ? $this->getTimeout() : 5.0,
    ]);
}
```

--------------------------------

### 百度云配置

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

百度云短信网关配置，使用 template + data 发送短信。需配置 ak、sk、invoke_id 和 domain。

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

--------------------------------

### gateway()

Source: https://github.com/overtrue/easy-sms/blob/master/_autodocs/api-reference/EasySms.md

Retrieves a cached gateway instance by name, creating it on first access.

```APIDOC
## `gateway(?string $name): GatewayInterface`

### Description
Gets or creates and caches a gateway instance by its name. Throws an `InvalidArgumentException` if the gateway class does not exist or does not implement the required interface.

### Signature
`gateway(?string $name): GatewayInterface`

### Parameters
- **$name** (`?string`) - Required - The gateway name (e.g., `'aliyun'`).

### Returns
`GatewayInterface` instance.

### Exceptions
- `InvalidArgumentException` - If the gateway class does not exist or does not implement the required interface.

### Example
```php
$gateway = $easySms->gateway('aliyun');     // Overtrue\EasySms\Gateways\AliyunGateway
$gateway = $easySms->gateway('error-log');  // Naming tolerates - and _
```

```

--------------------------------

### Kingtto configuration

Source: https://github.com/overtrue/easy-sms/blob/master/README.md

Configure the kingtto gateway with userid, account, and password. Messages use the 'content' field.

```php
    'kingtto'  => [
        'userid'   => '',
        'account'  => '',
        'password' => '',
    ],
```
Tokens:
Raw