README

内容

Arkesel SDK

关于

这是一个为 Arkesel 提供的非官方 SDK，Arkesel 是一个围绕 [Arkesel API] 为 PHP 和 Laravel 应用程序提供的包装器。

功能

批量短信
支付
语音
电子邮件
USSD

此 SDK 包含一个 Laravel 通知通道，允许使用 Arkesel API 将 Laravel 通知作为短信发送。

安装

您可以通过 composer 安装此包

composer require parables/arkesel-sdk

服务提供程序将自动加载。

然后发布配置文件

php artisan vendor:publish --provider="Parables\ArkeselSdk\ArkeselServiceProvider" --tag="config"

设置 Arkesel 服务

首先，创建注册账户。您将被带到您的短信仪表板，在那里您可以找到短信 API 密钥。

然后，将 API 密钥添加到 .env 文件中

ARKESEL_SMS_API_KEY="your Arkesel API key"

以下 env 变量可用于自定义该包。有关更多信息，请参阅 Arkesel 文档

ARKESEL_API_VERSION="v2" # or "v1"
ARKESEL_SMS_URL= # for SMS API v1, use 'https://sms.arkesel.com/sms/api`
ARKESEL_SMS_SENDER= # defaults to your `APP_NAME` env variable
ARKESEL_SMS_CALLBACK_URL= # for API SMS v2
ARKESEL_SMS_SANDBOX= # for API SMS v2

使用

批量短信

$builder = (new ArkeselMessageBuilder)
    ->message('Hello World')
    ->recipients(["233234567890", "233234567890"])
    ->recipients("233234567890,233234567890") // alternative
    ->sandbox(false);

// helper function
$response = arkeselSms(builder: $builder)->send();

// facade
$response = ArkeselSms::make(builder: $builder)->send();

// instance
$response = new ArkeselSms(builder: $builder)->send();

向 `arkesel` 通道发送通知

创建一个通知类。请参阅 Laravel 关于通知的文档。

将 Notifiable 特性添加到您的模型中

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;
}

创建一个通知

php artisan make:notification WelcomeMessage

然后使用 via() 方法指定通道，并使用 toArkesel($notifiable) 方法指定要发送的消息

<?php

namespace App\Notifications;

use Parables\ArkeselSdk\BulkSms\ArkeselMessageBuilder;
use Illuminate\Notifications\Notification;
use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Bus\Queueable;

class WelcomeMessage extends Notification implements ShouldQueue
{
    use Queueable;

    protected string $message;

    /**
     * Create a new notification instance.
     *
     * @return void
     */
    public function __construct(string $message)
    {
        $this->message = $message;
    }

    /**
     * Get the notification's delivery channels.
     *
     * @param  mixed  $notifiable
     * @return array
     */
    public function via($notifiable)
    {
        return ['arkesel'];
    }

    /**
     * the content of the notification to be sent.
     *
     * @param  mixed  $notifiable
     * @return string|ArkeselMessageBuilder
     */
    public function toArkesel($notifiable)
    {
        return $this->message;
    }
}

发送通知

选项 1：使用 Notifiable 特性提供的 notify() 方法

use App\Notifications\WelcomeMessage;

$user->notify(new WelcomeMessage($message));

选项 2：使用通知外观

use Illuminate\Support\Facades\Notification;

Notification::send($users, new WelcomeMessage($message));

选项 3：使用通知的外观 route 方法进行按需通知

Notification::route('arkesel', '233123456789')->notify(new WelcomeMessage($message));

短信接收者

对于按需通知，recipients 直接传递给 Notification::route 方法。

Notification::route('arkesel', ['233123456789', '233123456789'])->notify(new WelcomeMessage($message));

// alternative
Notification::route('arkesel', '233123456789,233123456789')->notify(new WelcomeMessage($message));

对于所有其他情况，强烈建议您使用 ArkeselMessageBuilder 实例或 ArkeselSms 实例/外观/辅助函数上的 recipients() 方法明确指定您的通知接收者

