Installation

Installing Pirum is as simple as downloading the latest stable pirum file and saving it where you see fit. You can also download a specific version if you want.

Of course, you can also install Pirum globally on your machine via PEAR:

$ pear channel-discover pear.pirum-project.org
$ pear install pirum/Pirum-beta

Check that Pirum works by calling it without any argument:

$ php pirum

You should see something similar to the following:

Pirum is hosted on a Git repository.

Features

Besides its size and simplicity, Pirum is packed with a lot of features:

• Creates a full-featured PEAR channel server useable by any pear CLI
• Each channel has an HTML page describing the server and the packages it hosts
• New releases can be tracked by subscribing to the Atom feed

Usage

Creating a PEAR Channel Server

Creating a new PEAR channel server is as easy as creating a single XML configuration file. For instance the whole configuration for the Pirum PEAR channel reads as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<server>
  <name>pear.pirum-project.org</name>
  <summary>Pirum PEAR channel</summary>
  <alias>pirum</alias>
  <url>http://pear.pirum-project.org/</url>
</server>

The format of this file is self-explanatory.

A PEAR channel server managed by Pirum is simply a directory full of static XML files. As such, the server can be hosted on any shared host, without the need for PHP or any other web server technology installed.

Let's create a PEAR channel server for Pirum under the pear directory:

$ mkdir pear/

Save the above XML configuration file as pear/pirum.xml.

That's all. You can now build your PEAR channel server by calling the build command:

$ php pirum build pear/

Using your PEAR Channel Server

Of course, as we have not added any PEAR package yet, you will end up with an empty PEAR channel. But nonetheless, you can already register your channel and see if everything is setup correctly (beside checking that everythings work, it is also needed to create packages for this new channel - see below):

$ pear channel-discover pear.pirum-project.org
$ pear channel-info pirum
$ pear list-all -c pirum

Pirum also generates an index.html page which explains how to use the channel and lists the packages served by the channel.

Last but not the least, Pirum also generates an Atom feed containing the latest releases. People can subscribed at /feed.xml.

Adding new Releases

Adding a new release can be done by calling the add command:

$ php pirum add pear Pirum-1.0.0.tgz

where Pirum-1.0.0.tgz is a valid PEAR package for the 1.0.0 version if Pirum. The add command also calls the build command automatically.

If you want to remove a package, simply remove the archives (the .tgz and .tar files) under the get/ directory and run the build command.

Creating a PEAR package

Refer to the PEAR website for more information about PEAR packages. If you want to get started fast, here is the package.xml file for Pirum:

<?xml version="1.0" encoding="UTF-8"?>
<package packagerversion="1.8.0" version="2.0" xmlns="http://pear.php.net/dtd/package-2.0" xmlns:tasks="http://pear.php.net/dtd/tasks-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://pear.php.net/dtd/tasks-1.0
    http://pear.php.net/dtd/tasks-1.0.xsd
    http://pear.php.net/dtd/package-2.0
    http://pear.php.net/dtd/package-2.0.xsd">
 <name>Pirum</name>
 <channel>pear.pirum-project.org</channel>
 <summary>Pirum is a simple PEAR channel server manager.</summary>
 <description>
   Pirum is a simple PEAR channel server manager.
 </description>
 <lead>
  <name>Fabien Potencier</name>
  <user>fabpot</user>
  <email>fabien.potencier@symfony-project.org</email>
  <active>yes</active>
 </lead>
 <date>2009-10-18</date>
 <time>16:00:00</time>
 <version>
  <release>0.9.0</release>
  <api>0.9.0</api>
 </version>
 <stability>
  <release>beta</release>
  <api>beta</api>
 </stability>
 <license uri="http://www.opensource.org/licenses/mit-license.php">MIT</license>
 <notes>-</notes>
 <contents>
   <dir name="/">
    <file name="LICENSE" role="doc" />
    <file name="README.markdown" role="doc" />
    <file baseinstalldir="/" name="pirum" role="script" />
   </dir>
 </contents>
 <dependencies>
  <required>
   <php>
    <min>5.0.0</min>
   </php>
   <pearinstaller>
    <min>1.4.0</min>
   </pearinstaller>
  </required>
 </dependencies>
 <phprelease />
</package>

The content of the package.xml file is important as Pirum uses its content to automatically configure your PEAR channel server information.

Generating a PEAR package is then as simple as calling the PEAR package command:

$ pear package

Support

You can get support on the mailing-list.

Current Limitations

The main differences with a full-features PEAR channel server are the following:

• No support for fallback PEAR channel servers
• No category management (all packages are under a "default" category)
• No web interface for management

The following limitations might be addressed in a future release of Pirum:

• The release developer is always the first listed maintainer
• The Pirum CLI only works on *nix servers (it assumes the tar and gunzip utilities are available)

Who uses Pirum?

Pirum is used by the following projects:

• Pirum
• Symfony
• Symfony Components
• Swift Mailer
• PHPUnit
• Twig
• phpUnderControl
• FluentDOM
• PHP Depend
• Qubit
• pearhub

If you use Pirum to host your PEAR package(s) and want to be listed here, feel free to send me an email (fabien.potencier symfony-project DOT org).

Who is behind Pirum?

Pirum is brought to you by Fabien Potencier, the creator of the symfony framework. Pirum is released under the MIT license.