Irc Bot Bundle Laravel Package

Getting Started

First, calibrate expectations: this is not a Laravel package. whisller/irc-bot-bundle is a Symfony2 bundle (circa 2013, PHP 5.3/5.4 era) that has been archived and receives no updates. There is no service provider, no facade, no config/irc-bot.php, and it will not composer require cleanly into a modern Laravel app without constraint surgery.

Where to look first, in this order:

1. composer.json — confirm the Symfony version constraint (likely ~2.0/~2.1) and whether there is even a tagged release. The 2013-11-05 "release" suggests a dev-master-only situation.
2. DependencyInjection/Configuration.php + WhisllerIrcBotExtension.php — this is the real API surface. Everything configurable (server, port, nick, channels, command map) lives in this config tree.
3. Command/ — the console entrypoint that starts the bot loop. This is the thing you will end up wrapping or porting.
4. Event/ and EventListener/ — the message-received hooks you would attach behavior to.

Minimal path to a first runnable bot:

composer create-project symfony/framework-standard-edition irc-demo "2.8.*"
cd irc-demo
composer require whisller/irc-bot-bundle:dev-master

Register the bundle in app/AppKernel.php, add a whisller_irc_bot: block to app/config/config.yml (server, port, nick, channels), and run the bundle's console command. The canonical first use case is a "ping/pong" bot: join a channel, listen for !ping, respond pong. That exercises the full config → connect → parse → dispatch → respond path in one sitting.

Implementation Patterns

Run the bot as a long-lived process, not inside a request. The bundle ships a Symfony console command that owns a blocking socket read loop. In a Laravel context, do not try to invoke it from a controller. Wrap it in an Artisan command and supervise it:

// app/Console/Commands/IrcBot.php
protected $signature = 'irc:bot';
public function handle()
{
    // Either shell out to the Symfony command in a legacy app...
    // ...or, more realistically, port the loop into this class.
}

Run under Supervisor/systemd. The bot is a daemon, and treating it as one from day one avoids the "works until the terminal closes" trap.

Drive behavior through listeners, not edits to the loop. The bundle's design is event-based: the socket loop reads a line, emits a message event, and your listeners decide what to do. Keep the loop untouched and attach handlers that pattern-match on channel + nick + message body. This keeps your business logic portable if you later replace the bundle with a maintained IRC library.

Separate "parse" from "act." For each incoming message, resolve intent (regex/command prefix) in a pure class, then dispatch side effects (HTTP call, DB write, Slack relay) through Laravel jobs or events. The socket loop should be thin enough to unit test without a live IRC connection.

Reuse the config tree as a feature map. The bundle's YAML config is a natural place to declare channel→handler bindings or a command→class map. If you port the loop out, keep that config shape — it makes the bot declarative and lets non-PHP contributors add commands.

Bridge to Laravel via the framework's HTTP kernel. Because the bundle predates Laravel's container conventions, the cleanest integration is: run the bot in its own process, have listeners POST to an internal Laravel route (or push to a queue) when they need app services. This decouples the legacy Symfony runtime from your modern app and sidesteps container-incompatibility entirely.

Gotchas and Tips

• Archived means frozen. No security patches, no PHP 8 compatibility, no IRCv3 support. Audit composer.lock and expect to vendor/fork the package if you keep it.
• PHP 5.x syntax. The code predates scalar type hints, short array syntax in places, and ::class. It will parse on PHP 8 in many cases but is untested there; do not assume it runs.
• Old Symfony DI format. Config uses %parameters% placeholders and the 2.x extension loading conventions. Modern Laravel/Symfony containers will reject it — don't try to load the bundle in a Laravel app kernel.
• Blocking loop, no reconnect. There is no backoff/heartbeat logic baked in. IRC will drop you on network blips and idle timeouts. You must implement PING/PONG handling and reconnect-with-backoff yourself; wrap the process in Supervisor with autorestart=true as a blunt fallback.
• Protocol edge cases. Expect to handle nick collision (433), channel keyed joins, CTCP VERSION/ACTION, and multiline message splitting (>512-byte lines) manually — the bundle will not do it for you.
• PONG is your liveness probe. If the bot silently stops responding after ~5 minutes, it is almost certainly a missed server PING, not a code bug.
• Debug at the socket, not the handler. When messages "vanish," log the raw line off the stream before parsing. The bundle's event layer hides malformed lines.
• Test with a fake stream. Refactor the read/write into an injectable stream interface so you can feed canned IRC lines in tests instead of standing up a server.
• Extension point to keep: the dispatcher. If you fork, preserve the event contract — it is the only clean seam in the package and the one thing worth carrying forward if you migrate to a maintained library.