PEAR channel server REST interface

This manual section describes how the REST interface of a PEAR channel server works, as well as the files and their formats look like.

Directory structure

A REST channel server simply delivers files in a certain directory structure. The content of those files is static. Their location is relative to the URLs given in the channel.xml baseurl tags.

All files are static - you do not need a scripting language installed on your server.

The following table lists all known files, a tiny description as well as the version they appeared in first.

Directory- and file structure
Level 0 Level 1 Level 2 Description REST version
c/     Categories 1.0
  categories.xml   List of all categories 1.1
  $CategoryName/     1.0
    info.xml Info about the category 1.0
    packages.xml List of packages in category 1.0
    packagesinfo.xml Info about all packages 1.1
         
m/     Maintainers 1.0
  allmaintainers.xml   List of all maintainers 1.1
  $maintainernick/     1.0
    info.xml Info about the maintainer 1.0
         
p/     Packages 1.0
  packages.xml   List of all packages 1.0
  $packagename/     1.0
    info.xml General package information 1.0
    maintainers.xml List of package maintainers 1.0
    maintainers2.xml List of developers and their roles 1.2
         
r/     Releases 1.0
  $packagename/     1.0
    allreleases.xml List of all releases 1.0
    allreleases2.xml List of all releases including minimum PHP version 1.3
    latest.txt Latest version number 1.0
    stable.txt Latest stable version number 1.0
    beta.txt Latest beta version number 1.0
    alpha.txt Latest alpha version number 1.0
    devel.txt Latest development version number 1.0
    0.1.2.xml Short package info for version 0.1.2 1.0
    v2.0.1.2.xml Short version of package.xml, version 2 1.3
    package.0.1.2.xml package.xml for version 0.1.2 1.0
    deps.0.1.2.txt Serialized dependencies for version 0.1.2 1.0
         

File formats

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

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.

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

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

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

Extended 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 a <pi> tag.

Location

c/${categoryname}/packagesinfo.xml

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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>
  <optional>
   <package>
    <name>Toolbox</name>
    <channel>pear.example.org</channel>
    <min>1.3.0</min>
   </package>
  </optional>
 </dependencies>

REST version history

This page lists the known REST versions and their changes they introduced.

REST 1.0

This was the initial and first supported version of the REST interface.

REST 1.1

This version added files to allow spidering channels without requiring the server to have directory listings enabled. These files are:

REST 1.2

Now the developer's roles are listed in the package's maintainer list.

REST 1.3

This version makes it possible to resolve PHP version incompatibilities by downloading the releases list only. allreleases2.xml lists the minimum PHP version for each package release, thus the package name does not need to be changed when upgrading the package's minimum PHP version.

Use cases

This section shows common actions on a channel server and what to do then.

The idea and initial cases have been taken from Jean-Lou Dupont's "PEAR Channel on Google Code" presentation.

Adding a new category

When creating a fresh category on your channel server, the following steps are necessary:

  1. Create c/${CategoryName} directory.

  2. Create the following files:

  3. Update c/categories.xml .

Adding a new package

A new package shall be published on the server, and here are the steps you need to do:

  1. Check if the package category already exists, or a new category needs to be created.

  2. Create the package directory p/${packagename}/.

  3. Create those files:

  4. Update the category files:

Adding a release

The time has come to release a new version of an existing package. Those are the steps to do:

  1. Publish the release's package.xml as r/${packagename}/package.0.1.2.xml .

  2. Create the version specific r/${packagename}/0.1.2.xml .

  3. Update state files if appropriate: r/${packagename}/latest.txt , stable.txt , beta.txt , alpha.txt , devel.txt .

  4. Generate r/${packagename}/deps.0.1.2.xml .

  5. Update r/${packagename}/allreleases.xml and r/${packagename}/allreleases2.xml .

  6. Place package archives (tar and tgz) at the place specified in r/${packagename}/0.1.2.xml .

Channel server software

While you can use this documentation to build you own channel server, it is possibly easier for you to either get your package into PEAR itself, or setup your own channel server. The reference implementation of a PEAR channel server is the PEAR website itself, but it should not be used for your own server.

If you seek for an easy-to-setup software, try Chiara_PEAR_Server which resides on its own channel http://pear.chiaraquartet.net.

Another project is SimpleChannelServer, which is available as a plugin for Pyrus, or a standalone phar pearscs.phar. View the online documentation, or the source in SVN.

channel.xml: The channel definition file (Previous) (deprecated) XML-RPC functions (Next)
Last updated: Sat, 16 Feb 2019 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report.
View this page in:
  • English

User Notes:

There are no user contributed notes for this page.