README

Laravel SMS是一个包，它提供了一个简单灵活的方式来从您的Laravel应用程序发送短信消息。它支持多个短信服务提供商，并允许您轻松地在它们之间切换。

安装

您可以通过运行以下命令使用composer安装此软件包：

composer require "alhaji-aki/laravel-sms"

配置

安装完成后，软件包将自动注册自己。运行以下命令以发布配置文件：

php artisan vendor:publish --provider="AlhajiAki\Sms\SmsServiceProvider"

这将在您的配置文件夹中创建一个sms.php文件，您可以在其中配置您的短信服务提供商和其他设置。配置文件如下所示

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Default Sender
    |--------------------------------------------------------------------------
    |
    | This option controls the default sms sender that is used to send all text
    | messages unless another sender is explicitly specified when sending
    | the message. All additional senders can be configured within the
    | "senders" array. Examples of each type of senders are provided.
    |
    */

    'default' => env('SMS_SENDER', 'log'),

    /*
    |--------------------------------------------------------------------------
    | Global "From" Address
    |--------------------------------------------------------------------------
    |
    | You may wish for all text messages sent by your application to be sent from
    | the same address. Here you may specify a name and address that is
    | used globally for all messages that are sent by your application.
    |
    */

    'from' => env('SMS_FROM_NAME', 'Example'),

    /*
    |--------------------------------------------------------------------------
    | Sender Configurations
    |--------------------------------------------------------------------------
    |
    | Here you may configure all of the senders used by your application plus
    | their respective settings. Several examples have been configured for
    | you and you are free to add your own as your application requires.
    |
    | This package supports a variety of sms "senders" that can be used
    | when delivering a text message. You may specify which one you're using for
    | your senders below. You may also add additional senders if needed.
    |
    | Supported: "hellio", "log", "array", "slack", "failover", "roundrobin"
    |
    */

    'senders' => [
        'hellio' => [
            'sender' => 'hellio',
            'client_id' => env('HELLIO_CLIENT_ID'),
            'app_secret' => env('HELLIO_APP_SECRET'),
            'from' => env('HELLIO_SENDER_ID'),
        ],

        'frog_sms' => [
            'sender' => 'frog_sms',
            'username' => env('FROG_SMS_USERNAME'),
            'password' => env('FROG_SMS_PASSWORD'),
            'from' => env('FROG_SMS_SENDER_ID'),
            'service_type' => 'SMS',
            'message_type' => env('FROG_SMS_MESSAGE_TYPE', 'text'),
        ],

        'slack' => [
            'sender' => 'slack',
            'webhook_url' => env('SMS_SLACK_WEBHOOK_URL'),
            'from' => env('SMS_SLACK_USERNAME'),
            'emoji' => env('SMS_LOG_SLACK_EMOJI'),
        ],

        'log' => [
            'sender' => 'log',
            'channel' => env('SMS_LOG_CHANNEL'),
        ],

        'array' => [
            'sender' => 'array',
        ],

        'failover' => [
            'sender' => 'failover',
            'senders' => [
                'log',
            ],
        ],

        'roundrobin' => [
            'sender' => 'roundrobin',
            'senders' => [
                'log',
                'array',
            ],
        ],

    ],

];

该软件包预先配置了类似于Hellio、Wigal、Slack、Log和数组的短信服务提供商。

故障转移配置

故障转移机制允许您定义多个服务提供商，以便在主服务提供商失败时使用。您应用程序的故障转移发送器的配置数组应包含一个发送器数组，该数组引用配置发送器的顺序，以便在交付时选择

'senders' => [
    'failover' => [
        'sender' => 'failover',
        'senders' => [
            'log',
            'slack',
        ],
    ],
 
    // ...
],

定义了故障转移发送器后，您应通过指定其名称作为应用程序的sms配置文件中的default配置键的值，将此发送器设置为应用程序使用的默认发送器

'default' => env('SMS_SENDER', 'failover'),

轮询配置

roundrobin发送器允许您将短信发送分布到多个发送器，以平衡负载。要开始，在应用程序的sms配置文件中定义一个使用roundrobin发送器的发送器。您应用程序的roundrobin发送器的配置数组应包含一个senders数组，该数组引用应用于交付的配置发送器

'senders' => [
    'roundrobin' => [
        'sender' => 'roundrobin',
        'senders' => [
            'log',
            'array',
        ],
    ],
 
    // ...
],

设置FROM

此软件包允许您以两种方式设置sms的from地址：全局方式或按发送器。

使用全局from地址

如果您的应用程序为所有短信使用相同的“from”地址，则将其添加到每个发送器可能会变得繁琐。相反，您可以在config/sms.php配置文件中指定全局“from”地址。如果没有指定其他“from”地址，则将使用此地址发送短信

'from' => env('SMS_FROM_NAME', 'Example'),

使用发送器级别的from地址

如果每个发送器都有自己的“from”地址，您可以在config/sms.php配置文件中的发送器配置中指定它。如果没有指定其他“from”地址，则将使用此地址发送短信

'senders' => [
    'hellio' => [
        'sender' => 'hellio',
        'client_id' => env('HELLIO_CLIENT_ID'),
        'app_secret' => env('HELLIO_APP_SECRET'),
        'from' => env('HELLIO_SENDER_ID'),
    ],
 
    // ...
],

您还可以在发送短信时指定一个from地址。发送消息时指定的from地址将优先于发送器配置中设置的发送器级别的from，这也优先于在config/sms.php配置文件中设置的全局from。