public function toArkesel($notifiable)
{
    return (new ArkeselMessageBuilder())
        ->message('Hello World')
        ->recipients(["233123456789", "233123456789"]);
        ->recipients("233123456789,233123456789") // alternative
}

但是，您可能想将字符串作为短信消息返回给 toArkesel($notifiable) 方法。

public function toArkesel($notifiable)
{
    return 'Hello World';
}

在这种情况下，请确保定义一个 routeNotificationForArkesel($notification) 方法，该方法将接收要发送在您的可通知类上的通知实例 $notification，并返回一个以逗号分隔的字符串或字符串数组。

这确保了该包不会尝试确定接收者。

public function routeNotificationForArkesel($notification)
{
    return ['233123456789','233123456789'];
    // or
    return '233123456789,233123456789';
}

如果您的可通知类中没有定义 routeNotificationForArkesel($notification) 方法，此包将尝试使用以下顺序中的任何一种方法或属性在可通知类上获取接收者。

TL'DR：它更喜欢

复数方法而不是单数方法

复数属性而不是单数属性

驼峰命名属性而不是下划线命名属性

使用以下特定名称： routeNotificationForArkesel、recipients、recipient、phoneNumbers、phone_numbers、phoneNumber、phone_number

在内部，它使用以下代码片段来决定如何获取收件人：

    /**
     * Get the recipients from methods and properties defined on the `$notifiable` class
     *
     * @param mixed $notifiable
     * @param Notification $notification
     * @return string|array
     */
    private function getRecipientsFromNotifiable($notifiable, Notification $notification): string|array
    {
        return $this->getValueFromMethodOrProperty('routeNotificationForArkesel', $notifiable, $notification)
            ?? $this->getValueFromMethodOrProperty('recipients', $notifiable, $notification)
            ?? $this->getValueFromMethodOrProperty('recipient', $notifiable, $notification)
            ?? $this->getValueFromMethodOrProperty('phoneNumbers', $notifiable, $notification)
            ?? $this->getValueFromMethodOrProperty('phone_numbers', $notifiable, $notification)
            ?? $this->getValueFromMethodOrProperty('phoneNumber', $notifiable, $notification)
            ?? $this->getValueFromMethodOrProperty('phone_number', $notifiable, $notification)
            ?? []; // [] is a fallback that will throw an exception
    }

这是获取收件人的优先级顺序：

<?php

namespace App;

use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;


class GetRecipientsOrderOfPreference
{
    use Notifiable;

    /*1st*/
    public function routeNotificationForArkesel($notification)
    {
        return ['233123456789','233123456789']
    }

    /*2nd*/
    public function recipients($notification)
    {
        return ['233123456789','233123456789']
    }

    /*3rd*/
    public string $recipients = ['233123456789','233123456789'];

    /*4th*/
    public function recipient($notification)
    {
        return ['233123456789','233123456789']
    }

    /*5th*/
    public string $recipient = ['233123456789','233123456789'];

    /*6th*/
    public function phoneNumbers($notification)
    {
        return ['233123456789','233123456789']
    }

    /*7th*/
    public string $phoneNumbers = ['233123456789','233123456789'];

    /*8th*/
    public string $phone_numbers = ['233123456789','233123456789'];

    /*9th*/
    public function phoneNumber($notification)
    {
        return ['233123456789','233123456789']
    }

    /*10th*/
    public string $phoneNumber = ['233123456789','233123456789'];

    /*11th*/
    public string $phone_number = ['233123456789','233123456789'];
}

注意，上述所有方法都接收正在发送的 Notification 实例 $notification。

如果没有定义这些方法或属性，它将抛出异常： ArkeselSmsBuilderException: '此短信未指定收件人'

编写短信

您可以通过链式调用 ArkeselMessageBuilder 提供的设置方法流畅地组合短信：

public function toArkesel($notifiable)
{
    return (new ArkeselMessageBuilder())
        ->message("Your message")
        ->recipients(["233123456789", "233123456789"])
        ->recipients("233123456789,233123456789") // alternative
        ->apiKey("your API key") # this overrides the `.env` variable
        ->schedule(now()->addMinutes(5))
        ->sender("Company") // less than 11 characters
        ->callbackUrl("https://my-sms-callback-url")
        ->sandbox(false)
}

