channel.xml: The channel definition file
Prev		Next

channel.xml: The channel definition file

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>

foo</suggestedalias>

Example channel.xml</summary>

<validatepackage

version="1.3.4">Foo_Validate</validatepackage>

<servers> <primary

port="8080" ssl="yes">

<!-- 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="REST1.0">http://pear.example.com/rest/</baseurl>
    <baseurl type="REST1.1">http://pear.example.com/rest/</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="REST1.0">http://foo2.example.com/rest/</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 REST currently, and may support other methods in the future. 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 version of the PEAR installer REST interface is provided at the base URL.

<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.

Prev	channel.xml, REST, XML-RPC	Next
channel.xml, REST, XML-RPC	PEAR Manual	PEAR channel server REST interface