Which files a channel server provides Changes between PEAR REST interface versions
PEAR channel server REST interface
PEAR Manual

File formats

Here you will find detailled description of the file formats used for the REST interface.

Note: In file names that contain version numbers, we use 0.1.2 as example.

In general, the files try to be as small as possible so that only little bandwidth is required to fetch them. That's why all of the xml files (except the original package.xml have only tag names of one or two characters. Remember that operations like pear list-all download a large number of files, so every saved bit helps.

channel.xml

Information about the channel

This is the main file for a channel; nothing works without it. When discovering a channel, this file is retrieved. It defines the REST directory locations as well as mirrors.

The channel <name> is a full qualified domain name and is used as part of the URL when e.g. updating the channel.xml file.

PEAR provides aliases for channels as shortcuts in the daily work of your user's lifes. The <suggestedalias> should be a short and easy to write word. Benefit is that, instead of 

pear install pear.mynicelittlespaceon.example.org/package
they just can type 
pear install nice/package
if the alias was nice.

Location

/channel.xml

It needs to be in the root directory of the domain. While all other files can be located somewhere deep in a directory structure, channel.xml needs to be in /.

Example

<?xml version="1.0" encoding="utf-8"?>
<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.example.org</name><!-- URL, used to update channel.xml and such -->
 <suggestedalias>example</suggestedalias>
 <summary>Simple demo channel server</summary>
 <servers>
  <primary>
   <!-- you can ignore xmlrpc, it's deprecated anyway -->
   <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.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>
    <baseurl type="REST1.0">http://pear.example.org/rest/</baseurl>
    <baseurl type="REST1.1">http://pear.example.org/rest/</baseurl>
    <baseurl type="REST1.2">http://pear.example.org/rest/</baseurl>
    <baseurl type="REST1.3">http://pear.example.org/rest/</baseurl>
   </rest>
  </primary>

  <mirror host="us.pear.example.org">
   <rest>
    <baseurl type="REST1.0">http://us.pear.example.org/rest/</baseurl>
    <baseurl type="REST1.1">http://us.pear.example.org/rest/</baseurl>
    <baseurl type="REST1.2">http://us.pear.example.org/rest/</baseurl>
    <baseurl type="REST1.3">http://us.pear.example.org/rest/</baseurl>
   </rest>
  </mirror>

  <mirror host="de.pear.example.org" ssl="yes" port="3452">
   <rest>
    <baseurl type="REST1.0">https://de.pear.example.org:3452/rest/</baseurl>
    <baseurl type="REST1.1">https://de.pear.example.org:3452/rest/</baseurl>
    <baseurl type="REST1.2">https://de.pear.example.org:3452/rest/</baseurl>
    <baseurl type="REST1.3">https://de.pear.example.org:3452/rest/</baseurl>
   </rest>
  </mirror>

 </servers>
</channel>

categories.xml

List of all categories

Provides a names and links to for all categories known on the server. Links are URL-encoded.

Note: Unlike all other files, the channel name is wrapped in a <ch> instead of a plain <c> tag.

Location

c/categories.xml

Example

<?xml version="1.0" encoding="utf-8" ?>
<a xmlns="http://pear.php.net/dtd/rest.allcategories"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allcategories
                       http://pear.php.net/dtd/rest.allcategories.xsd"
>
 <ch>pear.example.org</ch>
 <c xlink:href="/rest/c/Tools/info.xml">Tools</c>
 <c xlink:href="/rest/c/Garbage%2Band%2BStuff/info.xml">Garbage and Stuff</c>
</a>

info.xml (category)

Information about a category

Here, the category is explained in detail. The file lists the name (<n>), channel server (<c>), alias (<a>) and a longer description of the category (<d>).

Location

c/${categoryname}/info.xml

Note: Category names may contain spaces and other special characters, so (x)links need to be url-encoded.

Example

<?xml version="1.0" encoding="utf-8" ?>
<c xmlns="http://pear.php.net/dtd/rest.category"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.category
                       http://pear.php.net/dtd/rest.category.xsd"
>
 <n>Tools</n>
 <c>pear.example.org</c>
 <a>Tools and Utilities</a>
 <d>This category holds all sorts of packages that might help you when
  trying to dominate the world.</d>
</c>

packages.xml (category)

List of all packages in category

The file simply contains a list of names and links to each package in the category.

