LD SoftwareBespoke Software, Web Design, Security Consultants and Host Services.


You have been warned!
We have caught 5846 shameful hackers.


Paypal Referral
Sign up for PayPal and start accepting credit card payments instantly.

Link Exchange
Join our free link exchange

Click Here
The package definition file package.xml

Chapter 15. The package definition file package.xml

Introduction to the package definition file package.xml

package.xml version 1.0 is deprecated

package.xml 1.0 is deprecated, please use package.xml version 2.0, documentation is found at package.xml 2.0 documentation

The package definition file package.xml is, as the name already implies, a well-formed XML file that contains all information about a PEAR package.

This chapter will describe the allowed elements of the package definition file and it will discuss how to create such a file for your package.

The PEAR_PackageFileManager package simplifies the creation of package.xml. You can install PEAR_PackageFileManager via the usual command

$ pear install PEAR_PackageFileManager

Allowed elements

The toplevel element in package.xml is the element <package version="1.0">. The allowed sub elements are:

  • <name>: The name of the package.

  • <summary>: Short summary of the package's description.

  • <description>: Full length description of the package.

  • <license>: The license of the package (LGPL, PHP License etc.).

  • <maintainers>: Information about the maintainers of the package.

    • maintainer: Information about a single maintainer. (May be used multiple times.)

      • <user>: The account name of the user.

      • <role>: The role the user has during package development. (Can be either lead, developer, helper.)

      • <name>: The realname of the user.

      • <email>: The email address of the user.

  • <release>: Information about the current release.

    • <version>: The version number of the release.

    • <state>: The state of the release. (Can be one of stable, beta, alpha, devel, or snapshot.)

    • <date>: The date when the release has been rolled.

    • <license>: The license under which the code is available.

    • <notes>: Releasenotes

    • <filelist>

      • <file name="xxx" role="xxx" />: Filename

      • <dir name="xxx" [role="xxx"]>: Name of a subdirectory. This subdirectory can again contain <file role="xxx"> entries.

    • <deps>: List of dependencies of the package.

      • <dep type="xxx" rel="yyy" optional="yes">name</dep> : For more information about dependencies, please see below.

  • <changelog>: Changelog-like information about the package.

    • <release>

      • <version>: Version of the specific release.

      • <state>: State of the specific release.

      • <date>: Date when the specific release has been rolled.

      • <notes>: Changelog information

Allowed characters

The letters allowed inside elements are A-Z and a-z. Other characters, such as é must use entities (in this case: &eacute;).

If you create your package.xml files using the PEAR_PackageFileManager, upgrade your PEAR installation to version 1.4.0a2 or greater and you won't have to worry about this because the file manager takes care of this automatically.

If you write your package.xml files manually, you will need to enter the entities yourself. A list of the most common entities can be found at: http://www.evolt.org/article/A_Simple_Character_Entity_Chart/17/21234/ If the characters you need aren't in that list, go to http://www.oasis-open.org/docbook/xmlcharent/0.1/index.shtml and look at the other entity lists.


In order to validate package.xml files one can use the xmllint tool that comes with libxml2.

xmllint --dtdvalid http://pear.php.net/dtd/package-1.0 --noout package.xml

Creating a package definition file

Example 15-1. Basic package.xml

<?xml version="1.0" encoding="ISO-8859-1" ?>
<package version="1.0">
 <summary>Make money fast.</summary>
  This package helps you to make money pretty fast.
 <license>PHP License</license>
   <name>Joe Foo</name>

   This is the first release.
   <dir name="/" baseinstalldir="Money">
    <file role="php" name="Fast.php" />

This package.xml can serve as a template for you as it already contains all necessary elements. In most cases you only need to change the character data between the tags in order to use the example in your package.

Example 15-2. Example for nested directories

<?xml version="1.0" encoding="ISO-8859-1" ?>


   This is the first release.
   <dir name="/" baseinstalldir="Money">
    <file role="php" name="Fast.php" />
    <dir name="Calculator">
     <file name="Calculator.php" role="php" />
     <file name="Currency.php" role="php" />
     <file name="Stocks.php" role="php" />
    <dir name="docs">
     <file name="README.txt" role="doc" />
     <file name="tutorial.txt" role="doc" />
     <dir name="examples">
      <file name="NASDAQ.php" role="php" />
      <file name="DAX.php" role="php" />

