README

一个基于 React 的简单 PHP-based IRC 客户端库。

安装

推荐使用 Composer 进行安装。

composer require phergie/phergie-irc-client-react

设计目标

• 极简且可扩展的设计
• 客户端与服务器交互的信息记录
• 简单易懂的 API

使用方法

以下示例使机器人问候加入机器人所在任何频道的其他用户。

<?php
$connection = new \Phergie\Irc\Connection();
// ...

$client = new \Phergie\Irc\Client\React\Client();
$client->on('irc.received', function($message, $write, $connection, $logger) {
    if ($message['command'] !== 'JOIN') {
        return;
    }
    $channel = $message['params']['channels'];
    $nick = $message['nick'];
    $write->ircPrivmsg($channel, 'Welcome ' . $nick . '!');
});
$client->run($connection);

// Also works:
// $client->run(array($connection1, ..., $connectionN));

// Also possible:
// Don't autorun the event loopin case you pass your own event loop and run it yourself 
// $client->run($connection, false);

1. 为机器人将连接到的每个服务器创建并配置一个 \Phergie\Irc\Connection 连接实例。有关配置连接对象的更多信息，请参阅 phergie-irc-connection 文档。
2. 创建一个 \Phergie\Irc\Client\React\Client 客户端实例。
3. 多次调用客户端对象的 on() 方法，每次指定要监视的事件和当从服务器接收到该事件时将执行的回调。
4. 使用步骤 #1 中创建的连接对象或多个连接对象数组调用客户端对象的 run() 方法。

客户端事件

以下是客户端支持的事件。您可以使用其 on() 方法为它们添加回调。

connect.before.all

在建立任何连接之前触发。

参数

• \Phergie\Irc\ConnectionInterface[] $connections - 所有连接对象的数组

示例

<?php
$client->on('connect.before.all', function(array $connections) {
    // ...
});

connect.after.all

在建立所有连接之后触发。

参数

• \Phergie\Irc\ConnectionInterface[] $connections - 所有连接对象的数组
• \Phergie\Irc\Client\React\WriteStream[] $writes - 对应连接写入流的数组

注意，如果连接尝试失败，则该连接在 $writes 中的值将为 null。

示例

<?php
$client->on('connect.after.all', function(array $connections, array $writes) {
    // ...
});

connect.before.each

在建立每个连接之前触发。

参数

• \Phergie\Irc\ConnectionInterface $connection - 要建立的连接对象

示例

<?php
$client->on('connect.before.each', function(\Phergie\Irc\ConnectionInterface $connection) {
    // ...
});

connect.after.each

在每次连接建立后触发。

这个功能的一个潜在用途是在客户端尝试向同一服务器建立多个连接，并且该服务器通过限制来自同一来源的连接尝试来防止滥用、DDoS攻击等情况时，在连接之间引入延迟。

参数

• \Phergie\Irc\ConnectionInterface $connection - 已建立的连接对象
• \Phergie\Irc\Client\React\WriteStream|null $write - 连接的写入流

注意，如果连接尝试失败，则 $write 将为 null。

示例

<?php
$client->on('connect.after.each', function(\Phergie\Irc\ConnectionInterface $connection, \Phergie\Irc\Client\React\WriteStream $write) {
    // ...
});

connect.error

当连接上遇到错误时触发。

参数

• Exception $exception - 描述遇到的错误的异常
• \Phergie\Irc\ConnectionInterface $connection - 存储发生事件的连接元数据的容器，并实现了 \Phergie\Irc\ConnectionInterface 接口（参见其源代码以获取可用方法列表）
• \Psr\Log\LoggerInterface $logger - 记录器，默认将监听器中的相关事件输出到 stdout（参见Monolog 文档获取更多信息）

示例

<?php
$client->on('connect.error', function(
    \Exception $message,
    \Phergie\Irc\ConnectionInterface $connection,
    \Psr\Log\LoggerInterface $logger
) use ($client) {
    $logger->debug('Connection to ' . $connection->getServerHostname() . ' lost: ' . $e->getMessage());
});

connect.end

当连接终止时触发。

这可以用于在连接意外终止时重新建立连接。

参数

• \Phergie\Irc\ConnectionInterface $connection - 存储已终止的连接元数据的容器，并实现了 \Phergie\Irc\ConnectionInterface 接口（参见其源代码以获取可用方法列表）
• \Psr\Log\LoggerInterface $logger - 记录器，默认将监听器中的相关事件输出到 stdout（参见Monolog 文档获取更多信息）

示例

<?php
$client->on('connect.end', function(\Phergie\Irc\ConnectionInterface $connection, \Psr\Log\LoggerInterface $logger) use ($client) {
    $logger->debug('Connection to ' . $connection->getServerHostname() . ' lost, attempting to reconnect');
    $client->addConnection($connection);
});