可用方法

ArkeselMessageBuilder

message(string $message): self

设置要发送的消息。
getMessage(): string

获取要发送的短信消息。
sender(string $sender): self

设置标识短信消息发送者的名称或号码。
getSender(): null|string

获取标识短信消息发送者的名称或号码。
recipients(string|array $recipients):self

设置接收短信的电话号码。

此方法将删除空字符串并过滤出唯一的收件人。
getRecipients(string $apiVersion = 'v2'): string|array

获取接收短信的电话号码。

对于 SMS API 版本 v1 返回逗号分隔的字符串，对于 v2 返回字符串数组。
schedule(string|Carbon $schedule): self

设置/安排消息发送的时间。

有关更多信息，请参阅 https://carbon.nesbot.com/docs/
```
$builder = new ArkeselMessageBuilder();

$builder->schedule($now->addMinutes(5));

$builder->schedule('first day of May 2022');
```
getSchedule(string $apiVersion = 'v2'): null|string

获取指定 SMS API 版本的消息发送时间。
callbackUrl(string $callbackUrl): self

设置一个将被调用来通知您有关特定号码消息状态的 URL。
getCallbackUrl(): null|string

设置一个将被调用来通知您有关特定号码消息状态的 URL。
sandbox(bool $sandbox = true): self

设置发送短信的环境。如果为 true，短信消息不会转发到移动网络运营商进行投递，因此您不会为此操作付费。使用此功能测试您的应用程序。
getSandbox()

获取短信环境模式。
smsApiKey(string $apiKey): self

设置用于验证请求的 API 密钥。

覆盖 .env 文件中设置的 API 密钥。
getSmsApiKey(): null|string

获取用于此请求的 arkesel SMS API 密钥。
smsApiVersion(string $smsApiVersion = 'v2'): self

设置用于此请求的 SMS API 版本。

覆盖 .env 文件中设置的 ARKESEL_SMS_API_VERSION。
getSmsApiVersion(): null|string

获取用于此请求的 arkesel SMS API 版本。

ArkeselSms

使用 ArkeselSms 类发送短信并获取短信余额。

// Create an instance
(new ArkeselSms(builder: $builder))->send();
// OR: Use the Facade
ArkeselSms::make(builder: $builder)->send();
// OR: Use the helper function
arkeselSms(builder: $builder)->send();

make(ArkeselMessageBuilder $builder): self

在使用 ArkeselSms 作为外观时必须首先调用。
send(): array

向收件人发送短信。
static getSmsBalance(string $smsApiVersion = null, string $smsApiKey = null): array

获取短信余额。

Arkesel::getSmsBalance();

常见问题解答

在沙盒模式下发送短信

默认情况下，SDK 以沙盒模式发送短信设置为 false。如果您希望以沙盒模式发送短信，必须明确调用 sandbox() 或 sandbox(true) 设置器方法。

ArkeselChannel

ArkeselChannel 类公开发送方法以发送通知。

send($notifiable, Notification $notification): array

通过 ArkeselSms 发送给定的通知。

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG

测试

composer test

composer test:coverage

安全

如果您发现任何安全相关的问题，请通过电子邮件 parables95@gmail.com 反馈，而不是使用问题跟踪器。

parables / arkesel-sdk

维护者

详细信息

README

内容

关于

功能

安装

设置 Arkesel 服务

使用

批量短信

向 `arkesel` 通道发送通知

短信接收者

编写短信

可用方法

ArkeselMessageBuilder

ArkeselSms

常见问题解答

ArkeselChannel

变更日志

测试

安全

贡献

致谢

许可

parables / arkesel-sdk

维护者

详细信息

README

内容

关于

功能

安装

设置 Arkesel 服务

使用

批量短信

向 arkesel 通道发送通知

短信接收者

编写短信

可用方法

ArkeselMessageBuilder

ArkeselSms

常见问题解答

ArkeselChannel

变更日志

测试

安全

贡献

致谢

许可

向 `arkesel` 通道发送通知