In my Beyond Frameworks talk, I explained how a component-based architecture can help answer some of the important (i.e. expensive!) questions you might face when creating long-lived apps that rely on a PHP framework. In this series of blog posts, I’m going to look at how to go about creating and working with components.
In the last article, I explained how to create a PEAR-compatible package from your component, and how to install the package both for local testing and for system-wide use on your own computer. One of the strengths of picking the PEAR installer for our components is that it’s a very easy way for others to download and consume our components.
We just need somewhere to publish them. We either need to find an existing PEAR channel to publish to, or we need to publish our own.
To Self-Publish Or Not
It’s worth taking a moment to consider whether you should publish your own PEAR channel or not.
At the time of writing, the components culture in the PHP community is at an embryonic stage of development. There are curated pockets here and there, but we have nothing yet that compares with both the traction and ubiquity of RubyForge or Perl’s CPAN.
There is the venerable PEAR project, which has given us the installer I’m using for the components skeleton featured in these blog posts, but its no-compete policy for packages means that you have to apply for permission to have your package carried by their channel.
There are other efforts around such as Pearhub and Pearfarm, but neither of them have really nailed the complete experience for both package publisher and package user at this time. If anyone wants to take up the challenge of providing our community with a modern, credible equivalent to RubyForge, I’d love to hear from you :)
This is why many of the tools you’ll hear talked about at PHP conferences (such as the QA tools that Sebastian talks regularly about) end up being self-published. Today, it’s simply easier to do.
How To Setup Your Own PEAR Channel
Self-publishing your PEAR channel is incredibly easy. All you need is some web-hosting space, and Fabien’s Pirum. Pirum is a very simple, very straight-forward tool that creates and updates all the files needed for your own PEAR channel. Best of all, these files are all static files, keeping things lean and mean.
To install Pirum, simply run these commands from the command-line:
pear channel-discover pear.pirum-project.org pear install pirum/Pirum
This installs a command-line tool that you’ll use to create your PEAR channel.
Next, you need to configure Apache to serve your PEAR channel to the world. By convention, PEAR channels normally are http://pear.<project>.whatever or http://pear.<vendor>.whatever. The PEAR installer works best if your PEAR channel files are in the DocumentRoot of your website.
Let’s say that the DocumentRoot of your PEAR channel is going to be /var/www/pear.example.com. Once you’ve configured Apache to serve pear.example.from from /var/www/pear.example.com, you need to create a pirum.xml file to describe your PEAR channel. This is a very simple file that tells Pirum the essential information it needs to create your PEAR channel’s files.
mkdir /var/www/pear.example.com cd /var/www/pear.example.com vi pirum.xml
For pear.example.com, the pirum.xml file would look like this:
<?xml version="1.0" encoding="UTF-8" ?> <server> <name>pear.example.com</name> <summary>Example PEAR channel</summary> <alias>Example</alias> <url>http://pear.example.com</url> </server>
Now we need to tell pirum to build our PEAR channel files:
cd /var/www/pear.example.com pirum build .
Congratulations – you now have your own PEAR channel. Remember to change ‘pear.example.com’ to be the actual name of your own PEAR channel, and you too can have your own PEAR channel up and running in about 10 minutes first time around.
Once you’ve built a PEAR-compatible package from your component, it’s one command in Pirum to publish that package on your PEAR channel.
Adding A Package To Your Own PEAR Channel
Let’s say I’m going to publish my RepustateApi package on the pear.example.com channel I created above. The full sequence of commands to create and publish the channel is:
stuart:~/Devel/repustateApi$ phing pear-package stuart:~/Devel/repustateApi$ pirum add /var/www/pear.example.com dist/repustateAPI-0.1.0.tgz
It’s that straight forward :)
Now, in reality, you’re unlikely to be developing your PHP components on your public webserver. You’re more likely to be developing your PHP components on your local desktop or laptop (or on a shared development server), and then uploading the final results to your public webserver. This is how we work at Gradwell right now, and in the next blog post I’ll go through our actual workflow for publishing a new or updated component, showing you how we’re setup to both support multiple contributors and disconnected development.