PEAR 1.4.0 channels from the client side

1. PEAR only allows one package for each solution to a problem.
2. Other sites like Horde have no systemized way to distribute their packages
3. Namespacing of packages is impossible, and leads to Ever_More_Underscores

Time and again, a user comes along with a new implementation of the FOO protocol. It is similar to the PEAR implementation, and may be better. The current maintainer of PEAR's FOO package, however, feels threatened and instead of cooperating with the new user to integrate the new user's ideas, puts up roadblocks. The end result is a bunch of wasted bandwidth with flames and no progress, no benefit to end users. Competition is not possible when the maintainer is God, and all others must prove their worth. Channels will help to provide the implementer of the FOO protocol a standard way to offer his/her package as a competitor to PEAR's package, thus giving the end-users a real choice.

Horde, Seagull, and other major frameworks currently distribute their packages in the old fashioned unzip-and-configure-endlessly-and-manually manner, through no fault of their own: there is no alternative. Channels solve this problem incredibly elegantly.

If one server provides Net_POP3 and another provides Net_POP3, this can lead to a dangerous race condition where the package from server 1 is upgraded by the non-compatible package Net_POP3 from server 2. This is bad. Always. Channels fix these problems elegantly and simply

In PEAR 1.3.4 and earlier, there is essentially one official source for PEAR packages, and that is pear.php.net. Theoretically, someone could take the time to cvs checkout pearweb from cvs.php.net and then hack it to work as a server for their packages, but the effort would hardly be worth it. The end user has to do almost as much work just to use the packages.

$ pear config-set master_server blah.example.com
$ pear install Somepackage
ERROR: Somepackage requires package Foo
$ pear config-set master_server pear.php.net
$ pear install Foo
Install of Foo OK
$ pear config-set master_server blah.example.com
$ pear install Somepackage
Install of Somepackage OK
$ pear config-set master_server pear.php.net

In addition, the user has to memorize the "blah.example.com" server address, or use postits on the monitor. This sucks. Much better is:

$ pear config-set auto_discover 1
$ pear install blah.example.com/Somepackage
auto-discovering channel blah.example.com... done
Downloading pear/Foo... done
Downloading blah/Somepackage... done
Install of channel://pear.php.net/Foo OK
Install of channel://blah.example.com/Somepackage OK

Notice here that the Somepackage package had an internal dependency on a pear package, and the installer downloaded packages from both servers transparently. This is one of the side effects of channels: it is possible to depend on a package from another channel.

In addition, if 6 months down the line, you can't remember the server name for the blah.example.com channel, no problem:

$ pear list-channels
REGISTERED CHANNELS:
====================
CHANNEL SUMMARY
pear.php.net PHP Extension and Application Repository
__uri Pseudo-channel for static packages
blah.example.com Blah channel

Information can be retrieved about installed or non-installed channels with the channel-info command.

$ pear channel-info http://pear.php.net/channel.xml
CHANNEL PEAR.PHP.NET INFORMATION:
=================================
Name and Server pear.php.net
Alias pear
Summary PHP Extension and Application Repository
Validation Package Name PEAR_Validate
Validation Package default
Version
SERVER CAPABILITIES
===================
TYPE VERSION FUNCTION NAME URI
xmlrpc 1.0 logintest
xmlrpc 1.0 package.listLatestReleases
xmlrpc 1.0 package.listAll
xmlrpc 1.0 package.info
xmlrpc 1.0 package.getDownloadURL
xmlrpc 1.0 package.getDepDownloadURL
xmlrpc 1.0 package.search
xmlrpc 1.0 channel.listAll
$ pear channel-info __uri
CHANNEL __URI INFORMATION:
==========================
Name and Server __uri
Summary Pseudo-channel for static packages
Validation Package Name PEAR_Validate
Validation Package default
Version
SERVER CAPABILITIES
===================
TYPE VERSION FUNCTION NAME URI
xmlrpc 1.0 ****

How are channels defined

Channels are defined with the channel.xml file format. This format is documented at both http://pear.php.net/dtd/channels-1.0.xsd and in PEAR/ChannelFile.php, found in cvs.php.net's pear-core module. Basically, the channel.xml file defines the channel server, which is the same as its name, a brief summary of the channel's purpose, and a description of the protocols it supports. Currently, the installer only recognizes xml-rpc protocols, but forward compatibility is present for SOAP and REST. In addition, the channel.xml has the ability to define mirrors, something PEAR has been needing for a long time. Here is a sample channel.xml containing a mirror that I use in my own development (pear.chiara is an alias to localhost):

