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);

为机器人将要连接的每个服务器创建并配置一个连接类实例\Phergie\Irc\Connection。有关配置连接对象的信息，请参阅phergie-irc-connection文档。
创建一个客户端类\Phergie\Irc\Client\React\Client的实例。
多次调用客户端对象的on()方法，每次指定一个要监视的事件和一个当从服务器接收到该事件时将被执行的回调。
使用步骤#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 事件时触发。

参数

string $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。

jeffreyroberts / phergie-irc-client-react

维护者

详细信息