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.

2 comments »

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.

Now that my repustateApi client component both has working API calls and 100% code coverage from its unit tests, I want to make a PEAR package ready for release. At this stage, I’m only going to release it for internal testing (and so that the other components in my app can use it); there are plenty of other things to be done before it is really fit to release to the wider world.

What Is A PEAR-Compatible Package?

The PEAR installer is the de facto standard tool for installing reusable components into a PHP environment. Chances are that it was installed onto your computer when PHP was installed; if not, it’s normally available as a package for your operating system of choice. One day it will be replaced by Pyrus (the next-generation PEAR installer); Pyrus supports the same packages that the PEAR installer does.

Both installers know how to download PEAR-compatible packages from websites (known as channels), how to install them, and importantly how to upgrade them when new releases become available. This makes PEAR-compatible packages a good choice when picking the format to ship your component.

The package itself is a tarball containing:

  • package.xml, a manifest file that tells the PEAR installer all about the package and its contents, and
  • your PHP code (plus any additional files) that you want the PEAR installer to install

A lot of the work that has gone into the skeleton files for the component is make it easy to create a PEAR-compatible package.

How To Make A PEAR-Compatible Package

To make a PEAR-compatible package, go into the top-level folder of your component (where the build.xml file is), and run this command:

stuart:~/Devel/sental/repustateApi$ phing pear-package

This will build a PEAR-compatible package from your source code, and put it in the dist/ folder for you.

How To Test The Package

If you want to test that the package itself is compatible with the PEAR installer, go into the top-level folder of your component, and run this command:

stuart:~/Devel/sental/repustateApi$ phing install-vendor

This will install your PEAR-compatible package into the ‘vendor/’ folder for you, alongside your component’s dependencies.

How To Install The Package Onto Your Computer

If you want to install your PEAR-compatible package into /usr/share/php on your computer, go into the top-level folder of your component, and run this command:

stuart:~/Devel/sental/repustateApi$ sudo phing install-system

The sudo command will prompt you for your password, and will then run phing as the ‘root’ user, so that it has permissions to write into /usr/share/php.

Of course, the very best way to install your PEAR-compatible package is by publishing it to your own PEAR channel, and that’s something I’ll explain in the next blog post.

Comments Off