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.
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.
/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 /.
<?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> |
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.
<?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:class="blue" HREF="res_/rest/c/Tools/info.xml">Tools</c>
<c xlink:class="blue" HREF="res_/rest/c/Garbage%2Band%2BStuff/info.xml">Garbage and Stuff</c>
</a> |
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>).
c/${categoryname}/info.xml
Note:
Category names may contain spaces and other special characters,
so (x)links need to be url-encoded.
<?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> |
List of all packages in category |
The file simply contains a list of names and links to each
package in the category.
c/${categoryname}/packages.xml
Note:
Category names may contain spaces and other special characters,
so (x)links need to be url-encoded.
<?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:class="blue" HREF="res_/rest/p/earth">Earth</p>
<p xlink:class="blue" HREF="res_/rest/p/worlddominator">WorldDominator</p>
</l> |
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.
c/${categoryname}/packagesinfo.xml
Note:
Category names may contain spaces and other special characters,
so (x)links need to be url-encoded.
Provides "summary" information in the list-all commmand.
<?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> |
Simply lists names and links to all developers of any package
on the server.
FIXME: full names or just nicks?
FIXME: lowercased nicks?
<?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:class="blue" HREF="res_/rest/m/pinky">pinky</h>
<h xlink:class="blue" HREF="res_/rest/m/thebrain">the brain</h>
</m> |
Information about a maintainer |
Contains maintainer information like handle
(nickname, <h>),
full name (<n>)
and URL (<u>) to the developer's homepage.
m/${maintainernick}/info.xml
FIXME: lowercasednick?
<?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> |
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.
p/packages.xml
Note:
The package name is lowercased.
<?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> |
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.
r/${packagename}/info.xml
Note:
The package name is lowercased.
remote-info fetches this file and displays
its information.
<?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:class="blue" HREF="res_/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:class="blue" HREF="res_/rest/r/worlddomination"/>
</p> |
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.
r/${packagename}/maintainers.xml
Note:
The package name is lowercased.
<?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> |
Same as
maintainers.xml,
except that the developer's role is written down, too.
Valid
role names
are lead, developer,
contributor and helper.
r/${packagename}/maintainers2.xml
Note:
The package name is lowercased.
<?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> |
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.
r/${packagename}/allreleases.xml
Note:
The package name is lowercased.
<?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> |
List of all package versions with PHP version |
Same as allreleases.xml, but with information
about the minimum version of PHP required.
r/${packagename}/allreleases2.xml
Note:
The package name is lowercased.
<?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> |
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.
r/${packagename}/latest.txt
Note:
The package name is lowercased.
This file does not exist when no release has been made yet.
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.
The latest stable version |
The only content of this file is the version number of the latest
stable version in pure plain text.
r/${packagename}/stable.txt
Note:
The package name is lowercased.
This file does not exist when no stable release exists.
The only content of this file is the version number of the latest
beta version in pure plain text.
r/${packagename}/beta.txt
Note:
The package name is lowercased.
This file does not exist when the package has no beta version.
The only content of this file is the version number of the latest
alpha version in pure plain text.
r/${packagename}/alpha.txt
Note:
The package name is lowercased.
This file does not exist when no alpha release exists.
The latest development version |
The only content of this file is the version number of the latest
development version in pure plain text.
r/${packagename}/devel.txt
Note:
The package name is lowercased.
This file does not exist when no development release exists.
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.
r/${packagename}/0.1.2.xml
Note:
The package name is lowercased.
<?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:class="blue" HREF="res_/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:class="blue" HREF="res_package.0.1.2.xml"/>
</r> |
Table 33-2. 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.
|
Short xml file about the release, version 2 |
Same as
0.1.2.xml
,
but with additional API and minimum PHP version.
r/${packagename}/v2.0.1.2.xml
Note:
The package name is lowercased.
<?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:class="blue" HREF="res_/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:class="blue" HREF="res_package.0.1.2.xml"/>
</r> |
New tags compared to 0.1.2.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.
r/${packagename}/package.0.1.2.xml
Note:
The package name is lowercased.
Serialized dependency information |
The file contains an array of dependency information, serialized with
PHP's
serialize()
function.
r/${packagename}/deps.0.1.2.txt
Note:
The package name is lowercased.
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> |
