Users

Installation

As of version 2.0, Phergie releases are distributed via a Pirum PEAR server at http://pear.phergie.org. If you’re looking for the 1.x branch, it still resides in the old Assembla SVN repository and is no longer in active development.

You have a few options for installing your own instance of Phergie.

PEAR Client

The recommended method of installing Phergie is to use a PEAR client. If you don’t already have a PEAR client installed, follow these instructions from the PEAR web site to install one.

If you’re using a distribution of Linux, such as Ubuntu, it may also be possible to install a PEAR package using your distribution’s package management system. Consult related documentation for your particular distribution for more information.

If you already have a PEAR client installed, just browse to http://pear.phergie.org. There, you’ll find instructions on how to use it to install the core Phergie package and any plugins you’d like to use.

Tarball

The other installation option is to browse to http://pear.phergie.org and manually download the tarballs for the core Phergie package and packages for any plugins you’d like to use.

Under the section for each package, you’ll see a Releases subsection where version numbers are linked to the corresponding tarball files. Save the tarballs for the packages you want to install and extract them using the appropriate utilities on your operating system.

If you’re on Linux, open a terminal and issue a command like the one shown below.

tar -zxf Phergie-2.0.0.tgz

If you’re using Windows, it does not natively support extracting tarballs; you’ll need to install a program like 7-Zip to do this.

Github Repository

Version control for the Phergie project is hosted on Github. You can go to its project page for the address to clone the repository and Github Help for more information on how to do this. Directions for operating such a clone correspond to those for manual installations included in subsequent sections of this page.

Getting Started

If you installed Phergie using a PEAR client, one of the advantages of doing so is that a command line executable is included in the installation. As a result, you can open a terminal in your operating system and launch Phergie using a shell command like any other.

phergie

The phergie executable accepts a variable number of parameters, each of which is the path to a PHP file containing configuration settings. If no parameters are passed, the executable defaults to searching for a file in the current working directory calling Settings.php (notice the capital “S”, which may be relevant if your filesystem is case-sensitive) and will terminate if such a file is not found.

phergie /path/to/config1.php /path/to/configN.php

If your installed Phergie manually from a tarball, you’ll find a phergie.php file in the root directory to which you extracted the tarball. This is the same as the command line executable mentioned earlier, but must be installed manually. It can be run like any other PHP CLI script.

php phergie.php /path/to/config1.php

If you’re on Linux and you’d like to run Phergie as a command line executable, simply modify the shebang line of this file to conform to the location of the PHP CLI executable on your system and place the file in your PATH. You may optionally rename the file to remove the .php file extension.

If you’re on Windows, a phergie.bat file is included in the tarball. This simply locates your local PHP CLI interpreter and uses that to run the included phergie.php script. Place both in a directory included in your PATH environmental variable if you’d like to run the script from a command line by only specifying the filename rather than the full path to the file.

Configuration

If you installed Phergie using a PEAR client, you’ll file a sample configuration file Settings.php.dist within your PEAR data directory. To get the path to this directory, open a terminal and enter the command below.

pear config-show

Look for a line resembling this one. The path to the directory is listed in the last column. Within this directory, there will be a Phergie directory. The sample Settings.php.dist file will be located here.

PEAR data directory            data_dir         /usr/share/php/data

Make a copy of the Settings.php.dist file and open it in your preferred text editor. The file need only return an array containing various configuration settings. The sample file is fairly well documented and easy to follow.

<?php
return array(
    // One array per connection, pretty self-explanatory
    'connections' => array(
        // Ex: All connection info for the Freenode network
        array(
            'host' => 'irc.freenode.net',
            'port' => 6667,
            'username' => 'Elazar',
            'realname' => 'Matthew Turland',
            'nick' => 'Phergie2',
            // 'password' => 'password goes here if needed',
            // 'transport' => 'ssl' // uncomment to connect using SSL
        )
    ),

    // Whitelist of plugins to load
    'plugins' => array(
        // 'ShortPluginName'
        // ex: 'AutoJoin' for 'Phergie_Plugin_AutoJoin'
    ),

    // If set to true, this allows any plugin dependencies for plugins
    // listed in the 'plugins' option to be loaded even if they are not
    // explicitly included in that list
    'plugins.autoload' => true,

    // Enables shell output describing bot events via Phergie_Ui_Console
    'ui.enabled' => true,
);

Note that the file need not contain only a single statement returning an anonymous array. In fact, it’s useful to split the creation of the array into multiple statements to allow previously set values to be used when setting other values. Regardless, the file must eventually return an array with values for all the settings listed in the sample file.

Plugins

If you’re using a PEAR client, plugin packages are installed in the same fashion as the core package; the only thing that varies is the package name in the command you issue to perform the installation.

If you’re installing package tarballs manually, you can download them from the PEAR server page just as you did the core package. Simply extract plugin tarballs to the same directory to which you originally extracted the core tarball. Each plugin package includes the necessary directory structure such that the plugin files will be installed to the Phergie/Plugin subdirectory within that directory.

Once the plugin files are installed, modify your configuration file such that the “plugins” option includes the short name of the plugin. For example, if you’re installing the Phergie_Plugin_AutoJoin package, then "AutoJoin" would be the plugin’s short name. Review documentation included with the plugin for more information about its configuration settings.

Here are a few plugins that are considered “bare necessities.”

  • Pong: IRC servers sporadically check to ensure that clients are still connected by sending a PING event and expecting a PONG response. If no response is received after several attempts, the server terminates the connection from its side. This plugin handles sending PONG responses when needed; as such, it is vital to maintaining a consistent connection.
  • AutoJoin: This plugin can be used to have the bot automatically join specific channels once it successfully connects to the server. These channels are specified using the autojoin.channels configuration setting. See the class docblock in the plugin file for more information.
  • Quit: This plugin causes the bot to gracefully terminate its connection when it detects a message that simply reads “quit” sent either directly to the bot or to a channel it inhabits.
  • Prioritize: The order in which plugins process events by default is random. As such, the bot may end up processing a response to an event that causes it to terminate before processing a response to send a message to a channel. Before responses are dispatched, this plugin reorders responses to be transmitted in order from least to most destructive, such that the bot doesn’t quit until all other responses have been sent.
  • AltNick: This plugin handles the situation of the bot’s nick already being taken by another user. It tries switching to other nicks from a supplied list.