Location

c/${categoryname}/packages.xml

Note: Category names may contain spaces and other special characters, so (x)links need to be url-encoded.

Example

<?xml version="1.0" encoding="utf-8" ?>
<l xmlns="http://pear.php.net/dtd/rest.categorypackages"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.categorypackages
                       http://pear.php.net/dtd/rest.categorypackages.xsd"
>
 <p xlink:href="/rest/p/earth">Earth</p>
 <p xlink:href="/rest/p/worlddominator">WorldDominator</p>
</l>

packagesinfo.xml

Extendet information about all packages

packagesinfo.xml is a collection of information about packages in the category. It contains the contents of the package's info.xml, release information from allreleases.xml and dependency information for each version.

Every package information piece is wrapped in an <pi> tag.

Location

c/${categoryname}/packagesinfo.xml

Note: Category names may contain spaces and other special characters, so (x)links need to be url-encoded.

Usage

Provides "summary" information in the list-all commmand.

Example

<?xml version="1.0" encoding="utf-8" ?>
<f xmlns="http://pear.php.net/dtd/rest.categorypackageinfo"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.categorypackageinfo
                       http://pear.php.net/dtd/rest.categorypackageinfo.xsd"
>
<pi>
<?xml version="1.0" encoding="UTF-8" ?>
<p xmlns="http://pear.php.net/dtd/rest.package"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.package
                       http://pear.php.net/dtd/rest.package.xsd"
>
 <n>WorldDominator</n>
 <c>pear.example.org</c>
 <!-- Full contents of p/${packagename}/info.xml follow -->
</p>
<a>
 <r><v>1.1.2</v><s>stable</s></r>
 <r><v>0.1.2</v><s>beta</s></r>
 <r><v>0.0.1</v><s>devel</s></r>
</a>
<deps>
 <v>0.1.2</v>
 <d><!-- serialized dependency information like deps.0.1.2.txt --></d>
</deps>
<deps>
 <v>0.0.1</v>
 <d><!-- serialized dependency information like deps.0.1.2.txt --></d>
</deps>
</pi>
</f>

allmaintainers.xml

Lists all maintainers

Simply lists names and links to all developers of any package on the server.

FIXME: full names or just nicks? FIXME: lowercased nicks?

Location

m/allmaintainers.xml

Example

<?xml version="1.0" encoding="utf-8" ?>
<m xmlns="http://pear.php.net/dtd/rest.allmaintainers"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allmaintainers
                       http://pear.php.net/dtd/rest.allmaintainers.xsd"
>
 <h xlink:href="/rest/m/pinky">pinky</h>
 <h xlink:href="/rest/m/thebrain">the brain</h>
</m>

info.xml (maintainer)

Information about a maintainer

Contains maintainer information like handle (nickname, <h>), full name (<n>) and URL (<u>) to the developer's homepage.

Location

m/${maintainernick}/info.xml

FIXME: lowercasednick?

Example

<?xml version="1.0" encoding="utf-8" ?>
<m xmlns="http://pear.php.net/dtd/rest.maintainer"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.maintainer
                       http://pear.php.net/dtd/rest.maintainer.xsd"
>
 <h>thebrain</h>
 <n>The Brain</n>
 <u>http://pinkyandthebrain.example.org</u>
</m>

packages.xml (p)

List of all packages

This file lists all packages in this channel, together with the channel server name itself.

Package names should not contain any spaces; the behavior of the installer in such cases is undefined.

Location

p/packages.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<a xmlns="http://pear.php.net/dtd/rest.allpackages"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allpackages
                       http://pear.php.net/dtd/rest.allpackages.xsd"
>
 <c>pear.example.org</c>
 <p>Earth</p>
 <p>WorldDominator</p>
</a>

info.xml (package)

Information about a package

This file contains general version-independent information about the package: License, category, summary, description and a link to the release directory.

Location

r/${packagename}/info.xml

Note: The package name is lowercased.

Usage

remote-info fetches this file and displays its information.

Example

<?xml version="1.0" encoding="utf-8" ?>
<p xmlns="http://pear.php.net/dtd/rest.package"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.package
                       http://pear.php.net/dtd/rest.package.xsd"
