Building and Maintaining a PEAR Server with Pirum

Pirum is a simple PEAR channel server manager that was built by Fabien Potencier. The Pirum project allows you to easily setup a PEAR channel and publish your own packages quickly. This quick blog post / article will get you going with it in no time.

Getting Started

There are a few things that you must have already to get going on this exercise (besides PHP and a Web Server *Note: you can do it without these):

• PEAR
• SSH access

Installing Pirum

To install Pirum we are simply going to be running a few commands against PEAR:

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

Pirum should now be installed, we now need to setup the pirum.xml file to describe your server.

Creating the PEAR Structure for Pirum

Pirum requires a pirum.xml file that is a very simple XML file. You place this into the directory that you would like your pear server to live. Let’s say for the sakes of this post that it is /var/www/pear. We create a file /var/www/pear/pirum.xml file that contains the following XML (to be explicit you will change the XML values to your liking)

<?xml version="1.0" encoding="UTF-8" ?>
<server>
  <name>pear.mydomain.com</name>
  <summary>PEAR Server for MyDomain</summary>
  <alias>mydomain</alias>
  <url>http://pear.mydomain.com/</url>
</server>

The fields in the pirum.xml file are explained as follows:

• name: The name is typically the domain name to the PEAR channel. You should keep this the same since this is how just about every PEAR channel references itself.
• summary: A very short summary about what the channel is, generally the name of the project / components that sit inside of it
• alias: utilized when upgrading or installing, you can reference a package by “pear install alias/package_name”
• uri: The external URI that people will run “pear channel-discover uri”

Making it Work

We can now build the main repository. We will not add any packages at this point but to get the main repository running and viewable from a web server. We will need to run the command:

pirum build /var/www/pear

At this point you should see that pirum is building out a few files such like the following:

   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

We now need to attach a web server to simply be able to access this directory. In your virtual hosts file or dedicated server add an entry to /var/www/pear that can be accessed from the uri we created in the pirum.xml file. You should not be able to see the index.html file for the packages that are installed in the repository (which is none at this point

Creating a Package

In order to create package, you should have some form of reusable code that is able to be deployed into a PEAR channel. This might be a private or public repository – either way, it is the same exact process. You must first create a package.xml file for the individual package in a top level before your package. Don’t worry, this is not needed on the same environment as we are going to create a .tgz package from it (tar gzip). Once you have completed the package.xml file and have created your .tgz file, we are moments away from being able to add a package into pirum.

Once the package is up on server with pirum – utilize the following command:

pirum add /var/www/pear package.tgz

This will add in the package and now you can install it through the pear repository you have just finished creating. This same exact process is utilized in upgrading packages.

Advanced Topics

Sometimes the main PEAR channel is not going to do it for you. For instance, I have had the need to locally create a PEAR package in our own repository to maintain versions between web servers as well as being able to quickly download and install the package locally. This helps to maintain our versions and upgrade when we need to, not when a new web server is provisioned.

Cloning a Package

Cloning a PEAR package is as simple as downloading the package and modifying the channel in the package.xml file to match the channel of your package. I have made this more simple and submitted a push request – however I currently have no response. The clone command works under linux only at the moment but can be found in my github fork of Pirum. To install it you simply need to replace the pirum file with the one provided in my repository. This adds a new command “pirum clone-package” which allows you to clone an existing package and add it into your repository.

Note: this does not mean it will handle dependencies for you, it will simply clone the package that it was asked to and not modify any dependencies. Seeing as this is how it works, you cannot download two packages that require each other and expect them to be downloaded from the cloned packages without modifying the package.xml file again.

Cloning Packages

A simple package that we have utilized in the past and continue to is Zend Framework. To add it to our repository we simply run:

pirum clone-package /var/www/pear http://pear.zfcampus.org/get/ZF-1.11.3.tgz

Under the hoods, this will download the package by utilizing file_get_contents for the download, executing tar command, running simple xml to locate the element in PHP do a string replace on the channel then re-package it and add it into your repository.

Once this is done your package is read to be installed by running:

pear install mydomain/ZF

Conclusion

Pirum makes it easy to control your own PEAR server. Now that you understand how to get it going, utilize it. It is a great tool and makes it far easier to continue adding new packages to your environment or publishing them to the world.