1. About
Here’s a fairly simple way of creating PEAR package so you can distribute your application or library as a PEAR package.
2. 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
3. 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_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
4. 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+install for you, containing details for the PEAR package creation.
5. 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
6. 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
7. 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
8. Copyright / License
Copyright (c) 2008, Ferry Boender
This document may be freely distributed, in part or as a whole, on any medium, without the prior authorization of the author, provided that this Copyright notice remains intact, and there will be no obstruction as to the further distribution of this document. You may not ask a fee for the contents of this document, though a fee to compensate for the distribution of this document is permitted.
Modifications to this document are permitted, provided that the modified document is distributed under the same license as the original document and no copyright notices are removed from this document. All contents written by an author stays copyrighted by that author.
Failure to comply to one or all of the terms of this license automatically revokes your rights granted by this license
All brand and product names mentioned in this document are trademarks or registered trademarks of their respective holders.