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.
Premise.
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 [5]*:
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 [fboender@php.net]*: ferry.boender@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:
include('MyApp.php');
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