README

简介

使用此包，您可以轻松地使用 Laravel ^8.0 发送 Netgsm 通知。此包还提供了一些简单的报告。

此包需要 PHP 7.3 或更高版本以及 Laravel 8.0 或更高版本。
对于 Laravel 的旧版本，请使用此包的 ^2.0.0 版本！

内容

• 安装
  • 设置 Netgsm 服务
• 使用
  • 服务方法
  • SMS 发送
    • 可用的 SMS 接口
  • 报告
    • 可用的报告接口
  • 账户余额
    • 剩余余额
    • 剩余套餐信用
  • IYS 集成
    • 添加地址
    • 搜索地址
• 测试
• 安全
• 贡献
• 致谢
• 许可

安装

您可以通过 composer 安装此包

composer require tarfin-labs/netgsm

接下来，您应该使用 vendor:publish Artisan 命令发布 Laravel 配置迁移文件。

php artisan vendor:publish --provider="TarfinLabs\Netgsm\NetgsmServiceProvider"

设置 Netgsm 服务

将您的 Netgsm 用户代码、默认标题（发送者名称或号码）和密钥（密码）添加到您的 .env

// .env
...
NETGSM_USERCODE=
NETGSM_SECRET=
NETGSM_LANGUAGE=
NETGSM_HEADER=
NETGSM_BRANDCODE=
],
...

NETGSM_USERCODE 和 NETGSM_SECRET 是 netgsm 的认证信息。NETGSM_HEADER 是短信消息的默认标题（发送者名称或号码）。

使用

服务方法

 Netgsm::sendSms(AbstractSmsMessage $message):string $JobId

将 SMS 消息发送到作为参数传递的消息对象上的电话号码。如果消息发送成功，将返回 netgsm API 服务返回的作业 ID。

Netgsm::getReports(AbstractNetgsmReport $report): ?Collection

根据作为参数传递的报告对象返回一个集合。

使用通知通道发送 SMS

为了使您的通知知道您正在发送给哪个电话号码，请将 routeNotificationForNetgsm 方法添加到您的 Notifiable 模型中，例如您的 User 模型

public function routeNotificationForNetgsm()
{
    /*
       where `phone` is a field in your users table, 
       phone number format can be either `5051234567` or `5051234567, 5441234568`.
    */
    return $this->phone;
}

您可以在通知内部的 via() 方法中使用此通道

use TarfinLabs\Netgsm\NetGsmChannel;
use TarfinLabs\Netgsm\NetGsmSmsMessage;
use Illuminate\Notifications\Notification;

class NewUserRegistered extends Notification
{
    public function via($notifiable)
    {
        return [NetGsmChannel::class];
    }

    public function toNetgsm($notifiable)
    {
        return (new NetGsmSmsMessage("Hello! Welcome to the club {$notifiable->name}!"));
    }
}

您也可以添加接收者（字符串或数组）

return (new NetGsmSmsMessage("Your {$notifiable->service} was ordered!"))->setRecipients($recipients);

您还可以设置消息的发送日期范围。（OTP 消息不适用。）

$startDate = Carbon::now()->addDay(10)->setTime(0, 0, 0);
$endDate = Carbon::now()->addDay(11)->setTime(0, 0, 0);

return (new NetGsmSmsMessage("Great note from the future!"))
->setStartDate($startDate)
->setEndDate($endDate)

您还可以设置授权数据参数。（OTP 消息不适用。）

如果此参数传递为 true，则仅向具有数据权限的电话号码发送 SMS。

return (new NetGsmSmsMessage("Your {$notifiable->service} was ordered!"))->setAuthorizedData(true);

此外，您还可以更改标题。

return (new NetGsmSmsMessage("Your {$notifiable->service} was ordered!"))->setHeader("COMPANY");

您可以使用 NetGsmOtpMessage 替代 NetGsmSmsMessage 来发送 OTP 消息。

return (new NetGsmOtpMessage("Your {$notifiable->service} OTP Token Is : {$notifiable->otp_token}"));

有关发送 OTP 消息的更多信息，请参阅 Netgsm OTP SMS 文档

使用 Netgsm Facade 发送 SMS

您还可以直接使用 Netgsm Facade 发送 SMS 或 OTP 消息

$message = new NetgsmSmsMessage("Your {$notifiable->service} was ordered!");
->setHeader("COMPANY")
->setRecipients(['5051234567','5441234568']);

Netgsm::sendSms($message);

报告

您可以通过日期范围或 netgsm 批量 ID 获取 SMS 报告

要接收报告，必须创建一个报告对象。

$report = new NetgsmSmsReport();

可用的报告接口

• NetgsmSmsReport（基本报告）：文档
• NetgsmSmsDetailReport（详细报告）：文档

对象参数

示例用法