>
 <n>WorldDomination</n>
 <c>pear.example.org</c>
 <ca xlink:href="/rest/c/Tools">Tools</ca>
 <l>Dictatoric License</l>
 <s>Tool to dominate the world</s>
 <d>
  Helps you dominating the world by fulfilling various tasks:
  - Feed the cats
  - Lock the doors after 23:42
 </d>
 <r xlink:href="/rest/r/worlddomination"/>
</p>

maintainers.xml

Lists all developers on the package

All package developers are listed in this file, regardless if active or inactive.

Each maintainer's handle (<h>) and activity state (<a>, 0 for inactive, 1 for active) is provided.

Location

r/${packagename}/maintainers.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<m xmlns="http://pear.php.net/dtd/rest.packagemaintainers"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.packagemaintainers
                       http://pear.php.net/dtd/rest.packagemaintainers.xsd"
>
 <p>WorldDominator</p>
 <c>pear.example.org</c>
 <m>
  <h>pinky</h>
  <a>1</a>
 </m>
 <m>
  <h>thebrain</h>
  <a>1</a>
 </m>
 <m>
  <h>deadcow</h>
  <a>0</a>
 </m>
</m>

maintainers2.xml

Lists package developers

Same as maintainers.xml, except that the developer's role is written down, too.

Valid role names are lead, developer, contributor and helper.

Location

r/${packagename}/maintainers2.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<m xmlns="http://pear.php.net/dtd/rest.packagemaintainers"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.packagemaintainers
                       http://pear.php.net/dtd/rest.packagemaintainers.xsd"
>
 <p>WorldDominator</p>
 <c>pear.example.org</c>
 <m>
  <h>pinky</h>
  <a>1</a>
  <r>developer</r>
 </m>
 <m>
  <h>thebrain</h>
  <a>1</a>
  <r>lead</r>
 </m>
 <m>
  <h>deadcow</h>
  <a>0</a>
  <r>helper</r>
 </m>
</m>

allreleases.xml

List of all package versions

This file lists all known versions of a package, together with its stability.

Releases in this file are ordered, the latest version has to be first.

Location

r/${packagename}/allreleases.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<a xmlns="http://pear.php.net/dtd/rest.allreleases"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allreleases
                       http://pear.php.net/dtd/rest.allreleases.xsd"
>
 <p>WorldDominator</p>
 <c>pear.example.org</c>
 <r><v>0.8.1</v><s>beta</s></r>
 <r><v>0.0.2</v><s>alpha</s></r>
</a>

allreleases2.xml

List of all package versions with PHP version

Same as allreleases.xml, but with information about the minimum version of PHP required.

Location

r/${packagename}/allreleases2.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<a xmlns="http://pear.php.net/dtd/rest.allreleases2"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allreleases2
                       http://pear.php.net/dtd/rest.allreleases2.xsd"
>
 <p>WorldDominator</p>
 <c>pear.example.org</c>
 <r><v>0.8.1</v><s>beta</s><m>4.4.2</m></r>
 <r><v>0.0.2</v><s>alpha</s><m>5.2.3</m></r>
</a>

latest.txt

The latest package version

The only content of this file is the version number of the latest version in pure plain text. The stability state does not matter; the highest version number is written down here.

Location

r/${packagename}/latest.txt

Note: The package name is lowercased.

This file does not exist when no release has been made yet.

Example

A package has a stable version 1.0.0, two beta versions 0.9.8 and 1.0.9 and a development version 1.0.1. The highest version number is 1.0.9, and this is put in latest.txt. 

1.0.9

stable.txt

The latest stable version

The only content of this file is the version number of the latest stable version in pure plain text.

Location

r/${packagename}/stable.txt

Note: The package name is lowercased.

This file does not exist when no stable release exists.

Example

0.1.2

beta.txt

The latest beta version

The only content of this file is the version number of the latest beta version in pure plain text.

Location

r/${packagename}/beta.txt

Note: The package name is lowercased.

This file does not exist when the package has no beta version.

Example

0.1.2

alpha.txt

The latest alpha version

The only content of this file is the version number of the latest alpha version in pure plain text.

Location

r/${packagename}/alpha.txt

Note: The package name is lowercased.

This file does not exist when no alpha release exists.

Example

0.1.2

devel.txt

The latest development version

The only content of this file is the version number of the latest development version in pure plain text.

Location

r/${packagename}/devel.txt

Note: The package name is lowercased.

This file does not exist when no development release exists.

Example

0.1.2

0.1.2.xml (release)

