README

Laravel inbox

此包的目的是提供对 incoming 通信的模式匹配，并在匹配成功时执行自定义回调。

感谢 BeyondCode 提供了初始代码库。后来此包的理念与原始版本有较大差异，不得不将其作为一个新的包独立出来。

安装

使用 composer require asseco-voice/laravel-inbox 安装包。服务提供程序将自动注册。

使用方法

接口

在开始使用此包之前，您需要有一个实现了 CanMatch 接口的类，以便包知道将对其验证正则表达式。

例如，如果您想验证 'from' 字段，则需要定义从哪里获取该信息。

class Message implements CanMatch
{
    ...
    public function getMatchedValues(string $matchBy): array
    {
        switch ($matchBy) {
            case 'from':                return [$this->from()];
            case 'subject':             return [$this->subject()];
            case 'something_custom':    return [$this->custom()];
            default:                    return [];
        }
    }
    ...
}

Inbox API

Inbox 是一个类，您在其中提供您希望在与给定回调执行之前进行匹配的正则表达式。

例如，在 action() 下定义的回调只有在匹配 .*@gmail.com 模式时才会执行

$inbox = new Inbox();

$inbox
    ->from('{.*}@gmail.com')
    ->action(function (CanMatch $message) {
        Log::info("Message received");
    });

模式需要用 { } 包围。

from($pattern) 将针对 from 字段
to($pattern) 将针对 to 字段
cc($pattern) 将针对 cc 字段
bcc($pattern) 将针对 bcc 字段
subject($pattern) 将针对 subject 字段
setPattern($name, $pattern) 是为所有其他可能需要的情况创建的。例如，from($pattern) 只是 setPattern('from', $pattern) 的简写。
meta([...]) 用于添加任何其他元数据。
action(callable) 是要执行的回调，它接受一个实现 CanMatch 接口的对象作为唯一参数（也可以省略）。
matchEither() 将作为定义了多个模式时的情况下的 OR 门。默认行为是匹配所有模式以执行回调。
priority($number) 将设置 inbox 优先级，该优先级只有在使用 InboxGroup 时才会考虑。
run(CanMatch $message) 将接受一个实现 CanMatch 接口的对象实例，并将返回一个布尔值，表示是否触发了 inbox。 当使用 inbox 组时，不得使用此方法。它们有自己的 run() 方法。

Inbox 组 API

如果您需要处理多个情况，还有一个更高层次的概念——InboxGroup，它作为多个 inbox 的容器，同时也有几个流畅的 API 方法。

add(Inbox $inbox) 将 inbox 添加到组中
continuousMatching() 将在第一次匹配后继续匹配。默认行为是在匹配到一个 inbox 后停止。
fallback(callable) 将添加一个（非强制性的）回退，如果未命中任何 inbox，则执行。
run(CanMatch $message) 将接受一个实现 CanMatch 接口的对象实例，并将返回一个匹配的 inbox 数组。inbox 将按优先级运行。

更多示例

示例将涵盖使用邮件的情况，但它可以适应任何 incoming 通信。

匹配函数可以用来提供精确匹配（即 from('exact@email.com')），或者提供正则表达式匹配，需要用花括号 { } 包围才能被解释为正则表达式。

示例

$inbox = new Inbox();

$inbox
    ->from('{.*}@gmail.com')
    ->to('{.*}@gmail.com')
    ->subject('Subject to match')
    ->action(function (CanMatch $email) {
        Log::info("Mail received");
    })
    ->matchEither()
    ->priority(10);

更多示例及结果

精确匹配 from('your.mail@gmail.com')
- 只有来自 your.mail@gmail.com 的邮件会被匹配。
部分匹配 from('{.*}@gmail.com')
- 任何以 @gmail.com 结尾的邮箱地址都会被匹配，例如 someone@gmail.com 和 someone-else@gmail.com，但 someone@yahoo.com 不会。
部分匹配 from('your.name@{.*}')
- 与上一个示例相同，但这次名称是固定的，提供者是灵活的。它会匹配 your.name@gmail.com 和 your.name@yahoo.com，但不会匹配 not.your.name@gmail.com。
完全正则表达式匹配：from('{.*}')
- 接受任何内容。

分组示例

public function receiveEmail($email){

    $inbox1 = ...;
    $inbox2 = ...;
    $inbox3 = ...;

    $group = new InboxGroup(); 
    
    $group
        ->add($inbox1)
        ->add($inbox2)
        ->add($inbox3) 
        ->fallback(function (CanMatch $email) {
            Log::info("Fell back");
        })
        ->continuousMatching()
        ->run($email);
}

如果你不想使用分组但只想使用一个收件箱，你可以直接调用该收件箱的 run 方法。

public function receiveEmail($email){

    $inbox = new Inbox();
    
    $inbox
        ->...
        ->...
        ->run($email);
}

asseco-voice / laravel-inbox

维护者

详细信息