[xml]< xml version="1.0" encoding="ISO-8859-1" >
<channel version="1.0" xmlns="http://pear.php.net/channel-1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://pear.php.net/channel-1.0
http://pear.php.net/dtd/channel-1.0.xsd">
<name>pear.php.net</name>
<suggestedalias>pear</suggestedalias>
<summary>PHP Extension and Application Repository</summary>
<servers>
<primary>
<xmlrpc>
<function version="1.0">logintest</function>
<function version="1.0">package.listLatestReleases</function>
<function version="1.0">package.listAll</function>
<function version="1.0">package.info</function>
<function version="1.0">package.getDownloadURL</function>
<function version="1.0">package.getDepDownloadURL</function>
<function version="1.0">package.search</function>
<function version="1.0">channel.listAll</function>
</xmlrpc>
</primary>
<mirror host="pear.chiara">
<xmlrpc>
<function version="1.0">logintest</function>
<function version="1.0">package.listLatestReleases</function>
<function version="1.0">package.listAll</function>
<function version="1.0">package.info</function>
<function version="1.0">package.getDownloadURL</function>
<function version="1.0">package.getDepDownloadURL</function>
<function version="1.0">package.search</function>
<function version="1.0">channel.listAll</function>
</xmlrpc>
</mirror>
</servers>
</channel>[/xml]

The suggested alias is a shortcut to avoid having to type, for instance:

$ pear install pear.php.net/Foo blah.example.com/Blah

Instead, you can type:

$ pear install pear/Foo blah/Blah

In addition, the alias is user-customizable (hence "suggestedalias"), with the channel-alias command

$ pear channel-alias pear.php.net gronk
$ pear install gronk/HTML_QuickForm

The above is perfectly valid. Note that if a new channel is discovered that attempts to alias itself to an existing alias, the channel's name will be used as the alias instead.

A further shortcut available to users is the default_channel and preferred_mirror configuration variables.

default_channel will prepend the channel name to any packages specified. Therefore:

$ pear config-set default_channel pear.php.net
$ pear install HTML_QuickForm HTML_QuickForm_Controller

will work great. PEAR ships with the default_channel = pear.php.net for obvious backward compatibility reasons.

"Discovering" a channel is a fancy word for retrieving http://channel.server/channel.xml and seeing if it is a valid channel.xml, and if the server specified in channel.xml is the same as channel.server.

Discovering new channels can be done in a couple of ways. One that I already spoke of, is the configuration variable auto_discover, which is 0 by default for security reasons. Users who understand what channels are doing, and how they work should set this variable on, as the only risk is if a user doesn't understand why the installer is downloading from another server and freaks out .

When auto_discover is set to 1 with

$ pear config-set auto_discover 1

then any time a channel server is referenced in a dependency or on the command-line, PEAR will attempt to discover the channel and will automatically add it to the registry of known channels, and then install the package normally. If auto_discover is off, then PEAR will still attempt to discover the channel, but will not add it to the registry and will error out with a message describing how to manually discover the channel.

The second way to discover a channel is with the manual channel-discover command:

$ pear channel-discover blah.example.com

The final and most official way to discover a channel is with the update-channels command. This command retrieves a list of officially sanctioned channel servers from the default channel (which is usually pear.php.net) and then attempts to discover new channels and update the channel definitions of existing channels.

$ pear update-channels

You may have noticed the odd __uri channel in there. This is a fake channel that allows the implementation of static uri dependencies. In other words, it is possible in PEAR 1.4.0 to list a dependency on http://blah.example.com/SomeRandomPackage.tgz. This is useful for folks who have 1 or 2 packages that contain utility classes that are used for custom non-public freelance jobs, which will allow total control over the packages without having to set up a full-blown channel server.

[xml]<dependencies>
<required>
...
<package>
<name>SomeRandomPackage</name>
<uri>http://blah.example.com/SomeRandomPackage.tgz</uri>
</package>
</required>
</dependencies>[/xml]

Incidentally, channels are the feature that motivated me to devote my energies full-time to working on the installer in the first place. Channels will allow applications like phpDocumentor to distribute official plugins and non-official templates through separate channels. The user community that channels will create could help to spawn a new age in php applications.

Security issues

At this time, the only possible security issue is if a user takes over a channel server and replaces all of the packages. A channel.xml cannot change the channel server, because of the link between channel server and name. Although mirrors can be used to provide alternate locations for download, the user cannot be forced to use a mirror, this must be changed manually.

Checks are performed when adding a new channel, updating a channel, and on package download that there are no unexpected changes in channel.

If a package is downloaded from channel blah.example.com and the package.xml claims it is from pear.php.net, installation will fail with a large security warning.

If a channel.xml from http://blah.example.com/channel.xml claims it is from pear.php.net, updating will fail.

All of these options can be overridden with a --force option, to maintain flexibility, but the user must bring his or her own doom consciously and manually.