How to describe a channel
Discovery of a channel's capabilities is extremely flexible. The XSD schema
defining channel.xml can be found at
http://pear.php.net/dtd/channel-1.0.xsd.
Channel.xml defines:
the channel name
an optional suggested user alias for the channel
a brief summary of the channel's purpose
an optional package to perform custom validation of packages on
both download and packaging
a list of protocols supported by a channel (XML-RPC, SOAP, and REST are supported)
a list of mirrors and the protocols they support.
Here is a sample channel.xml with all elements:
<channel version="1.0"
xsi:schemaLocation="http://pear.php.net/channel-1.0
http://pear.php.net/dtd/channel-1.0.xsd">
<name>pear.example.com</name>
<suggestedalias>foo</suggestedalias>
<summary>Example channel.xml</summary>
<validatepackage version="1.3.4">Foo_Validate</validatepackage>
<servers>
<primary port="8080" ssl="yes">
<xmlrpc> <!-- default path is xmlrpc.php -->
<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.1">package.getDownloadURL</function>
<function version="1.0">package.getDepDownloadURL</function>
<function version="1.1">package.getDepDownloadURL</function>
<function version="1.0">package.search</function>
<function version="1.0">channel.listAll</function>
</xmlrpc>
<rest> <!-- no default path, all must be defined in baseurl -->
<baseurl type="package">http://pear.example.com/rest/1.0/package</baseurl>
<baseurl type="category">http://pear.example.com/rest/1.0/category</baseurl>
</rest>
<soap path="soapy.php"> <!-- default path is soap.php -->
<function version="1.0">package.listAll</function>
</soap>
</primary>
<mirror server="foo2.example.com/pearmirror">
<xmlrpc path="mirrorxmlrpc.php"> <!-- default path is xmlrpc.php -->
<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.1">package.getDownloadURL</function>
<function version="1.0">package.getDepDownloadURL</function>
<function version="1.1">package.getDepDownloadURL</function>
<function version="1.0">package.search</function>
</xmlrpc>
<rest> <!-- no default path, all must be defined in baseurl -->
<baseurl type="package">http://foo2.example.com/rest/1.0/package</baseurl>
</rest>
</mirror>
</servers>
</channel> |
<name>
A channel's name should be the name of the server that users would browse to in order
to learn more about the packages being offered. For instance, PEAR packages are
located in the pear.php.net channel. PECL packages are located in the pecl.php.net
channel. Note that for backwards compatibility, all existing packages based on
package.xml version 1.0 are in the pear.php.net channel.
The benefit that comes from using the server name as the channel name is that
auto-discovery becomes a real possibility, as well as ease of locating packages
increases dramatically.
A channel need not be located in the document root, a channel can contain a path. This
is a perfectly valid channel name:
foo.example.com/path/to/pear.
Note that users would have to type:
$ pear install foo.example.com/path/to/pear/Packagename |
Unless you provide a <suggestedalias>.
The channel's definition file "channel.xml" must be placed in the root channel
directory. If a channel is "pear.example.com", the channel.xml must be located
in "http://pear.example.com/channel.xml". If the channel is
"pear.example.com/path/to/pear", then the channel.xml must be located in
"http://pear.example.com/path/to/pear/channel.xml"
<suggestedalias>
<suggestedalias> defines a shorter, more friendly name to use when installing
packages from a channel. For instance, the pear.php.net channel's suggested alias is
"pear". The best aliases for a channel will be no more than 6 characters long -
remember, a user must type them often when installing or upgrading, and this can be
tedious for longer aliases.
Rather than call this tag <alias>, as it was originally named, the tag
is named <suggestedalias> in order to provide the user some latitude. If
the user does not like the alias suggested by the channel owners, he or she can
easily re-alias a channel through the channel-alias command.
<summary>
This tag provides a short description of what packages the user should expect to
find on this channel. The summary is what users will see when the use the list-channels
command.
<validatepackage>
Most channels will be satisfied with the restrictions placed upon package naming,
versioning, and so on that PEAR provides by default. However, for some channels,
the validation will be too strict, and others, too relaxed. The <validatepackage>
tag provides the next level of customization.
If omitted, the installer assumed that the PEAR_Validate class
should be used. Note that a looser version validation is provided by the
PEAR_Validate_PECL class, for channels like pecl.php.net that do
not wish to deal with PEAR's warnings on version transgressions.
<validatepackage> requires a version attribute and text content. The text content
must be the name of a package that can be installed via:
$ pear install channelname.example.com/Packagename-version |
as in:
$ pear install pear.example.com/Foo_Validate-1.3.4 |
for the sample channel.xml at the beginning of this section. In addition, the package
must provide a single class named after the package in a file using the PEAR naming
conventions (all underscores "_" converted into path separators "/"
so that Foo_Validate is located in Foo/Validate.php), and this class should extend
PEAR_Validate. Methods beginning with "validate" like
validateVersion() are intended to be overridden by validation classes
for use in extending existing validation functionality.
<servers>: <primary> and <mirror>
Mirroring is explicitly supported in channel.xml and in the PEAR installer. Users can
choose their favorite mirror via the default_channel configuration
option, and channel.xml can list all the possible mirrors using the (surprise)
<mirror> tag.
The <primary> tag is used to define the location of protocols, and to list
the protocols that are supported by the main channel server. Optional attributes
can be used to modify how the PEAR installer will attempt to connect to the server.
The "port" attribute can be used to define how the installer will connect
to XML-RPC and SOAP services. REST services are always controlled by the individual
<baseurl> tags.
<xmlrpc>, <soap>, <rest>
channel.xml knows about the XML-RPC, SOAP, and REST protocols for web services.
However, the PEAR installer only supports XML-RPC currently, and may support
REST shortly. No support for SOAP is planned for the near future. However, should
it ever be implemented, channel.xml is ready.
The <xmlrpc> and <soap> tags have identical formats. Both tags can contain
an optional attribute "path" that tells the PEAR installer which URL to
query. By default, the path is protocol.php, as in xmlrpc.php or soap.php. In other
words, to access XML-RPC functions for the pear.example.com channel defined in the sample
channel.xml, the installer would query
https://pear.example.com:8080/xmlrpc.php for XML-RPC functions, but
would query https://pear.example.com:8080/soapy.php for SOAP
functions.
The <rest> tag reflects the design concept behind REST: each resource is
defined by a base URL in tag <baseurl> that is then used by the installer
along with hyperlinks to glean the same information that XML-RPC or SOAP would
provide. Required attribute "type" tells the installer what kind of
information is provided by the base URL, and how to parse that information.
<function>
The <function> tag is quite simple. A required version attribute informs the
installer what the API is, and the text content informs the installer what the name
of the function is. Note that multiple functions with different versions can co-exist
peacefully, as in:
<function version="1.0">package.getDownloadURL</function>
<function version="1.1">package.getDownloadURL</function> |
If a newer API is backwards-compatible, always define every possible API version
in order to prevent older installer versions from giving up.
Why not use a standard such as wsdl?
Some of you may be asking "why create another standard for web
services discovery?" The answer is simple: channel.xml does not
supplant the role that WSDL has for java, or XML-RPC introspection occupies.
channnel.xml is a layer on top of these technologies. The point is to quickly
list the remote protocols that are supported, not to describe what they do.
The PEAR installer is specialized enough that a generic listing of parameters and
return values is entirely unnecessary: the installer knows exactly what xml-rpc
function package.info version 1.0 requires and what it returns. Any other information
simply adds wasted bandwidth and disk space.