您可以通过将报告对象传递给 Netgsm::getReports 方法来获取 SMS 报告。如果成功，SMS 报告结果将作为集合返回。

// Start and end dates
$startDate = Carbon::now()->subDay()->setTime(0, 0, 0);
$endDate = Carbon::now()->setTime(0, 0, 0);

$report = new NetgsmSmsReport();
$report->setStartDate($startDate)
    ->setEndDate($endDate);

$reports = Netgsm::getReports($report);
Netgsm::getReports($report);

报告结果中的字段可能会根据指定的报告类型和发送的报告版本参数而有所不同。

报告结果

账户余额

使用这项服务，您可以查询netgsm账户的余额以及套餐的信用余额。

剩余余额

返回netgsm账户的剩余金额。（TL）

使用

Netgsm::getCredit();

输出

2,7

剩余套餐信用

返回在相关netgsm账户中定义的套餐的信用余额。

使用

Netgsm::getAvailablePackages();

输出

class Illuminate\Support\Collection#105 (1) {
  protected $items =>
  array(3) {
    [0] =>
    array(3) {
      'amount' =>
      int(1000)
      'amountType' =>
      string(14) "Adet Flash Sms"
      'packageType' =>
      string(0) ""
    }
    [1] =>
    array(3) {
      'amount' =>
      int(953)
      'amountType' =>
      string(12) "Adet OTP Sms"
      'packageType' =>
      string(0) ""
    }
    [2] =>
    array(3) {
      'amount' =>
      int(643)
      'amountType' =>
      string(4) "Adet"
      'packageType' =>
      string(3) "SMS"
    }
  }
}

IYS 集成

使用这些服务，您可以将任何地址添加到IYS。

添加地址

此服务用于通过NetGsm IYS服务将电话号码或电子邮件地址添加到IYS。

对象参数

使用

$address = new \TarfinLabs\Netgsm\Iys\Requests\Add();
$address->setRefId(999999)
        ->setType('MESAJ')
        ->setSource('HS_WEB')
        ->setRecipient('+905XXXXXXXXX')
        ->setStatus('ONAY')
        ->setConsentDate(now()->toDateTimeString())
        ->setRecipientType('TACIR');

\TarfinLabs\Netgsm\Netgsm::iys()->addAddress($address)->send();

响应参数

{
    "code": "0",
    "error": "false",
    "uid": "73113cb9-dff0-415b-9491-xxxxxxxxxx"
}

批量插入

$address = new \TarfinLabs\Netgsm\Iys\Requests\Add();
$address->setRefId(999999)
        ->setSource('HS_WEB')
        ->setRecipient('+905XXXXXXXXX')
        ->setStatus('ONAY')
        ->setConsentDate(now()->toDateTimeString())
        ->setRecipientType('TACIR');

$iys = \TarfinLabs\Netgsm\Netgsm::iys();
$iys->addAddress($address->setType('MESAJ'));
$iys->addAddress($address->setType('ARAMA'));
$iys->send();

批量插入的响应参数

{
    "code": "0",
    "error": "false",
    "uid": "16116f5e-ae2a-4745-927a-xxxxxxxxxxx",
    "erroritem": {
        "1": {
            "recipient": "Telefon numarası 13 karakter ve numerik olmalıdır.+9xxxx"
        }
    }
}

搜索地址

此服务用于通过NetGsm IYS服务在IYS上搜索电话号码或电子邮件地址。

对象参数

使用

$address = new \TarfinLabs\Netgsm\Iys\Requests\Search();
$address->setType('MESAJ')
        ->setRecipient('+905XXXXXXXXX')
        ->setRecipientType('TACIR')
        ->setRefId(999999);

\TarfinLabs\Netgsm\Netgsm::iys()->searchAddress($address)->send();

响应参数

• 带有匹配地址的响应。

{
    "code": "0",
    "error": "false",
    "query": {
        "consentDate": "2020-11-06 11:22:34",
        "source": "HS_FIZIKSEL_ORTAM",
        "recipient": "+905XXXXXXXXX",
        "recipientType": "BIREYSEL",
        "type": "MESAJ",
        "status": "ONAY",
        "creationDate": "2020-11-06 11:23:49",
        "retailerAccessCount": 0
        // "querystatus": null
    }
}

• 没有匹配地址的响应

{
    "code": "50",
    "error": "Kayıt bulunamadi."
}

测试

composer test

变更日志

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

贡献

欢迎提交拉取请求。对于重大更改，请先创建一个问题来讨论您想要更改的内容。

请确保适当更新测试。

安全

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

致谢

• Hakan Özdemir
• Faruk Can
• Yunus Emre Deligöz
• Turan Karatuğ
• 所有贡献者

许可

Laravel Netgsm是开源软件，根据MIT许可证授权。