<file> – documenting a file in the <contents> tag

Describing files

The <file> tag describes a file in a directory in the package sources. File tags may only occur as children of <dir> tags.

File Tasks can be used to modify files at package time or at installation.


Required attributes
Attribute name Description
name Name of the file in the sources
role Type of the file. See roles.
Optional attributes
Attribute name Description
baseinstalldir Relative location where all files and subdirectories will be installed
md5sum MD5 hash about file contents.This is automatically generated when executing pear package, so you should never set it manually.

Previous optional attributes (package.xml v1) <platform> and <install-as> have been replaced by the release tags.

Specifically, <install> is used to specify <install-as>, and the <ignore> tag can be used in conjunction with <installconditions> to exclude packages from being installed on particular platforms.


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

Possible values
Role value Description Destination dir
php PHP source file $php_dir (your include path)
doc Documentation or example file $doc_dir/Package_Name/
data Package related data files (graphics, data tables, CSS etc.) $data_dir/Package_Name/
www Files for the HTTPd document root $www_dir/
test Package related test files (unit-tests etc) $test_dir/Package_Name/
script Package related shell scripts the PHP binary directory ($bin_dir) or PHP_PEAR_BIN_DIR if defined
ext Extension, dynamically loadable library the PHP extension directory ($ext_dir) or PHP_PEAR_EXTENSION_DIR if defined
src / extsrc C or C++ source code not copied directly - used to build a extension

Directory locations like $php_dir are configurable in PEAR. You can use pear config-show or pear config-get php_dir to retrieve their values.


  <dir name="/">
   <dir name="examples">
    <!-- gets installed as $doc_dir/Package_Name/examples/authors.php -->
    <file name="authors.php" role="doc" />
    <file name="authors.tpl" role="doc" />
    <file name="README"      role="doc" />

   <dir name="HTML">
    <dir name="Template">
     <!-- gets installed as $php_dir/HTML/Template/PHPLIB.php -->
     <file name="PHPLIB.php"     role="php" />
     <dir  name="PHPLIB">
      <file name="Generator.php" role="php" />
      <file name="Helper.php"    role="php" />
      <file name="Tool.php"      role="php" />
      <file name="Validator.php" role="php" />
   <dir name="tests">
    <file name="AllTests.php"      role="test" />
    <file name="GeneratorTest.php" role="test" />
    <file name="HelperTest.php"    role="test" />
    <file name="ValidatorTest.php" role="test" />
documenting a directory in the <contents> tag (Previous) specialized file installation and manipulation (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.