Making A PEAR-Compatible Package
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 a€˜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 a€˜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.