Short xml file about the release

This file is a special size-optimized version of the full package.xml with only necessary information.

As in package.xml, the tag order is important and may not be shuffled.

Location

r/${packagename}/0.1.2.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<r xmlns="http://pear.php.net/dtd/rest.release"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.release
                       http://pear.php.net/dtd/rest.release.xsd"
>
 <p xlink:href="/rest/p/worlddominator">WorldDominator</p>
 <c>pear.example.org</c>
 <v>0.1.2</v>
 <st>beta</st>
 <l>Dictatoric License</l>
 <m>thebrain</m>
 <s>Tool to dominate the world</s>
 <d>Helps you dominating the world by fulfilling various tasks:
  - Feed the cats
  - Lock the doors after 23:42</d>
 <da>2007-12-24 23:42:00</da>
 <n>* Fix atomic X-mas bug [thebrain]</n>
 <f>19588</f>
 <g>http://pear.example/get/WorldDominator-0.1.2</g>
 <x xlink:href="package.0.1.2.xml"/>
</r>

Tags

Tag description

Tag name Description
<p> Package name inclusive absolute path to the package directory
<c> Channel server name
<v> Release version
<st> Stability state (e.g. stable, beta etc.)
<l> License name
<m> Handle/nickname of the releasing developer
<s> Summary
<d> Description, multiline
<da> Date and time of release
<n> Release notes
<f> File size of the tgz in bytes
<g> Full URL to the release archive
<x> Link to the version's package.xml file.

v2.0.1.2.xml

Short xml file about the release, version 2

Same as 0.1.2.xml , but with additional API and minimum PHP version.

Location

r/${packagename}/v2.0.1.2.xml

Note: The package name is lowercased.

Example

<?xml version="1.0" encoding="utf-8" ?>
<r xmlns="http://pear.php.net/dtd/rest.release2"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.release2
                       http://pear.php.net/dtd/rest.release2.xsd"
>
 <p xlink:href="/rest/p/worlddominator">WorldDominator</p>
 <c>pear.example.org</c>
 <v>0.1.2</v>
 <a>0.1.2</a>
 <mp>5.2.3</mp>
 <st>beta</st>
 <l>Dictatoric License</l>
 <m>thebrain</m>
 <s>Tool to dominate the world</s>
 <d>Helps you dominating the world by fulfilling various tasks:
  - Feed the cats
  - Lock the doors after 23:42</d>
 <da>2007-12-24 23:42:00</da>
 <n>* Fix atomic X-mas bug [thebrain]</n>
 <f>19588</f>
 <g>http://pear.example/get/WorldDominator-0.1.2</g>
 <x xlink:href="package.0.1.2.xml"/>
</r>

Tags

New tags compared to 0.1.2.xml.

Tag description

Tag name Description
<a> API version
<mp> Minimum PHP version

package.0.1.2.xml

Full package.xml

Full package.xml for the release. May be version 1 or version 2 of the package.xml format. The highest version should be made available if the package contains both.

Location

r/${packagename}/package.0.1.2.xml

Note: The package name is lowercased.

deps.0.1.2.txt

Serialized dependency information

The file contains an array of dependency information, serialized with PHP's serialize() function.

Location

r/${packagename}/deps.0.1.2.txt

Note: The package name is lowercased.

Example of an dependency array, unserialized and in xml

array(2) {
  ["required"]=>
  array(2) {
    ["php"]=>
    array(1) {
      ["min"]=>
      string(5) "5.2.3"
    }
    ["pearinstaller"]=>
    array(1) {
      ["min"]=>
      string(7) "1.7.1"
    }
  }
  ["optional"]=>
  array(1) {
    ["package"]=>
    array(2) {
      ["name"]=>
      string(4) "Toolbox"
      ["channel"]=>
      string(12) "pear.example.org"
      ["min"] =>
      string(7) "1.3.0"
    }
  }
}
<dependencies>
  <required>
   <php>
    <min>5.2.3</min>
   </php>
   <pearinstaller>
    <min>1.7.1</min>
   </pearinstaller>
  </required>
  
   <package>
    <name>Toolbox</name>
    <channel>pear.example.org</channel>
    <min>1.3.0</min>
   </package>
  
 </dependencies>
Which files a channel server provides Changes between PEAR REST interface versions
PEAR channel server REST interface
PEAR Manual