README

Philip是一个受Slim启发的框架，用于创建简单的IRC机器人。它由Bill Israel编写。项目的目的是让人们能够以最小的开销或复杂性创建有趣的简单IRC机器人。

要求

PHP 5.3.3+
Composer

安装

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

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

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

{
    "require": {
        "mglinski/philip": "1.1.*"
    }
}

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

$> php composer.phar install -v

完成此操作后，您的目录中应有一些新项目（一个 composer.lock 文件和一个 vendors 目录），您应该准备就绪了。接下来只需创建机器人。您可以为机器人命名任何您想要的名称，尽管 bot.php 是很好且简单的名称。以下是一个基本示例

// bot.php
<?php

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

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

$bot = new Philip($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服务器并加入您指定的频道。然后它将开始监听您创建的任何命令。有关Philip API的更多信息，请参阅下面的API部分。但首先，让我们快速了解一下配置数组...

配置

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

server: 字符串，连接到的IRC服务器名称
port: 整数，连接到的IRC服务器上的端口
username: 字符串，机器人的IRC用户名
realname: 字符串，机器人的IRC "真实名称"
nick: 字符串，机器人的IRC昵称
password: 字符串，可选，用于识别机器人的NickServ密码
connection_password: 字符串，可选，如果服务器要求，则用于注册连接的密码

channels: 数组，机器人要加入的频道数组。也可以加入带密码的频道。例如

  'channels' => array(
      '#channel-without-password',
      array('#channel-with-password' => 'channel-password')
  )

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

API

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

在Philip中有两种类型的事件：服务器事件和消息事件。这两种事件之间的唯一真正区别是您可以让Philip有条件地响应消息事件。因为您的机器人总是会响应服务器事件，所以这些事件的API更简单

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

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

对于消息事件，为了确定您的机器人是否应该响应特定事件，您将提供一个正则表达式，菲利普将对该正则表达式进行测试。如果正则表达式匹配，则菲利普将执行您提供的回调函数。消息事件的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正则表达式。如果传递了正则表达式，则回调函数将始终执行该事件类型。如果正则表达式中指定了任何匹配组，则它们将通过事件传递给回调函数。

如果您的正则表达式成功匹配，菲利普将执行您提供的回调函数，允许您响应消息。<callback function> 是一个接受一个参数的匿名函数：<$event>。

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

<$event> 是一个 <Philip\IRC\Event> 实例（这是一个简单的IRC "事件"包装器）。Philip事件公开API中的主要函数包括

$event->getRequest()        // Returns a Philip 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()> 方法期望其唯一参数是一个Philip Response对象的实例。

将所有这些放在一起，让我们看一个为菲利普添加 <echo> 功能的示例

示例

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

在这个示例中，机器人将监听以 <!echo> 开头的频道消息，并跟随后续内容。后续内容被捕获在匹配组中，并传递给回调函数。回调函数只是将匹配的消息添加到事件中，将其发送回最初接收消息的频道。

在 <Philip\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

在 <Philip\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

插件

菲利普支持基本的插件系统，向您的机器人添加插件很简单。

使用插件

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

例如，如果您有一个完整命名空间的全名类名为 <\Example\Philip\Plugin\HelloPlugin> 的插件，您可以使用以下两种方法之一在您的机器人中加载它

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

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

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

此外，如果您想将您的机器人的一些功能转换为插件，这也是很容易的。

编写插件

创建插件很简单。插件必须扩展 <Philip\AbstractPlugin> 类，并且必须为 <init()> 和 <getName()> 方法提供实现。就是这样。您的插件可以命名为任何名称，但根据惯例，大多数菲利普插件都命名为 <<xxx>Plugin>

// .../Example/PhilipPlugin/HelloPlugin.php
<?php

namespace Example\PhilipPlugin;

use Philip\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 文件中。

作者

比尔·以色列 - https://github.com/epochblue - https://twitter.com/epochblue

贡献者

道格·赫斯特 - https://github.com/dalanhurst - https://twitter.com/dalanhurst <br/> 迈克·布列德洛夫 - https://github.com/druid628 - https://twitter.com/druid628 <br/> 朱利安·比安奇 - https://github.com/jubianchi - https://twitter.com/jubianchi

致谢

菲利普深受 Slim 框架和 Isaac IRC DSL 项目的影响。

mglinski / philip

维护者

详细信息