README

简介

此包提供了与 Bird.com API 的无缝集成，允许您通过短信管理联系人和发送通知。

安装

您可以通过 composer 安装此包

composer require 101media/bird

安装包后，您需要发布配置文件

php artisan vendor:publish --tag="bird-config"

配置

发布配置文件后，您需要在您的 .env 文件中设置以下环境变量

BIRD_ACCESS_KEY={--your-access-key--}
BIRD_WORKSPACE_ID={--your-workspace-id--}
BIRD_SMS_CHANNEL_ID={--your-sms-channel-id--}

所有配置密钥都可在 config/bird.php 中找到

用法

联系人管理

检索联系人

要从 API 检索联系人，您可以使用 ContactManager 的 get 方法

use Media101\Bird\Services\Contacts\ContactManager;

$contacts = ContactManager::get(); // Retrieve all contacts with default settings

您也可以通过 ID 检索特定的联系人

$contact = ContactManager::get('contact-id');

可以提供额外的参数来自定义查询

$contacts = ContactManager::get(null, 20, true, 'nextPageToken');

创建或更新联系人

要创建或更新联系人，请使用 createOrUpdate 方法

use Media101\Bird\Services\Contacts\BirdContact;
use Media101\Bird\Services\Contacts\ContactManager;

$contact = (new BirdContact())
    ->name('John Doe')
    ->phone('+12345678901')
    ->email('john.doe@example.com');

$response = ContactManager::createOrUpdate($contact);

您可以指定标识键（默认为 phonenumber）

$response = ContactManager::createOrUpdate($contact, 'emailaddress');

删除联系人

要删除联系人，请使用 delete 方法

$response = ContactManager::delete('contact-id');

通知

发送短信通知

目前此包仅支持发送 text 类型的短信通知。要发送短信通知，您需要使用 SMSChannel 类。此类处理通过 Bird.com 发送短信通知。

首先，创建一个返回 SMSMessage 类实例的通知类

namespace App\Notifications;

use Media101\Bird\Services\Contacts\BirdContact;
use Media101\Bird\Services\Notifications\SMS\SMSMessage;

class OrderReceived
{

    public function __construct(
        private string $content
    ) {}
    
    public function via($notifiable): array
    {
        return [SMSChannel::class];
    }

    public function toSMS(User $notifiable): array
    {
        // The phone number must have a country code appended.
        $contact = (new BirdContact())->phone($notifiable->phone_number);
        
        return (new SMSMessage())
            ->to($contact)
            ->type(SMSType::TEXT)
            ->text($this->content);
    }
    
}

最后，通知可通知的实体

$user->notify(new OrderReceived('Your order has been received'));

异常处理

此包使用自定义异常来处理错误

• InvalidParameterException：当参数无效时抛出。
• ConnectionException：当与 API 的连接出现错误时抛出。
• NotAnSmsMessageException：当提供的消息不是 SMSMessage 的实例时抛出。
• NotificationNotSent：当通知无法发送时抛出。

请确保在您的代码中捕获这些异常，以优雅地处理错误。

贡献

请将问题和拉取请求提交到 GitHub 仓库。

许可

此包是开源软件，采用 MIT 许可。

联系方式

有关任何查询或支持，请联系 101Media。

此 README 现在包括针对 SMSChannel 和 SMSMessage 的部分，以及现有的联系人管理功能。如果您还有其他类或详细信息要添加，请告诉我！