用法

在通知类中

要在通知中使用此软件包，请确保在通知模型中包含一个routeNotificationForSms()方法，该方法返回一个电话号码。如下所示

class User extends Authenticatable
{
    use Notifiable;

    /**
     * Route notifications for the SMS channel.
     *
     * @param  \Illuminate\Notifications\Notification  $notification
     * @return string
     */
    public function routeNotificationForSms($notification)
    {
        return $this->phone_number; 
    }
}

然后在您的通知类中可以在via()方法中使用通道sms

use AlhajiAki\Sms\Notification\Messages\SmsMessage;
use Illuminate\Notifications\Notification;

class AccountApproved extends Notification
{
    public function via($notifiable)
    {
        return ['sms'];
    }

    public function toSms($notifiable)
    {
        return (new SmsMessage())
            ->message("Hello sms notification channel");
    }
}

\AlhajiAki\Sms\Notification\Messages\SmsMessage类提供了以下方法

• sender()：当您想更改在 config/sms.php 文件中设置的默认发送者时，请使用此方法。此方法接受一个字符串或 null。
• from()：使用此方法设置消息的 from 地址。此方法接受一个字符串。
• data()：数据方法提供了一种发送对发送者在发送消息时可能有用数据的手段。这可以用来设置消息类型或任何需要通过发送者发送短信的相关信息。

使用外观

此包提供了一个 Sms 外观，可以用于如下发送短信

use AlhajiAki\Sms\Sms;

Sms::send('Hello sms facade', '+3112345678');

如果您想使用不同的发送者发送短信，可以像下面这样做

use AlhajiAki\Sms\Sms;

Sms::sender('slack')->send('Hello sms facade', '+3112345678');

send() 方法接受以下 4 个参数，如下所述

• $message：要发送的消息。这是一个字符串。
• $to：消息的接收者。这是一个字符串或数组。
• $from：发送者地址。这是一个字符串或 null。如果没有提供，将使用发送者的 from 或在 config/sms.php 文件中设置的全球 from。
• $data：要发送给发送者的数据

短信与本地开发

当开发一个发送短信的应用程序时，您可能不想将消息实际发送到真实的电话号码。此包提供几种方法在本地开发期间“禁用”实际发送消息。

日志驱动程序

而不是发送您的消息，日志发送驱动程序会将所有消息写入您的日志文件以供检查。通常，此驱动程序只会用于本地开发。有关按环境配置应用程序的更多信息，请查看配置文档。

Slack 驱动程序

或者，您可以使用 Slack 驱动程序发送您的消息，您可以查看它们。这种方法的好处是允许您实际检查最终消息。

使用全局地址

最后，您可以通过调用 Sms 外观提供的 alwaysTo 方法来指定全局“to”地址。通常，此方法应从您应用程序的一个服务提供者的 boot 方法中调用

use AlhajiAki\Sms\Sms;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    if ($this->app->environment('local')) {
        Sms::alwaysTo('+3212345678');
    }
}

事件

在发送短信消息时，我们发出两个事件。在消息发送之前发出 SmsMessageSending 事件，在消息发送后发出 SmsMessageSent 事件。请记住，这些事件在发送短信时发出，而不是在排队时发出。您可以在应用程序中创建这些事件的监听器

use AlhajiAki\Sms\Events\SmsMessageSending;
// use AlhajiAki\Sms\Events\SmsMessageSent;

class LogMessage
{
    /**
     *Handle the given event.
     */
    public function handle(SmsMessageSending $event): void
    {
        // ...
    }
}

自定义发送者

您可能希望编写自己的发送者以通过此包不支持的其它服务发送短信。要开始，定义一个扩展 AlhajiAki\Sms\Senders\SenderInterface 类的类。然后，在您的发送者上实现 send() 和 __toString() 方法

use AlhajiAki\Sms\SentMessage;
use AlhajiAki\Sms\TextMessage;

class TwilioSender implements SenderInterface
{
    /**
     * Create a new Twilio sender instance.
     */
    public function __construct(protected array $config) {
    }

    /**
     * {@inheritdoc}
     */
    public function send(TextMessage $message): ?SentMessage
    {
        // Implement the logic to send SMS via your custom sender
    }
 
    /**
     * Get the string representation of the sender.
     */
    public function __toString(): string
    {
        return 'twilio';
    }
}

一旦定义了您的自定义发送者，您可以通过 Sms 外观提供的 extend 方法来注册它。通常，这应在您的应用程序的 AppServiceProvider 服务提供者的 boot 方法中完成。将向提供给 extend 方法的闭包传递一个 $config 参数。此参数将包含在应用程序的 config/sms.php 配置文件中为发送者定义的配置数组

use App\Sms\TwilioSender;
use AlhajiAki\Sms\Sms;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Sms::extend('twilio', function (array $config = []) {
        return new TwilioSender(/* ... */);
    });
}

一旦定义并注册了您的自定义发送者，您可以在应用程序的 config/sms.php 配置文件中创建一个发送者定义，该定义利用了新的发送者

'twilio' => [
    'sender' => 'twilio',
    // ...
],

待办事项

• 添加 SmsFake 以帮助测试短信发送
• 编写测试短信发送的文档
• 编写整个包的测试

测试

vendor/bin/phpunit

贡献

有关详细信息，请参阅 CONTRIBUTING

许可

MIT 许可证（MIT）。有关更多信息，请参阅 许可证文件