WARNING: Pirum is not maintained anymore; use Composer instead.
a Sensio Labs Product

The simple PEAR Channel
Server Manager

Pirum is a simple PEAR Channel Server Manager

Pirum is a simple and nice looking PEAR channel server manager that lets you setup PEAR channel servers in a matter of minutes. Pirum is best suited when you want to create small PEAR channels for a few packages written by a few developers.

Pirum consists of just one file, a command line tool, written in PHP. There is no external dependencies, no not need for a database, no need to setup credentials, and nothing need to be installed or configured.

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

As of Pirum 1.1, a composer repository is generated as well.

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

Check that Pirum works by calling it without any argument:

$ php pirum

You should see something similar to the following:

Default pirum output

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 client
  • Each channel has an HTML page describing the server and the packages it hosts
  • New releases can be tracked by subscribing to an 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.

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/
Default pirum build output

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 everything 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 subscribe 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 of 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 at symfony.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

Customizing Default Templates

Pirum generates an index.html and an pirum.css file at the PEAR root directory. It gives some information about the PEAR channel, and list all packages and versions. You can customize the templates used to generate those files by creating a templates/ directory. This directory can be in the same directory as the pirum file (for global templates if you install pirum globally) or in the PEAR root directory (pear/ in the above example - for local templates).

To get you started, you can copy and paste the default templates found in the buildIndex() and buildCss() methods.

Current Limitations

The main differences with a full-featured 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 release developer is always the first listed maintainer

Who uses Pirum?

Pirum is used by the following projects:

If you use Pirum to host your PEAR package(s) and want to be listed here, feel free to send me an email (fabien <at> symfony DOT com).

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.

The Pirum logo is © 2010 Sensio Labs