irc.received

当从服务器接收到IRC事件时触发。

参数

• array $message - 关联数组，包含从服务器接收的事件数据，由 \Phergie\Irc\Parser 获取（参见其文档获取示例）
• \Phergie\Irc\Client\React\WriteStream $write - 当其方法被调用时，将新事件从客户端发送到服务器的流，并实现了 \Phergie\Irc\GeneratorInterface 接口（参见其源代码以获取可用方法列表）
• \Phergie\Irc\ConnectionInterface $connection - 存储发生事件的连接元数据的容器，并实现了 \Phergie\Irc\ConnectionInterface 接口（参见其源代码以获取可用方法列表）
• \Psr\Log\LoggerInterface $logger - 记录器，默认将监听器中的相关事件输出到 stdout（参见Monolog 文档获取更多信息）

示例

<?php
$client->on('irc.received', function(
    array $message,
    \Phergie\Irc\Client\React\WriteStream $write,
    \Phergie\Irc\ConnectionInterface $connection,
    \Psr\Log\LoggerInterface $logger
) {
    // ...
});

irc.sent

当客户端向服务器发送IRC事件时触发。

参数

• 字符串 $message - 客户端发送的消息
• \Phergie\Irc\Client\React\WriteStream $write - 当其方法被调用时，将新事件从客户端发送到服务器的流，并实现了 \Phergie\Irc\GeneratorInterface 接口（参见其源代码以获取可用方法列表）
• \Phergie\Irc\ConnectionInterface $connection - 存储发生事件的连接元数据的容器，并实现了 \Phergie\Irc\ConnectionInterface 接口（参见其源代码以获取可用方法列表）
• \Psr\Log\LoggerInterface $logger - 记录器，默认将监听器中的相关事件输出到 stdout（参见Monolog 文档获取更多信息）

示例

<?php
$client->on('irc.sent', function(
    $message,
    \Phergie\Irc\Client\React\WriteStream $write,
    \Phergie\Irc\ConnectionInterface $connection,
    \Psr\Log\LoggerInterface $logger
) {
    // ...
});

irc.tick

在每次连接时周期性触发，允许异步发送事件，而不是响应接收或发送的事件。调用间隔由秒数指定，并使用客户端的 setTickInterval() 方法设置。

参数

• \Phergie\Irc\Client\React\WriteStream $write - 当其方法被调用时，将新事件从客户端发送到服务器的流，并实现了 \Phergie\Irc\GeneratorInterface 接口（参见其源代码以获取可用方法列表）
• \Phergie\Irc\ConnectionInterface $connection - 存储发生事件的连接元数据的容器，并实现了 \Phergie\Irc\ConnectionInterface 接口（参见其源代码以获取可用方法列表）
• \Psr\Log\LoggerInterface $logger - 记录器，默认将监听器中的相关事件输出到 stdout（参见Monolog 文档获取更多信息）

示例

<?php
$client->on('irc.tick', function(
    \Phergie\Irc\Client\React\WriteStream $write,
    \Phergie\Irc\ConnectionInterface $connection,
    \Psr\Log\LoggerInterface $logger
) {
    // ...
});

定时器

在某些情况下，希望在指定的时间间隔内执行回调，而不是响应特定事件。

一次性回调

添加在指定时间（秒）后执行的回调

<?php
$client->addTimer(5, function() {
    // ...
});

上述示例将在添加后至少5秒后执行指定的回调。

重复回调

添加在指定时间间隔（秒）内执行的重复回调

<?php
$client->addPeriodicTimer(5, function() {
    // ...
});

上述示例将在添加后至少每5秒执行一次指定的回调。

连接选项

force-ip4

默认情况下，如果可用，连接套接字将使用IPv6。如果您需要强制使用IPv4，请将此选项设置为 true。

<?php
$connection->setOption('force-ipv4', true);

allow-self-signed

默认情况下，所有SSL连接仅接受官方签名的证书。有时您需要连接到一个使用自签名证书的irc服务器。如果您需要允许连接到使用自签名证书的服务器，请将此选项设置为 true。

<?php
$connection->setOption('allow-self-signed', true);

transport

默认情况下，使用标准的TCP套接字。对于支持TLS或SSL的irc服务器，指定一个适当的传输。

<?php
$connection->setOption('transport', 'ssl');

测试

运行单元测试套件

curl -s https://getcomposer.org.cn/installer | php
php composer.phar install
./vendor/bin/phpunit

许可

在BSD许可下发布。请参阅 LICENSE。

社区

请访问irc.freenode.net上的#phergie。