README

PHP客户端Kairoi，一个动态、准确且可扩展的时间任务调度器。

快速词汇

在尝试使用此库之前，您应该熟悉Kairoi的核心概念。如果不是这样，您可以从阅读Kairoi官方文档开始。

关于这个库，它的主要目标是提供一个易于使用、面向对象和低级别的可编程接口，以在PHP中与Kairoi服务器进行通信。它抽象化了与服务器管理套接字连接，使用Kairoi客户端协议编码和解码消息，并处理Kairoi指令。需要注意的是，这个库是为与依赖注入容器一起使用而设计的，并作为面向对象编程的“Actor/Message”模式的专业化。虽然这确实可以被认为是一个限制，但它使得Kairoi-PHP具有高度的扩展性。

使用Kairoi和此库的常规工作流程如下

1. 为应用程序配置规则和运行者，定义Kairoi将如何处理作业。 您可以查看Kairoi运行者文档以获取现有运行者的列表。运行者应该使用此库提供的可编程接口在应用程序部署期间仅写入一次Kairoi服务器。
2. 实现（在应用程序范围内）负责处理作业执行的可执行文件。 例如，在Shell运行者的情况下，您可以在您的首选框架中注册一个CLI，将其作业标识符作为其主要参数，并执行与接收到的作业关联的领域代码。这部分超出了此库的范围。
3. 应用程序在其整个生命周期中动态创建作业。 当在领域过程中需要时，应用程序可以通过此库调度作业。然后Kairoi将自动在正确的时间触发作业执行，启动与该作业关联的领域代码，按照第一步中配置的规则和运行者。

使用方法

配置客户端

开始与Kairoi服务器通信的第一件事是需要一个Kairoi\Domain\Client\ClientInterface。库提供了一个默认实现Kairoi\Infrastructure\Client\Client，作为此接口的实现。它接受一个string作为服务器URL（由PHP方法stream_socket_client接受），以及一个Kairoi\Domain\Client\Encoding\EncoderInterface和一个Kairoi\Domain\Client\Decoding\DecoderInterface，分别负责将Kairoi\Domain\Protocol\Request编码为可发送到服务器的流式消息，并将从服务器接收的流式消息解码为Kairoi\Domain\Protocol\Response。再次强调，此库提供了一个Kairoi\Domain\Client\Encoding\Encoder作为第一个参数，以及一个Kairoi\Infrastructure\Client\Decoding\ParsicaDecoder作为第二个参数。

总结来说，您可以使用以下代码创建一个客户端，配置为与监听于 127.0.0.1:5678 的 Kairoi 服务器进行通信：

<?php

use Kairoi\Domain\Client\Encoding\Encoder;
use Kairoi\Infrastructure\Client\Client;
use Kairoi\Infrastructure\Client\Decoding\ParsicaDecoder;

$client = new Client('tcp://:5678', new Encoder(), new ParsicaDecoder());

设置作业

一旦客户端配置完成，就可以用它来执行指令。我们将首先介绍 Job Set 指令。它的目的是在 Kairoi 中设置作业，以便在某个时刻触发。此库提供了一个 Kairoi\Domain\Job\Set\Writer 来完成这项任务。它使用一个 Kairoi\Domain\Client\ClientInterface（之前配置的客户端）和一个负责将作业转换为标准 Kairoi\Domain\Protocol\Request 的 Kairoi\Domain\Job\Set\Driver\DriverInterface 构造。该库提供了一个作为此驱动程序的默认实现的 Kairoi\Domain\Job\Set\Driver\Driver 服务。

然后，我们将使用 write 方法将单个作业设置到 Kairoi 服务器。它接受一个 Kairoi\Domain\Job\Set\Job 作为参数，并返回一个 Kairoi\Domain\Job\Set\Result，这两个都是简单的消息对象。需要注意的是，返回的结果将表示 "SET" 指令的成功（或失败）：如果作业被写入 Kairoi 服务器，则为成功，但如果在通信过程中出现错误，则为失败。作业执行状态与此完全无关。

以下是一个将作业 app.domain.job.1 设置为将来执行的示例

<?php

use Kairoi\Domain\Job\Set\Driver\Driver;
use Kairoi\Domain\Job\Set\Job;
use Kairoi\Domain\Job\Set\Writer;

$driver = new Driver();
$writer = new Writer($client, $driver);

$job = new Job(
    'app.domain.job.1',
    new \DateTime('+5 minutes')
);
$result = $writer->write($job);
if ($result->isFailure()) {
    printf("Instruction failed to be executed.\n");
}

设置规则

为了正确执行此作业，它需要匹配一个可以通过 Rule Set 指令 设置的 Kairoi 规则。Kairoi-PHP 提供了一个 Kairoi\Domain\Rule\Set\Writer，它的工作方式类似于作业写入器：它使用一个 Kairoi\Domain\Client\ClientInterface 和一个用于转换为标准请求的 Kairoi\Domain\Rule\Set\Driver\DriverInterface 构造。还提供了一个作为此驱动程序的默认实现的 Kairoi\Domain\Rule\Set\Driver\Driver。

Kairoi\Domain\Rule\Set\Rule 是用于配置规则及其相关运行器的消息对象。它接受一个作为此规则唯一标识符的 string 作为其第一个参数，一个作为匹配模式的 string 作为第二个参数，以及一个作为第三个参数的运行器。在 Kairoi 中，匹配模式是一个简单的 "以...开头" 比较：app.domain. 将匹配以该字符串开头的每个作业，例如 app.domain.job.1 或 app.domain.1，但不会匹配 app.domainjob。运行器可以是驱动程序支持的任何内容。

默认规则集驱动程序比作业集驱动程序复杂一些。它接受一个作为参数的 Kairoi\Domain\Rule\Set\Driver\Runner\DriverInterface 集合，其中每个元素负责处理一种类型的运行器。

可以配置 Shell 运行器，如下所示

<?php

use Kairoi\Domain\Rule\Set\Driver\Driver;
use Kairoi\Domain\Rule\Set\Driver\Runner\Shell as ShellDriver;
use Kairoi\Domain\Rule\Set\Rule;
use Kairoi\Domain\Rule\Set\Runner\Shell as ShellRunner;
use Kairoi\Domain\Rule\Set\Writer;

$driver = new Driver([new ShellDriver()]);
$writer = new Writer($client, $driver);

$runner = new ShellRunner('/usr/src/app/domain_job.sh');
$rule = new Rule(
    'app.rule.domain.job',
    'app.domain.job.',
    $runner
);
$result = $writer->write($rule);
if ($result->isFailure()) {
    printf("Instruction failed to be executed.\n");
}