In this example you get to know a very handy feature: When you have a directory in your package that only contains files of the same type, you can add to role attribute even to the <dir> tag instead of adding it to every single <file> tag.

With the knowledge you aquired during this chapter you should now be able to produce a package definition file for your own package. If you still have questions concerning the topic, don't hesitate to ask on the mailinglist.

The file roles

The role-attribute in the <file> tag defines what type the file has and in which location it should be installed.

Table 15-1. Possible values

Value   Destination dir
php PHP source file the directory is determined by the package name
ext Extension, dynamically loadable library the PHP extension directory or PHP_PEAR_EXTENSION_DIR if defined
doc Documentation file {PEAR_documentation_dir}/Package_Name/
data Package related data files (graphics, data tables etc) {PEAR_data_dir}/Package_Name/
test Package related test files (unit-tests etc) {PEAR_test_dir}/Package_Name/
script Package related shell scripts the PHP binary directory or PHP_PEAR_BIN_DIR if defined
src and extsrc C or C++ source code not copied directly - used to build a extension

Defining Dependencies

The PEAR Package Manager supports checking for different system capabilities. You define those dependencies with the <dep> tag:

Example 15-3. package.xml with dependencies

The following example shows how to specificy dependencies for PHP 4.3.0 or better and XML_Parser 1.0.

<?xml version="1.0" encoding="ISO-8859-1" ?>

  <dep type="php" rel="ge" version="4.3.0" />
  <dep type="pkg" rel="has" version="1.0">XML_Parser</dep>

The type-attribute

The following types are supported:

Table 15-2. type values

Value   Meaning Example
pkg Package depends on a certain Package "HTML_Flexy"
ext Extension depends on a certain PHP extension "curl"
php PHP depends on a certain PHP version "4.2"
prog Program depends on a certain Program available in the system path. This is not supported in the PEAR installer. "latex"
os Operating System depends on a certain OS version "Linux"
sapi Server API depends on a certain Server API. This is not supported in the PEAR installer. "Apache"
zend Zend depends on a certain version of the Zend API. This is not supported in the PEAR installer. "2"

The DTD for the package definition file supports further types, but those are not supported yet.

The rel-attribute

The rel-attribute defines the relationship between the existing capability and the required.

Table 15-3. rel values

Value   Meaning Can be used with
has has the existing capability must have the requirement - version-attribute is ignored pkg, ext, php, prog, os, sapi, zend
eq equal the the existing capability must exactly match the version value pkg, ext, php, prog, os, sapi, zend
lt less than the existing capability must be less than the version value pkg, ext, php, zend
le less than or equal the existing capability must be less than or equal to the version value pkg, ext, php, zend
gt greater than the existing capability must be greater than the version value pkg, ext, php, zend
ge greater than or equal the existing capability must greater than or equal to the version value pkg, ext, php, zend
not conflicting dependency the dependency conflicts with the package, the two cannot co-exist. version is ignored. ext, php

Has will be used if no other value has been defined. Note that rel is required in PEAR 1.4.0 and newer.

The version-attribute

The attribute version defines the version that is used to compare.

The optional-attribute

The attribute optional can be used when a dependency is not required but having the package installed can bring enhanced functionalities. The only legal values are "yes" and "no". If the optional attribute is not present, a dependency is required. When optional="yes" is used, this attribute will result in installation messages similar to the following messages:

$ pear install <package>
Optional dependencies:
Package `XML_Tree' is recommended to utilize some features.
Package `MDB' is recommended to utilize some features.

Text Ads
There isn't content right now for this block.

Community Login


People Online:
Visitors: 11
Members: 1
Total: 12

Online Now:
01 : Monty

Like my code
Then please make a donation.

Which help me produce more free code.

Paypal Verified


Powered by PHP-Nuke

Valid CSS!

Valid Robots.txt

Bad Behavior

[Valid RSS]

[Valid RSS]
You can syndicate our News with backend.php And our Forums with rss.php
You can also access our feeds via Feedburner Site News and LD Software Forums
© 2009 ld-software.co.uk All Rights Reserved.
PHP-Nuke Copyright © 2005 by Francisco Burzi. This is free software, and you may redistribute it under the GPL. PHP-Nuke comes with absolutely no warranty, for details, see the license.
Page Generation: 0.39 Seconds