hoa/irc

The Hoa\Irc library.

, _(*1)

, _(*2)

Hoa is a modular, extensible and structured set of PHP libraries.
Moreover, Hoa aims at being a bridge between industrial and research worlds. , _(*3)

Hoa\Irc

, _(*4)

This library allows to write an IRC client, and interact through listeners and simple methods., _(*5)

Learn more., _(*6)

Installation

With Composer, to include this library into your dependencies, you need to require hoa/irc:, _(*7)

$ composer require hoa/irc '~0.0'

For more installation procedures, please read the Source page., _(*8)

Testing

Before running the test suites, the development dependencies must be installed:, _(*9)

$ composer install

Then, to run all the test suites:, _(*10)

$ vendor/bin/hoa test:run

For more information, please read the contributor guide., _(*11)

Quick usage

We propose a quick overview of a simple client that joins a channel and interacts to mentions. Next, we will enhance this client with a WebSocket server to receive external messages., _(*12)

Interact to mentions

The Hoa\Irc\Client proposes the following listeners: open, join, message, private-message, mention, other-message, ping, kick, invite and error., _(*13)

In order to connect to an IRC server, we have to use a socket client, such as:, _(*14)

$uri    = 'irc://chat.freenode.net';
$client = new Hoa\Irc\Client(new Hoa\Socket\Client($uri));

Then, we attach our listeners. When the connexion will be opened, we will join a channel, for example #hoaproject with the Gordon username:, _(*15)

$client->on('open', function (Hoa\Event\Bucket $bucket) {
    $bucket->getSource()->join('Gordon', '#hoaproject');

    return;
});

Next, when someone will mention Gordon, we will answer What?:, _(*16)

$client->on('mention', function (Hoa\Event\Bucket $bucket) {
    $data    = $bucket->getData();
    $message = $data['message']; // do something with that.

    $bucket->getSource()->say(
        $data['from']['nick'] . ': What?'
    );

    return;
});

Finally, to run the client:, _(*17)

$client->run();

Include a WebSocket server

We can add a WebSocket server to receive external messages we will forward to the IRC client. Thus, the beginning of our program will look like:, _(*18)

$ircUri = 'irc://chat.freenode.net';
$wsUri  = 'ws://127.0.0.1:8889';

$group  = new Hoa\Socket\Connection\Group();
$client = new Hoa\Irc\Client(new Hoa\Socket\Client($ircUri));
$server = new Hoa\Websocket\Server(new Hoa\Socket\Server($wsUri));

$group[] = $server;
$group[] = $client;

Then, we will forward all messages received by the WebSocket server to the IRC client:, _(*19)

$server->on('message', function (Hoa\Event\Bucket $bucket) use ($client) {
    $data = $bucket->getData();
    $client->say($data['message']);

    return;
});

Finally, to run both the IRC client and WebSocket server:, _(*20)

$group->run();

To send a message to the WebSocket server, we can use a WebSocket client in CLI:, _(*21)

$ echo 'foobar' | hoa websocket:client -s 127.0.0.1:8889

Documentation

The hack book of Hoa\Irc contains detailed information about how to use this library and how it works., _(*22)

To generate the documentation locally, execute the following commands:, _(*23)

$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open

More documentation can be found on the project's website: hoa-project.net., _(*24)

Getting help

There are mainly two ways to get help:, _(*25)

• On the #hoaproject IRC channel,
• On the forum at users.hoa-project.net.

Contribution

Do you want to contribute? Thanks! A detailed contributor guide explains everything you need to know., _(*26)

License

Hoa is under the New BSD License (BSD-3-Clause). Please, see LICENSE for details., _(*27)