README

介绍

Laravel Arpoone 是一个与Arpoone短信网关集成的包，允许您使用通知系统从Laravel应用程序发送短信。此包支持多租户应用程序，webhook支持，并在数据库中可选地记录短信消息。

要求

PHP 8.0+
Laravel 8.0+
Guzzle HTTP客户端
libphonenumber库用于电话号码验证

安装

通过Composer安装包

composer require controlink/laravel-arpoone

发布配置文件

安装后，发布配置文件以自定义包的行为。
```
php artisan vendor:publish --tag=arpoone-config
```
发布迁移（可选）

如果您使用多租户或想要记录短信消息，则发布迁移
```
php artisan vendor:publish --tag=arpoone-migrations
```
然后，运行迁移
```
php artisan migrate
```
设置环境变量

如果您不是使用多租户模式，在您的.env文件中添加必要的变量
```
ARPOONE_API_KEY=your-api-key-here
ARPOONE_ORGANIZATION_ID=your-organization-id-here
ARPOONE_SENDER=your-sender-id-here
```
如果您使用多租户模式，可以在发送通知时动态设置租户ID。

配置

发布配置文件后，您可以修改config/arpoone.php文件以自定义包的行为。

return [

    // The base URL of the Arpoone API. This should point to the appropriate version of the API you're using.
    // You can override it via the .env file with the variable ARPOONE_URL.
    'url' => env('ARPOONE_URL', "https://api.arpoone.com/v1.1/"),

    // The API key for authenticating requests to the Arpoone API.
    // This must be set in your .env file using the ARPOONE_API_KEY variable.
    'api_key' => env('ARPOONE_API_KEY', null),

    // The ID of the organization in Arpoone that is sending the SMS messages.
    // It should be set in your .env file using the ARPOONE_ORGANIZATION_ID variable.
    'organization_id' => env('ARPOONE_ORGANIZATION_ID', null),

    // The default sender name or number for the SMS messages.
    // You can configure this via the ARPOONE_SENDER variable in your .env file.
    'sender' => env('ARPOONE_SENDER', null),

    // If true, SSL certificates will be verified when sending requests to the API.
    // This is a security feature to ensure that the API connection is secure.
    'verify_ssl' => true,

    // If true, the package will migrate a database table to store the configuration settings.
    // This is useful if you want to store the configuration settings in the database to make them dynamic, or multi-tenant.
    'multi_tenant' => false,

    // The name of the database table to store the configuration settings.
    // This is only used if the multi_tenant option is set to true.
    'table_name' => 'arpoone_configuration',

    // The tenant model to use for multi-tenant applications. (e.g., App\Models\User)
    // This is only used if the multi_tenant option is set to true.
    'tenant_model' => '',

    // If true, the table will be created with a tenant column to store some type of identifier for the tenant.
    // This is only used if the multi_tenant option is set to true.
    'use_tenant_column' => false,

    // The name of the column to store the tenant identifier.
    // This is only used if the multi_tenant option is set to true and the use_tenant_column option is set to true.
    'tenant_column_name' => 'tenant_id',

    //If true, the sms sent will be logged in the database
    //This is useful if you want to keep track of the sms sent
    'log_sms' => false,

    //The name of the table to store the sms logs
    //This is only used if the log_sms option is set to true
    'sms_log_table' => 'arpoone_sms_logs',

    //The name of the column to store the tenant identifier.
    //This is only used if the multi_tenant option is set to true and the use_tenant_column option is set to true.
    'sms_log_tenant_column_name' => 'tenant_id',

    //If true, the package will apply webhooks routes to handle the sms status
    //This is useful if you want to keep track of the sms status, and update your database accordingly
    'webhooks' => false,
];

主要配置选项

url: Arpoone API的基础URL。
api_key: 用于认证请求的API密钥。
organization_id: 发送短信的组织ID。
sender: 短信消息的默认发送者名称或号码。
verify_ssl: 发送请求时验证SSL证书。
multi_tenant: 启用多租户支持。
table_name: 存储配置设置的数据库表名称。
tenant_model: 用于多租户应用程序的租户模型。
use_tenant_column: 在配置表中创建租户列。
tenant_column_name: 存储租户标识符的列名称。
log_sms: 启用短信消息记录。
sms_log_table: 存储短信日志的表名称。
sms_log_tenant_column_name: 存储短信日志租户标识符的列名称。
webhooks: 启用webhooks以跟踪短信状态。

用法

发送短信通知

要使用Laravel的通知系统发送短信，您需要定义一个使用Arpoone通道的通知类。以下是一个示例

创建通知类

php artisan make:notification SendSmsNotification

修改通知类

在SendSmsNotification类中，定义toArpoone方法以发送短信

use Illuminate\Notifications\Notification;

class SendSmsNotification extends Notification
{
     public function via($notifiable)
     {
          return [\Controlink\LaravelArpoone\Channels\Arpoone::class];
     }

     public function toArpoone($notifiable)
     {
          return [
            'content' => 'Your SMS message content goes here!',
          ];
     }
}

发送通知

在您的可通知模型（如User）中，确保您有一个routeNotificationForArpoone方法，它返回电话号码
```
public function routeNotificationForArpoone()
{
    return $this->phone_number;
}
```
然后，发送短信
```
$user = User::find(1);
$user->notify(new SendSmsNotification());
```
注意：如果您在可通知模型中未创建routeNotificationForArpoone方法，则包将尝试使用名为phone_number的列（如果存在），否则将抛出异常。

多租户支持

如果您使用多租户功能，请确保以下内容

在配置中将multi_tenant设置为true。
定义tenant_model并确保租户标识符可用。
在多租户应用程序中发送通知时，在初始化Arpoone通道时传递租户ID

$tenantId = $user->tenant_id;
$notification = new \Controlink\LaravelArpoone\Channels\Arpoone($tenantId);
$notification->send($user, new SendSmsNotification());

记录短信

如果启用短信记录，请在配置中将log_sms设置为true。包将在sms_log_table中定义的数据库表中记录发送的短信。

Webhook支持

要使用webhooks跟踪短信状态，请在配置中将webhooks设置为true。该包将自动创建一个路由来处理webhooks，并将必要的webhooks添加到发送的短信正文中。

可能的状态有

pending：短信正在等待发送。
delivered：短信已成功发送到接收者。
not_delivered：短信未能发送到接收者。

错误处理

在以下情况下，该包会抛出异常

缺少或无效的API密钥。
缺少发送者或组织ID。
无效或缺少电话号码。
短信发送失败。
确保您在应用程序中适当处理异常。

controlink / laravel-arpoone

维护者

详细信息