How to set up your own PEAR channel

If you want to make your projects available to users as PEAR packages you will most likely want a PEAR channel. This way users can install/upgrade/remove your packages by using the pear command. There are a couple of solutions available when setting up your own channel. One of the most popular is called Pirum, which I will be covering in this post.

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.

First you will need to install Pirum. This can be done via pear:

christer@aurora:~$ sudo pear channel-discover pear.pirum-project.org
Adding Channel "pear.pirum-project.org" succeeded
Discovery of channel "pear.pirum-project.org" succeeded
christer@aurora:~$ sudo pear install pirum/Pirum
downloading Pirum-1.0.0.tgz ...
Starting to download Pirum-1.0.0.tgz (11,732 bytes)
.....done: 11,732 bytes
install ok: channel://pear.pirum-project.org/Pirum-1.0.0

If your PEAR environment is set up correctly you should now have an executable called pirum. Run the command to see what it can do:

christer@aurora:~$ pirum
Pirum 1.0.0 by Fabien Potencier
Available commands:
pirum build target_dir
pirum add target_dir Pirum-1.0.0.tgz

The first thing you want to do is just choose a target directory for where you want to have your channel along with the packages served by the channel. Create the target directory and add a file called pirum.xml inside it that will be used by pirum when building the channel. The file can look like this:

<?xml version="1.0" encoding="UTF-8" ?>
<server>
  <name>pear.starzinger.net</name>
  <summary>Starzinger PEAR channel</summary>
  <alias>stz</alias>
  <url>http://pear.starzinger.net/</url>
</server>

This is the pirum.xml file I used when setting up pear.starzinger.net. Most tags are self descriptive except for the <alias> tag. That is the “shortcut” users can use when querying your channel. If you look at how I installed pirum above you can see that I used the “pirum” alias in the install command. The Starzinger PEAR channel uses “stz” so when querying the channel you can just do:

christer@aurora:~$ pear list -c stz
Installed packages, channel pear.starzinger.net:
================================================
Package        Version State
PHP_BitTorrent 0.0.1   alpha
SqlDiff        0.0.3   beta

Now that the pirum.xml file is in place, run the following command to build the channel:

christer@aurora:~$ pirum build /var/www/pear
Pirum 1.0.0 by Fabien Potencier
Available commands:
pirum build target_dir
pirum add target_dir Pirum-1.0.0.tgz

Running the build command:
INFO   Building channel
INFO   Building maintainers
INFO   Building categories
INFO   Building packages
INFO   Building releases
INFO   Building index
INFO   Building feed
INFO   Updating PEAR server files
INFO   Command build run successfully

Now you will need to setup apache to have a host pointing to the newly created channel. This can be done for instance via a regular VirtualHost setup:

<VirtualHost *:80>
        ServerName pear.starzinger.net
        DocumentRoot /var/www/pear
</VirtualHost>

Now, when browsing pear.starzinger.net you will see something like this:

Now you just need to add some packages. As an example I will add a couple of packages that I have on my own PEAR channel:

christer@aurora:~$ pirum add /var/www/pear SqlDiff-0.0.3.tgz
Pirum 1.0.0 by Fabien Potencier
Available commands:
pirum build target_dir
pirum add target_dir Pirum-1.0.0.tgz

Running the add command:
INFO   Parsing package 0.0.3 for SqlDiff
INFO   Building channel
INFO   Building maintainers
INFO   Building categories
INFO   Building packages
INFO   Building package SqlDiff
INFO   Building releases
INFO   Building releases for SqlDiff
INFO   Building release 0.0.3 for SqlDiff
INFO   Building index
INFO   Building feed
INFO   Updating PEAR server files
INFO   Command add run successfully

And then another:

christer@aurora:~$ pirum add /var/www/pear PHP_BitTorrent-0.0.1.tgz
Pirum 1.0.0 by Fabien Potencier
Available commands:
pirum build target_dir
pirum add target_dir Pirum-1.0.0.tgz

Running the add command:
INFO   Parsing package 0.0.3 for SqlDiff
INFO   Parsing package 0.0.1 for PHP_BitTorrent
INFO   Building channel
INFO   Building maintainers
INFO   Building categories
INFO   Building packages
INFO   Building package PHP_BitTorrent
INFO   Building package SqlDiff
INFO   Building releases
INFO   Building releases for PHP_BitTorrent
INFO   Building release 0.0.1 for PHP_BitTorrent
INFO   Building releases for SqlDiff
INFO   Building release 0.0.3 for SqlDiff
INFO   Building index
INFO   Building feed
INFO   Updating PEAR server files
INFO   Command add run successfully

Now, take a look at the pear channel again in your browser:

The current version of Pirum (1.0.0) does not support anything other than building the channel and adding packages. If you for instance want to remove a package you added by mistake you will need to manually remove files from the get directory in your channel dir, and re-build using pirum. Lets try to remove the PHP_BitTorrent-0.0.1 package:

christer@aurora:~$ cd /var/www/pear/get
christer@aurora:/var/www/pear/get$ rm PHP_BitTorrent-0.0.1.tar PHP_BitTorrent-0.0.1.tgz
christer@aurora:/var/www/pear/get$ pirum build /var/www/pear
Pirum 1.0.0 by Fabien Potencier
Available commands:
pirum build target_dir
pirum add target_dir Pirum-1.0.0.tgz

Running the build command:
INFO   Parsing package 0.0.3 for SqlDiff
INFO   Building channel
INFO   Building maintainers
INFO   Building categories
INFO   Building packages
INFO   Building package SqlDiff
INFO   Building releases
INFO   Building releases for SqlDiff
INFO   Building release 0.0.3 for SqlDiff
INFO   Building index
INFO   Building feed
INFO   Updating PEAR server files
INFO   Command build run successfully

If you take a look at the channel in your browser now you will see that the package has been removed:

The next version of pirum will support removing packages via the pirum command (contributed by yours truly).

And thats that!