Install the test package
Now that you have a channel up and running, you'll want to install a package from the channel. In order for the package manager to know where the packages are located, you need to add the implementation code behind the
package.getDownloadURL method to return the URL and information about the package. If the package has dependencies, you must also add implementation to the
package.getDepsDownloadURL method. Look at my sample implementation to understand the structure of the data being returned.
After you add the implementation code to the xmlrpc.php file, copy it where the previous file was located. You don't need to copy the channel.xml file again.
The sample package for this tutorial is simple. It doesn't need to be complicated because the package is only used to verify that all the plumbing works as the channel is being published. The example package contains two files, Account.php and AccountFactory.php, located in the Factory subdirectory. The contents of the files are unimportant, but the package.xml file is important because it contains the version of the package.
Listing 10. package.xml file contains package version
<?xml version="1.0" encoding="UTF-8"?> <package version="2.0" xmlns="http://pear.php.net/dtd/package-2.0" xmlns:tasks="http://pear.php.net/dtd/tasks-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://pear.php.net/dtd/tasks-1.0 http://pear.php.net/dtd/tasks-1.0.xsd http://pear.php.net/dtd/package-2.0 http://pear.php.net/dtd/package-2.0.xsd"> <name>Account</name> <channel>pear.example.net</channel> <summary>Domain objects for ABC Company</summary> <description> This package contains domain objects that are to be used by services and applications in ABC Company. </description> <lead> <name>Nathan A. Good</name> <user>ngood</user> <email>email@example.com</email> <active>yes</active> </lead> <date>2006-11-17</date> <time>12:00:00</time> <version> <release>1.0.0</release> <api>1.0.0</api> </version> <stability> <release>stable</release> <api>stable</api> </stability> <license uri="http://pear.abccompany.com/license"> ABC Company License </license> <notes>Release notes go here.</notes> <contents> <dir name="/"> <dir name="Factory"> <file name="AccountFactory.php" role="php"></file> </dir> <file name="Account.php" role="php"></file> </dir> </contents> <dependencies> <required> <php> <min>5.0</min> </php> <pearinstaller> <min>1.4.0</min> </pearinstaller> </required> </dependencies> <phprelease></phprelease> <changelog> <release> <version> <release>1.0.0</release> <api>1.0.0</api> </version> <stability> <release>stable</release> <api>stable</api> </stability> <date>2006-11-17</date> <license uri="http://pear.example.net/license"> ABC Company License </license> <notes>Brand new version.</notes> </release> </changelog> </package>
This file reflects V2.0 of the package.xml file, which has replaced V1.0. It's important to use V2.0 because it includes the
channel element. The text inside the
channel element must match the name of the channel or you'll get errors when you attempt to install the package using PEAR.
Getting in-depth about building PEAR packages isn't the focus of this tutorial. As a quick overview, you can follow the steps here, but see Resources for more information. To get started with the sample package, put the package.xml and Account.php files in a directory and AccountFactory.php into a subdirectory called Factory to mirror what was defined in package.xml. Fortunately, a couple commands come with the PEAR package manager that make it easy to validate the package file and build the package, so there is no guesswork in terms of package structure.
To verify the package file, open a command window, change into the directory where you put the package files, and verify the package.
Listing 11. Verify package
$ pear package-validate package.xml Analyzing Factory/AccountFactory.php Analyzing Account.php Validation: 0 error(s), 0 warning(s)
After the package file has been verified, use the PEAR package manager to build the package. Without leaving the directory, use the following command:
Listing 12. Build package
$ pear package Analyzing Factory/AccountFactory.php Analyzing Account.php Adding file Factory/AccountFactory.php Adding file Account.php Package Account-1.0.0.tgz done
Now, move the Account-1.0.0.tgz file to the location you'll specify in the
url key of the structure returned by the
package.getDownloadURL implementation in the xmlrpc.php file. For instance, you might decide on a convention of putting packages into a directory on your Web server that's accessible by http://pear.example.net/pkg. Make sure the
package.getDownloadURL function returns a URL of http://pear.example.net/pkg/Account-1.0.0 for a package called Account-1.0.0. Notice that the file extension .tgz isn't included in the URL. The package manager appends it for you.
Once the package is in place and the xmlrpc.php file has been updated to included the new implementation, install the package using the package manager as shown below.
Listing 13. Install package
pear install abccompany/Account downloading Account-1.0.0.tgz ... Starting to download Account-1.0.0.tgz (1,245 bytes) ....done: 1,245 bytes + create dir /usr/local/php5/lib/php/Factory md5sum ok: /usr/local/php5/lib/php/Factory/AccountFactory.php md5sum ok: /usr/local/php5/lib/php/Account.php about to commit 7 file operations successfully committed 7 file operations install ok: channel://pear.example.net/Account-1.0.0