package.xml reference
This page is for developers who write or change a package.xml by hand. It lists every element and attribute that
eZPackage understands, how it reads each one (eZPackage::parseDOMTree()), how it writes it back
(eZPackage::domStructure()), and the traps between the two. All references are to
kernel/classes/ezpackage.php unless another file is named.
Contents
- How the file is read
- The root element
- Description elements
- People, packaging and history
- Release elements
- Files
- Dependencies
- Install scripts: settings
- Install and uninstall items
- Metadata and install data
- What is lost when the kernel writes a package
- Related pages
How the file is read
- The reader looks most elements up with
getElementsByTagName(), which finds an element anywhere below the root and takes the first one. Keep every element where the writer puts it; do not reuse an element name inside another element (the one exception the reader handles is<version>, read with XPath as a direct child of<package>, so<ezpublish><version>does not get in its way). - A definition without a root element or without a non-empty
<name>is not a package: it is not read, and the package lists skip it. <version><number>,<version><release>and<type value>must each be absent, empty, or a plain token of 1 to 64 characters from0-9 A-Z a-z . _ + -(isValidDefinitionToken()). Anything else and the whole definition is refused.- A JSON package (
package.json) is turned into the same DOM first, so everything below applies to both formats.
The root element
<package version="3.5.2" development="false" install_type="install">| Attribute | Read | Written |
|---|---|---|
install_type | install (default) or import; see Import versus install | always |
development | "true" means development, anything else not | always, false |
version | not read | always eZPackage::VERSION, 3.5.2 (the format version, not the package version) |
other attributes (the 7x site packages carry is_active="true") | not read | not written |
Description elements
| Element | Required | Notes |
|---|---|---|
<name> | yes | The package name. On import it must pass eZPackage::isValidName() (letters of either case, digits, _ and -, not starting with -), else STATUS_INVALID_NAME. It is also the directory name in the repository |
<summary> | no | One line; the setup wizard shows it as the site's title and [site_details] Title defaults to it |
<description> | no | Longer text |
<vendor> | no | Chooses the repository directory: the vendor run through the urlalias transformation (7x stays 7x, eZ systems becomes ez-systems); without a vendor the package goes to local |
<type value="..."/> | no | The package type, trimmed; see Package types |
<priority value="..."/> | no | Kept and filterable in eZPackage::fetchPackages(); nothing in the installer uses it |
<extension name="..."/> | no | The extension a package belongs to; filterable in fetchPackages() |
<source> | no | Free text |
<ezpublish><version>, <named-version> | no | The Exponential version the package was made with (6.0.15-stable, 6.0 in sevenx_multisite). Kept for information: the package code does not compare it with the running version. The element name is historical and stays as it is |
People, packaging and history
<maintainers>
<maintainer><name>...</name><email>...</email><role>lead</role></maintainer>
</maintainers>
<packaging><timestamp>1705211779</timestamp><host>...</host><packager>...</packager></packaging>
<documents><document mime-type="text/plain" name="LICENCE" os="" audience=""/></documents>
<groups><group name="..."/></groups>
<changelog>
<entry timestamp="..." person="..." email="..." release="1"><change>Creation of package.</change></entry>
</changelog>| Element | Notes |
|---|---|
<maintainer> | name, email, optional role; the roles offered are [MaintainerSettings] RoleList[]: lead, developer, designer, contributor, tester |
<packaging> | When and where the archive was made. Without it the package reads as "not packaged" (no time, no host) |
<document> | A file in documents/; name and mime-type, optional os and audience |
<group> | Free group names |
<entry> | One per release, attributes timestamp, person, email, release, one <change> per change |
What a published package must fill in is in Documentation requirements.
Release elements
<version><number>6.0</number><release>15-stable</release></version>
<timestamp>1705211779</timestamp>
<licence>GPL</licence>
<state>stable</state>| Element | Notes |
|---|---|
<version><number> | The version number, trimmed. New packages from the wizards get a strict SemVer 2.0.0 number; reading stays tolerant (kernel/classes/ezpackageversion.php) |
<version><release> | The release number, trimmed. eZPackage::getVersion() joins them as <number>-<release>; that string is what min-version is compared with and what the ezpackage table records |
<timestamp> | The release time; only a <timestamp> that is a direct child of <package> counts |
<licence> | The license identifier; matched against package.ini [LicenseSettings] (AliasList[GPL]=GPL-2.0-or-later makes GPL known). An unknown value is shown as it is. The element keeps its historical spelling |
<state> | One of [PackageSettings] StateList[]: mature, stable, beta, alpha, prealpha |
Files
<simple-files>
<simple-file key="..." original-path="..." package-path="simplefiles/24ec46f7.jpg"/>
</simple-files>
<files>
<collection name="default">
<file-list type="thumbnail" variable-name="thumbnail">
<file name="thumbnail.png" md5sum="77a7bc0cc6e1e5138ca7a6e39a130307"/>
</file-list>
</collection>
</files>| Element | Attributes |
|---|---|
<simple-file> | key, original-path, package-path (below simplefiles/) |
<collection> | name; a <files> without <collection> is read as one collection named by its own name |
<file-list> | type (file, design, ini, thumbnail, image ...), design, role, role-value, variable-name |
<file> | name, sub-directory, path (where it came from), md5sum, type (dir for a directory), variable-name |
The first thumbnail file of the default collection is the picture the setup wizard shows for a site package
(thumbnail-list).
Dependencies
<dependencies>
<provides/>
<requires>
<require type="ezpackage" name="sevenx_classes" min-version="5.1"/>
</requires>
<obsoletes/>
<conflicts/>
</dependencies>Four sections with the items <provide>, <require>, <obsolete> and <conflict>. The reader keeps every
attribute of an item. The installer acts on <require type="ezpackage"> with name and min-version; see
Dependencies and install order. A design package of 7x declares
<provide type="ezfile" name="collection" value="default"/>.
Install scripts: settings
<settings>
<settings-file filename="install-scripts.php"/>
</settings>Each filename is a PHP file in the package's settings/ directory that the Create sites step includes. See
Install scripts in a site package.
Install and uninstall items
<install>
<item type="ezcontentclass" filename="class-article" sub-directory="ezcontentclass"/>
<item type="ezfile" collection="default"/>
</install>
<uninstall>
<item type="ezcontentclass" filename="class-article" sub-directory="ezcontentclass"/>
</uninstall>| Attribute | Meaning |
|---|---|
type | The handler, looked up in [PackageSettings] HandlerAlias[] |
filename, sub-directory | The item's document: <sub-directory>/<filename>.xml (or .json) |
name, os | Optional; os narrows an item to one operating system in installItemsList() |
| handler attributes | Read by the handler: collection (ezfile), original-path and database-type (ezsql) |
What each type does is in Install items and handlers.
Metadata and install data
<metadata><entry key="expai.provenance">value</entry></metadata>: free strings kept with a package by tools, written only when there is any (eZPackage::setMetadata()).<install-data><data type="..."><element name="" value=""/><array name="">...</array></data></install-data>: what handlers remember between install and uninstall; written by the kernel, not by hand.
What is lost when the kernel writes a package
domStructure() writes the elements in a fixed order (name, summary, description, vendor, priority, type,
extension, source, ezpublish, maintainers, packaging, documents, groups, changelog, simple-files, files, version,
timestamp, licence, state, dependencies, install, uninstall, install-data, metadata). Keep these differences in
mind before you let the kernel rewrite a hand-made file:
Note
Fixed in 6.0.15: domStructure() writes <settings> (after <dependencies>) and every attribute of a
dependency item. Before, a site package stored again by the kernel lost its install scripts' list and the
min-version of its <require> items. Editing a site package's package.xml in its source repository is still
the clearest way to change it.
- The root
versionbecomes3.5.2; attributes the kernel does not know are dropped. <files>is left out when there is no file.<settings>is left out when the package has no settings file.- A dependency item is written with
type,name,value(when not empty) and, from 6.0.15 on, every other attribute it was read with (min-version,max-version...). Before 6.0.15 those were dropped, so a stored site package lost its version requirements.
Related pages
- Site package basics
- Site packages: start here
- package.xml required fields
- Version numbers
- Package licenses and Semantic Versioning
- The JSON package format
- Contribute your site package
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.