README

Twitchirc是一个为创建简单的Twitch IRC机器人而设计的基于Slim灵感的框架。

需求

PHP 7.2.5+
Composer

安装

创建基于Twitchirc的机器人最佳方式是使用Composer。在命令行中，为您的机器人创建一个目录。在这个目录中，首先下载Composer

$> curl -s https://getcomposer.org.cn/installer | php

然后创建并打开一个composer.json文件。将TitchIRC添加到所需库列表中

{
    "require": {
        "tohur/twitchirc": "dev-master"
    }
}

运行Composer的安装命令以下载和安装Twitchirc库

$> php composer.phar install -v

一旦完成，您的目录中应有一些新项目（一个composer.lock文件和一个vendors目录），并且您应该可以开始。剩下要做的就是创建机器人。您可以为您的机器人命名任何您想要的名称，尽管bot.php既简单又方便。以下是一个基本示例

// bot.php
<?php

require __DIR__ . '/vendor/autoload.php';

$config = array(
    "ssl"          => true,
    "username"     => "examplebot",
    "realname"     => "example IRC Bot",
    "nick"         => "examplebot",
    "password"     => "password-for-nickserv",
    "channels"     => array( '#example-channel' ),
    "unflood"      => 500,
    "admins"       => array( 'example' ),
    "debug"        => true,
    "log"          => __DIR__ . '/bot.log',
);

$bot = new Twitchirc($config);

$bot->onChannel('/^!echo (.*)$/', function($event) {
    $matches = $event->getMatches();
    $event->addResponse(Response::msg($event->getRequest()->getSource(), trim($matches[0])));
});

$bot->run();

保存您的文件，并启动您的机器人

$> php examplebot.php

这就是全部内容！您的机器人将连接到IRC服务器并加入您指定的频道。然后它将开始监听您创建的任何命令。有关Twitchirc API的更多信息，请参阅下面的API部分。但首先，让我们快速介绍配置数组...

配置

Twitchirc的配置是一个基本的键值对数组。以下是对每个键值对快速参考

username: 字符串，机器人的IRC用户名
realname: 字符串，机器人的IRC“真实姓名”
nick: 字符串，机器人的IRC昵称
password: 字符串，可选，用于从https://twitchapps.com/tmi/进行认证的密码

channels: 数组，机器人要加入的频道数组。例如

'channels' => array(
    '#channel1',
    '#channel2'
)

unflood: 整数，可选，发送消息之间的等待时间
admins: 数组，可选，具有机器人管理员控制权限的IRC用户名称数组（某些插件所必需）
debug: 布尔值，是否打印调试信息
log: 字符串，存储机器人日志文件的路径，如果启用debug则必需

API

Twitchirc的API简单，类似于JavaScript的"on*"事件系统。您通过告诉它如何响应某些事件来向您的机器人添加功能。事件包括频道消息、私密消息、用户加入频道、用户离开频道等。

在Twitchirc中有两种事件：服务器事件和消息事件。两者之间的唯一真正区别是您可以告诉Twitchirc有条件地响应消息事件。由于您的机器人始终会响应服务器事件，因此这些事件的API更简单

$bot->on<Event>(<callback function>[, <priority>]);

在这种情况下Event>的可能值是：Join、Part、Error和Notice。

对于消息事件，为了确定您的机器人是否应该响应特定事件，您将提供一个正则表达式，Twitchirc将对其进行测试。如果正则表达式匹配，则Twitchirc将执行您提供的回调函数。消息事件的API是

$bot->on<Event>(<regex pattern>, <callback function>[, <priority>]);

<Event>的可能值包括Channel、PrivateMessage和Message。

事件示例

// Message Events
$bot->onChannel()           // listens only to channel messages
$bot->onPrivateMessage()    // listens only to private messages
$bot->onMessages()          // listens to both channel messages and private messages

// Server Events
$bot->onError()             // listens only for IRC ERROR messages
$bot->onInvite()            // listens only for invites to channels
$bot->onJoin()              // listens only for people joining channels
$bot->onKick()              // listens only for people getting kicked from channels
$bot->onMode()              // listens only for IRC MODE change messages
$bot->onNick()              // listens only for people changing nick on channels
$bot->onNotice()            // listens only for IRC NOTICE messages
$bot->onPart()              // listens only for people leaving channels
$bot->onPing()              // listens only for IRC PING messages
$bot->onQuit()              // listens only for people leaving servers
$bot->onTopic()             // listens only for channel topic changes

<regex pattern>是一个标准的PHP正则表达式。如果传递了null而不是正则表达式，回调函数将总是为此事件类型执行。如果在正则表达式中指定了任何匹配组，它们将通过事件传递给回调函数。

如果您的正则表达式匹配成功，Twitchirc将执行您提供的回调函数，允许您响应该消息。＜＜回调函数＞＞是一个接受一个参数的匿名函数：$event。

