Easy PEAR Package creation
Sunday, April 12th, 2009
Here's a fairly simple way of creating PEAR package so you can distribute your application or library as a PEAR package.
Let's assume you've written an application or library called 'MyApp'. The following is a possible directory structure layout:
myapp/ |- MyApp.php \- MyAap/ \- MyApp/MyLib.php
Install the PackageFileManager.
Since writing a package file by hand is way too much work, we first install the PEAR_PackageFileManager utility. This PEAR package includes a commandline utility which will guide you through the steps needed to create a proper package.xml file for your application or library.
# pear install pear install PEAR_PackageFileManager_Cli-0.3.0 Ignoring installed package pear/pear No releases available for package "pear.php.net/install" Cannot initialize 'channel://pear.php.net/install', invalid or missing package file WARNING: channel "pear.php.net" has updated its protocols, use "channel-update pear.php.net" to update Did not download optional dependencies: pear/PHP_CompatInfo, use --alldeps to download automatically pear/PEAR_PackageFileManager can optionally use package "pear/PHP_CompatInfo" (version >= 1.4.0) downloading PEAR_PackageFileManager_Cli-0.3.0.tgz ... Starting to download PEAR_PackageFileManager_Cli-0.3.0.tgz (8,051 bytes) .....done: 8,051 bytes downloading PEAR_PackageFileManager-1.6.3.tgz ... Starting to download PEAR_PackageFileManager-1.6.3.tgz (82,393 bytes) ...done: 82,393 bytes Package "channel://pear.php.net/install" is not valid install ok: channel://pear.php.net/PEAR_PackageFileManager-1.6.3 install ok: channel://pear.php.net/PEAR_PackageFileManager_Cli-0.3.0
If your PEAR is outdated, you will see something like:
pear/PEAR_PackageFileManager requires PEAR Installer (version >= 1.8.0alpha1), installed version is 1.7.1
In that case, you can upgrade your PEAR like so:
# pear channel-update pear.php.net Updating channel "pear.php.net" Update of Channel "pear.php.net" succeeded # pear upgrade PEAR ... upgrade ok: channel://pear.php.net/PEAR-1.8.1
You may also run into problems with alpha/beta state packages required for installation of the PackageFileManager CLI package. For instance, I got the following error: Failed to download pear/XML_Serializer within preferred state "stable", latest release is version 0.19.2, stability "beta", use "channel://pear.php.net/XML_Serializer-0.19.2" to install
In that case, you must manually install the beta packages:
# pear install channel://pear.php.net/XML_Serializer-0.19.2 downloading XML_Serializer-0.19.2.tgz ... Starting to download XML_Serializer-0.19.2.tgz (39,703 bytes) ..........done: 39,703 bytes downloading XML_Parser-1.3.2.tgz ... Starting to download XML_Parser-1.3.2.tgz (16,260 bytes) ...done: 16,260 bytes install ok: channel://pear.php.net/XML_Parser-1.3.2 install ok: channel://pear.php.net/XML_Serializer-0.19.2
Generate a package.xml file.
You can now use the PackageFileManager command-line utility to bootstrap a package.xml file for your PEAR package.
Change to the directory that is the root of your package:
$ cd myapp/ myapp$ ls MyApp MyApp.php myapp$ pfm PEAR Package File Manager Command Line Tool Please enter the location of your package [.]*: . Creating a new package file ... Enter the base install directory*: . Enter the name of the package [myapp]*: MyApp Channel or URI based package? [c] (c,u)*: u Enter the package URI*: http://www.example.com/download/PEAR/ Enter a 1 line summary*: My first PEAR example application. Enter a description* (2 blank lines to finish): MyApp is my first PEAR example application. It rocks. Enter the release version*: 0.1.0 Enter the API version [0.1.0]*: Choose a release stability [alpha] (alpha,beta,stable)*: Choose an API stability [alpha] (alpha,beta,stable)*: Enter any release notes* (2 blank lines to finish): Initial release Enter the minimum PHP version *: Enter the minimum PEAR Installer version [1.4.0]*: Please choose a license from one of the following options 1) Apache 2) BSD Style 3) LGPL 4) MIT 5) PHP Please choose an option: 4 How many maintainers?*: 1 What type of maintainer is #1? [lead] (lead,developer,contributor,helper)*: Enter maintainer #1's name*: Ferry Boender Enter maintainer #1's username*: fboender Enter maintainer #1's email [firstname.lastname@example.org]*: email@example.com PEAR Package File Manager Command Line Tool 1. Package name [MyApp] 2. Channel/URI [URI: http://www.example.com/download/PEAR/] 3. Summary [My first PEAR example application.] 4. Description [MyApp is my first PEAR example applic...] 5. Maintainers 6. Version [Release: 0.1.0 API: 0.1.0] 7. Stability [Release: alpha API: alpha] 8. License [MIT] 9. Notes [Initial release] 10. Dependencies 11. Tasks 12. Regenerate contents 13. Echo package file to stdout 14. Save & Quit 15. Quit without saving (ctrl-c) Please choose an option from the menu: 14 Analyzing MyApp/MyLib.php Analyzing MyApp.php
This generates a package.xml for you, containing details for the PEAR package creation.
Create a PEAR package.
PEAR can use this package.xml file to create a PEAR package for you:
myapp$ pear package package.xml Analyzing myapp/MyApp.php Analyzing myapp/MyApp/MyLib.php Package MyApp-0.1.0.tgz done
Testing and (un)installing your package
Test the installation of the package:
myapp$ pear install ./MyApp-0.1.0.tgz pear install ./MyApp-0.1.0.tgz install ok: channel://__uri/MyApp-0.1.0
It appears to work. Make sure to check the PEAR directory to see if it placed the files in the right spot:
myapp$ ls /usr/share/php/ Archive MyApp OS PEAR.php Structures adodb doc pearcmd.php php-shell-cmd.php Console MyApp.php PEAR PHP System.php data docs peclcmd.php
The MyApp.php file, and the MyApp directory have been added to the PEAR library directory. If their PHP include_path is set correctly, users of your package should now be able to include it using:
You can uninstall the package using the pear uninstall command:
$ pear uninstall channel://__uri/MyApp-0.1.0 uninstall ok: channel://__uri/MyApp-0.1.0
Distribute your package
You can now put your PEAR package online, and point users to it by mentioning they can install it using PEAR with the command:
$ pear install http://www.example.com/download/PEAR/MyApp-0.1.0.tgz