The index.xml format #

This page is for developers who publish packages, run a mirror or debug the Site package step. It describes the index.xml file of a release folder: its elements and attributes, which of them the code reads, and what happens when one is wrong. The reference implementation is eZStepSiteTypes::retrieveRemotePackagesList() in kernel/setup/steps/ezstep_site_types.php.

Contents #

1. An example
2. The root element
3. The package element
4. How the setup wizard reads it
5. How ezupdate reads it
6. A minimal index of your own
7. Checking an index
8. Related pages

An example #

Two entries of the 6.0.15 index, the first a required package, the second a site package (one line each in the file, wrapped here):

<?xml version="1.0"?>
<packages vendor="7x">

<!-- DEPENDENCY PACKAGE LIST -->
  <package name="sevenx_classes" type="contentclass"
           url="https://exponential.packages.exponential.earth/exponential/6.0/6.0.15/sevenx_classes.ezpkg"/>

  <package name="sevenx_multisite" version="6.0-15-stable" type="site"
           summary="7x MultiSite Default Installation"
           description="7x MultiSite Default Installation is a web based CMS solution based on Exponential. ..."
           url="https://exponential.packages.exponential.earth/exponential/6.0/6.0.15/sevenx_multisite.ezpkg"
           thumbnail_url="https://exponential.packages.exponential.earth/exponential/6.0/6.0.15/thumbnails/sevenx_multisite.png"/>
</packages>

The whole file: https://exponential.packages.exponential.earth/exponential/6.0/6.0.15/index.xml (44 entries).

The root element #

Comments and white space between the entries are allowed; everything that is not a <package> element is skipped.

The package element #

How the setup wizard reads it #

1. The index address is RemotePackagesIndexURL plus /index.xml (a trailing slash is not doubled).
2. The file is downloaded like a package, with retries (When the package server cannot be reached), into <cache>/packages/index.xml, and deleted after it is parsed.
3. If the download fails, the wizard copies index.xml from the system repository, var/storage/packages/7x/index.xml, when there is one (Offline installs and mirrors).
4. The file is parsed with DOMDocument. A file that does not parse logs "Unable to open index file." and the list stays empty.
5. Each <package> element becomes an array of all its attributes, so attributes the code does not know are kept but ignored.
6. For the list on the screen only site packages are used; for the dependencies of a chosen package the whole list is used, looked up by name. A required package that is neither imported nor in the index stops the step with "Download of package 'name' failed. You may upload the package manually."

The radio button of a remote entry carries name|url. The step treats the choice as a download only when the name consists of letters, digits and _ (/^(\w+)\|(.+)$/ in processPostData()); package names follow that rule anyway (package.xml required fields).

How ezupdate reads it #

The ezupdate extension's Package servers page reads the same format from every server it knows (extension/ezupdate/classes/ezupdatepackageservers.php):

• the index must be at most 1 MiB, and is parsed without network access (LIBXML_NONET);
• a root other than <packages> gives "The server did not answer with a package index.";
• a name must match ^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$, other entries are skipped;
• it shows name, type, summary and version, next to the version of an imported copy;
• fetch accepts only a url that starts with https://, and a package of at most 256 MiB.

See Package servers in ezupdate.

A minimal index of your own #

For a server with one site package that requires one other package:

<?xml version="1.0"?>
<packages vendor="example">
  <package name="example_classes" type="contentclass"
           url="https://packages.example.com/6.0/6.0.15/example_classes.ezpkg"/>
  <package name="example_site" version="1.0-0" type="site"
           summary="Example site"
           description="The starter site of Example Inc."
           url="https://packages.example.com/6.0/6.0.15/example_site.ezpkg"
           thumbnail_url="https://packages.example.com/6.0/6.0.15/thumbnails/example_site.png"/>
</packages>

Every package that a site package names in <dependencies><requires> must either have an entry here or already be imported on the installation. See Running your own package server and Declaring dependencies.

Checking an index #

# well formed?
xmllint --noout index.xml

# every url answers 200?
grep -o 'url="[^"]*"' index.xml | cut -d'"' -f2 | while read -r u; do
  printf '%s %s\n' "$(curl -s -o /dev/null -w '%{http_code}' "$u")" "$u"
done

The second command checks both url and thumbnail_url. Run both before you publish an index, and before you open a pull request for the shared server (Contribute your site package).

Related pages #

• Site packages: start here
• The package server
• What is on the package server
• Package server settings
• How the setup wizard uses packages
• The setup wizard, 5.3.8 Site package
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.