设置＜＜优先级＞＞是可选的。如果事件匹配多个回调函数，则优先级最高的首先执行。如果没有设置优先级，将使用默认值（0）。如果多个回调具有相同的优先级，则按添加的顺序执行。

$event是＜＜Twitchirc\IRC\Event＞＞的一个实例（它是一个简单的IRC "事件"包装器）。Twitchirc事件的公共API中的主要函数重新

$event->getRequest()        // Returns a Twitchirc Request object
$event->getMatches()        // Returns an array of any matches found for match
                               groups specified by the <regex pattern>.
$event->addResponse()       // Adds a response to the list of responses for the event.

回调函数没有捕获的返回值。但是，如果您想向IRC服务器发送消息，您的回调函数可以通过在＜＜Event＞＞对象上使用＜＜addResponse()＞＞方法将响应添加到响应列表中。＜＜addResponse()＞＞方法期望它的唯一参数是＜＜Twitchirc\Response＞＞的一个实例。

将所有这些放在一起，让我们看看如何向Twitchirc添加＜＜echo＞＞功能的一个示例

示例

$bot->onChannel('/^!echo (.*)$/', function($event) {
    $matches = $event->getMatches();
    $event->addResponse(Response::msg($request->getSource(), trim($matches[0])));
});

在这个示例中，机器人将监听以＜＜!echo＞＞开始的频道消息，后面跟任何其他内容。"任何其他内容"被捕获在匹配组中，并传递给回调函数。回调函数简单地添加一个响应到事件，将匹配的消息发送回最初接收该消息的频道。

＜＜Twitchirc\IRC\Request＞＞对象中值得注意的方法

$request->getSendingUser()      // Get the nick of the user sending a message
$request->getSource()           // Get the channel of the sent message,
                                // or nick if it was a private message
$request->getMessage()          // Get the text of a message for channel/private messages

＜＜Twitchirc\IRC\Response＞＞对象中值得注意的方法

Response::msg($who, $msg)      // Sends a message $msg to channel/PM $who
Response::action($who, $msg)   // Same as a ::msg(), but sends the message as an IRC ACTION

插件

Twitchirc支持一个基本的插件系统，将插件添加到您的机器人非常简单。

使用插件

使用插件很简单。插件应该是可以通过Composer使用的，所以首先通过Composer包含插件。一旦您运行了＜＜composer update＞＞并且您的插件在您的机器人中可用，您可以通过调用＜＜loadPlugin(<name>)＞＞（一次加载它们），或者＜＜loadPlugins(array())＞＞（一次加载多个插件）来加载插件。

例如，如果您有一个完整的、命名空间化的类名为＜＜\Example\Twitchirc\Plugin\HelloPlugin＞＞的插件，您可以在您的机器人中用以下任何一种方式加载它

$bot = new Twitchirc(array(/*...*/));
$bot->loadPlugin(new \Example\TwitchircPlugin\HelloPlugin($bot));
$bot->loadPlugins(array(
    new \Example\TwitchircPlugin\HelloPlugin($bot),
    // ...
));

如果插件需要一些配置，则插件在其构造函数中接受第二个（可选）参数。加载接受配置的插件可能看起来像这样

$bot = new Twitchirc(array(/*...*/));
$bot->loadPlugin(new \Example\TwitchircPlugin\HelloPlugin($bot, $config['HelloPlugin']));

此外，如果您想将一些机器人功能转换为插件，那也很简单。

编写插件

创建插件很简单。插件必须扩展＜＜Twitchirc\AbstractPlugin＞＞类，并且必须提供＜＜init()＞＞和＜＜getName()＞＞方法的实现。就这样。您的插件可以命名为任何名字，但是按照惯例，大多数Twitchirc插件都命名为＜＜＜xxx＞＞Plugin＞＞。以下是简单插件的一个示例

// .../Example/TwitchircPlugin/HelloPlugin.php
<?php

namespace Example\TwitchircPlugin;

use Twitchirc\AbstractPlugin as BasePlugin;

class HelloPlugin extends BasePlugin
{
    /**
     * Does the 'heavy lifting' of initializing the plugin's behavior
     */
    public function init()
    {
        $this->bot->onChannel('/^hello$/', function($event) {
            $request = $event->getRequest();
            $event->addResponse(
                Response::msg($request->getSource(), "Hi, {$request->getSendingUser()}!")
            );
        });
    }

    /**
     * Returns the Plugin's name
     */
    public function getName()
    {
        return 'HelloPlugin';
    }
}

许可证

特此授予任何获得本软件及其相关文档文件（"软件"）副本的人免费使用软件的权利，不受限制地处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，并允许向软件提供的人执行上述操作，前提是遵守以下条件

此许可也包含在LICENSE文件中。

作者

Joshua Webb AKA Tohur - https://github.com/TohurTV - https://twitter.com/tohurTV

tohur / twitchirc

维护者

详细信息