Marvirc is a dead simple, extremely modular and blazing fast IRC bot (yup, that's it).

Installation

With Composer, you only need to type:

$ composer install

Or, if you have Hoa widely-installed (in /usr/local/lib/Hoa) and up to date, you need nothing particular.

Usage

Marvirc can be run from CLI with marvirc. By default, marvirc welcome will run. It lists the available commands. The only one for now is marvirc join. The join command has the following options:

-s/--socket, the socket client URI (default: chat.freenode.org:6667),
-u/--username, username of Marvirc,
-c/--channel, the first channel to join, with the leading #,
-p/--password, the password of the first channel (default: null, i.e. no password),
-f/--channel-filter channels that can be joined, based on a PCRE pattern, with delimiters and options,
-w/--websocket, the WebSocket server URI (default: null, i.e. no server will be started),
-v/--verbose, be verbose or not,
-h/-?/--help, the help.

So, to join the channel #hoaproject on Freenode with the FakeMarvirc username, you will write:

$ marvirc join --socket   chat.freenode.org:6667 \
               --username FakeMarvirc            \
               --channel  '#hoaproject'

That's all. On Windows, simply use marvirc.bat.

Tips: use nohup to detach Marvirc from your current SSH session:

$ nohup marvirc join …

Features

Marvirc has the following features.

Based on Hoa

Hoa is a modular, extensible and structured set of PHP libraries. Marvirc is based on the following awesome libraries: Hoa\Irc, Hoa\Socket, Hoa\Stream etc. Moreover, Marvirc uses Hoa\Websocket for an extreme modularity, see below.

Also, it works on Linux, BSD and even Windows (yup!).

Custom actions on mentions, messages and private messages

Marvirc is able to react to mentions, messages and private messages. Actions are attached to each category through simple classes. An action interface is provided and asks to write only three methods: getPattern, getUsage and compute. Based on the pattern, Marvirc will choose the appropriated actions to run.

Here is a simple example of the “date” command that will run when the “date”, “time” or “today” keywords appear on mention, in Source/Marvirc/Action/Mention/Date.php:

<?php

namespace Marvirc\Action\Mention {

class Date implements \Marvirc\Action\IAction {

    public static function getPattern ( ) {

        return '#\b(date|time|today)\b#i';
    }

    public static function getUsage ( ) {

        return 'Get the current datetime from the server.';
    }

    public static function compute ( Array $data ) {

        return date('g\hi, l jS, F Y');
    }
}

}

So, if the username of Marvirc is FakeMarvirc, when someone writes:

Someone> FakeMarvirc: what time is it?

Marvirc will receive a mention and will run the “date” command. The result will be like:

FakeMarvirc> Someone: 1h23, Monday 1st January 2042

Really simple isn't?

Multi-channels

A single client instance can be present and interact on several channels at the same time, including private discussions.

A PCRE pattern representing channels, where the bot can be invited, can be provided through the -f/--channel-filter option. Thus, you can control where the bot will interact when someone runs:

Someone> /invite Marvirc

For example, with:

$ marvirc join --socket         chat.freenode.org:6667 \
               --username       FakeMarvirc            \
               --channel        '#hoaproject'          \
               --channel-filter '/#hoaproject-.+/'

The bot can be invited on #hoaproject-foo, #hoaproject-bar-baz but not #qux.

The footprint of an instance is quite ridiculous. Thus, if you want to run several clients, connected to several IRC servers, it is possible, discreet and understated.

Possession through WebSocket: realtime notifications

A WebSocket server can run side-by-side with the IRC client. Every message received by the WebSocket server is redirected verbatim on the IRC client. In this way, every tools, such Git hooks, cron tasks etc, is able to send a notification on IRC, as soon as you have a WebSocket client. Fortunately for us, a dead simple client exists, namely hoa websocket:client that uses a readline (which works on a regular standard input, a pipe or a redirection). Thus:

$ marvirc join --socket    chat.freenode.org:6667 \
               --username  FakeMarvirc            \
               --channel   '#hoaproject'          \
               --websocket 127.0.0.1:8889 &
$ echo 'You are awesome :-).' | hoa websocket:client --server 127.0.0.1:8889

And then, on #hoaproject, you will see Marvirc saying You are awesome :-). Imagine a Git hook that notifies you about what you need… exciting aye?

hoaproject / Marvirc