Basically PEAR_PackageFileManager takes an existing package.xml file and updates it with a new filelist and changelog.

This document is written as a guide to and reference for the PEAR_PackageFileManager package, for both beginner and expert users.

At the beggining, maintainers should wrote their package xml file by hand. PEAR_PackageFileManager (PFM) revolutionizes the maintenance of PEAR packages. With a few parameters, the entire package.xml is automatically updated with a listing of all files in a package.

Since first alpha release of PFM 1.6.0, this package can manage the new package.xml 2.0 format introduce with PEAR 1.4.0

The most significant change in PEAR 1.4 was addition of channels, a simple and effective method of distributing application development. PFM 1.6.0 help maintainers to build and manage the new package.xml 2.0 format that it is now simpler to distribute any PHP code project using the PEAR installer than it ever was.

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. Version 2.0 contains several important enhancements over version 1.0, including

This chapter will describe the allowed elements of the package definition file.

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

     
$ pear install PEAR_PackageFileManager
     
    

	Note
	Since version 1.6.0a1, PEAR_PackageFileManager supports package.xml 2.0 with the PEAR_PackageFileManager2 class.

As any other xml file, the package definition file package.xml begin with a standard xml prolog. The toplevel element in package.xml is the element <package version="2.0">.

The allowed sub elements are (bold entry is mandatory, while normal entry is optional):

The tutorial is divided into 9 short lessons. In each lesson, you will learn how to create a new release, manage developers, files list, dependencies, perform complex installation tasks, and much more.

After you complete the tutorial, you can apply the skills you learn to your own packager copy.

Lesson 1, introducing PEAR_PackageFileManager compares automated and manual building methods.

Lesson 2, setting options defines types and values, and tells when and why you should use an option rather than an other.

Lesson 3, creating a new package teaches you how to build your first package from scratch.

Lesson 4, maintaining users list teaches you how to update the maintainers list. Add a new one, make one inactive, or definitively remove him.

Lesson 5, using tasks to customize file installation teaches you how to perform a custom installation with 3 basic tasks (replace, windowseol, unixeol) and 1 complex (postinstallscript).

Lesson 6, maintaining dependencies list teaches you how to update the dependencies list. Add a new one, remove one or just change its content.

Lesson 7, using custom file roles teaches you how to customize installation locations for each file rather than use standard categories (php, data, doc, test, script, src, ext).

Lesson 8, using custom file tasks teaches you how to customize installation with a third party task file, rather than using standard basic tasks: replace, eol, postinstall script.

Lesson 9, handling changelog teaches you how to read, remove, modify a changelog entry.

If you have ever created package xml manually, you are aware of its drawbacks. Manual building is time-consuming and tedious, giving sometime typo errors or xml grammar validation errors.

Automated building package.xml with PEAR_PackageFileManager addresses these problems by dramatically speeding up the building/validating process. You can create package scripts that check all aspects of your application distribution.

Default behavior may be changed in many way. First one is to define options with the setOptions() method. Here are the list of all available options, with their default values:

           
array(
   'h' => 'src',
   'c' => 'src',
   'm4' => 'src',
   'w32' => 'src',
   'dll' => 'ext',
   'php' => 'php',
   'html' => 'doc',
   '*' => 'data',
)
           
          

           
array(
   'docs' => 'doc',
   'examples' => 'doc',
   'tests' => 'test',
)
           
          

While in reality, we could find the same generator script to build a package.xml on first time, and update it later, both classes PEAR_PackageFileManager and PEAR_PackageFileManager2 provides two distinct ways of generation, using : setOptions() and importOptions(). We will focus only, in this chapter, on the first method. Later we will see usage of second method when we will talk how to update an existing package.

Lets see step by step how to define a new package with the two versions of PEAR_PackageFileManager.

To define a new package we will need to know some informations, such as : its name, a little summary, and a longer description. But we need also to know where package sources resides, and where it should be installed (on PEAR infrastructure).

With package.xml version 1.0, almost all properties were set with the setOptions() method. With package.xml version 2.0, there are new functions to get/set property individually. Among these ones, there is :

To produce a package.xml version 1.0, here is the basic sheme

To produce a package.xml version 2.0

A new release, depends in part of package type, but as common properties, you should at least read/set :

To produce a package.xml version 1.0

To produce a package.xml version 2.0

Even, if its not yet perfect, we have built our first package.xml.

	Important
	A point in favor of PEAR_PackageFileManager2. It may generates package with PHP4 even if PHP5 tokens are detected in source code, while PEAR_PackageFileManager cannot.

No big change since API 1.5.x that manage package.xml 1.0; We use the same method name addMaintainer() with parameters :

	Important
	No checking of duplicates is performed, use updateMaintainer() for that purpose.

	Warning
	Role, and Handle parameters are not given in same order. See example below:

To produce a package.xml version 1.0

To produce a package.xml version 2.0

	Tip
	You may now with PEAR_PackageFileManager 1.6.0+ add a new user with a default inactive status. It was not possible with package xml 1.0; When a user was added as maintainer, it was considered as active. No way to made him inactive, except to remove him definitively. See previous example with "davidc", added as inactive.

If you think this function is useless, you may consider that the package script generator could use data coming from another source (such as a database, a flat file, ...) rather than just hard-coded.

	Important
	This feature is only available for PEAR_PackageFileManager 1.6.0 or better. To do the same thing, by programming, with package.xml version 1.0, you should set options with an empty "maintainers" array first, before apply the addMaintainer() method.

To produce a package.xml version 1.0

To produce a package.xml version 2.0

Once again, if you think this function is useless, you may consider that the package script generator could use data coming from another source (such as a database, a flat file, ...) rather than just hard-coded.

Checking of duplicates is performed by usage of updateMaintainer(), and even allow adding a new user if he did not exists.

	Important
	This feature is only available for PEAR_PackageFileManager 1.6.0 or better. To do the same thing, by programming, with package.xml version 1.0, you should set options with an empty "maintainers" array first, before apply the addMaintainer() method.

To produce a package.xml version 1.0

To produce a package.xml version 2.0

While API 1.5.x did not provides any way to retrieve user data of a maintainer. PEAR_PackageFileManager 1.6.0+ allow to get a full list organized by role or not, or a restricted list to a specific role. These methods to get data are : getMaintainers(), getLeads(), getDevelopers(), getContributors() and getHelpers().

Here are the 5 methods in action :

With such functions, we can retrieve easily a specific user and change its properties. For example, suppose an helper become a new lead on the next stable release.

We could write something like :

The replace task is nearly identical to the old <replace> tag from package.xml 1.0, and does a text search-and-replace of a file's contents.

In this example we will specialize file pear-phpdoc contents on installation, with the most common and used basic task : <tasks:replace>.

Search all @PHP-BIN@ occurences in source file pear-phpdoc, and replace them by value of option php_bin (PHP CLI/CGI binary location).

To produce a package.xml version 1.0

To produce a package.xml version 2.0

Tip

If all your files, or almost all of them as the same task replacement to do, you can use the addGlobalReplacement() function that accept same $type, $from, $to parameters (#2, #3, #4) of addReplacement(). <?php require_once 'PEAR/PackageFileManager2.php';   PEAR::setErrorHandling(PEAR_ERROR_DIE);   $p2 = new PEAR_PackageFileManager2(); //... $p2->addGlobalReplacement('pear-config', '@PHP-BIN@', 'php_bin'); ?>

Windows and Unix platform handle end-of-line in a specific way that you should take care if you don't want to have surprise at run-time.

Windows convert line endings to \r\n, while Unix convert line endings to \n. You may decides to prevent problem at package-time, as well as at install-time, and adding two basic tasks : <tasks:windowseol>, and <tasks:unixeol>.

	Note
	This feature is only available for package.xml, version 2.0

In this example we have two files pear-phpdoc and pear-phpdoc.bat that only one version should be installed at run-time. We will see later how to specify this condition.

If you want to do something else than just basic tasks (search and replace string, converting line ending), extreme customization is possible with <postinstallscript> tag. This tag define parameters that are used by PEAR installer to retrieve user input, while running a post-install script.

	Note
	This feature is only available for package.xml, version 2.0

Distribution of full web application, including a database, is one of common problem that <tasks:postinstallscript> may solve.

Scripting actions proceed after files copy

Introduction to a class pattern

Initializing environment

Proceeding post install task

Introduction to a class pattern

Post-install script files can be named anything one desires, but the class within the file must be the same name as the file with all path separators replaced by underscores, and a fixed postfix "_postinstall". In other words, this postinstall script: server/mysqlinstall.php, must contain a class named server_mysqlinstall_postinstall.

API of a post install script always match, at least 2 functions :

init()

that initialize script environment with :

• parameter #1 a reference to a PEAR_Config instance (current configuration used for installation).

• parameter #2 a reference to the current PEAR_PackageFileManager instance.

• parameter #3 the last version of this package that was installed. This is a very important parameter, as it is the only way to determine whether a package is being installed from scratch, or upgraded from a previous version. Using this parameter, it is possible to determine what incremental changes, if any, need to be performed.

run()

is called at the conclusion of each parameter group in order to process the user's responses to queries. This method carry two parameters :

• parameter #1 is an array that will contain a list of successfully completed parameter group sections. This can be used to restore any system changes made by the installation script.

• parameter #2 identify the most recent paramgroup or contains _undoOnError only triggered by the PEAR installer on rollback process.

In our example, we should have a class pattern as this one :

1. <?php
2. class server_mysqlinstall_postinstall
3. {
4.     var $_config;
5.     var $_ui;
6.     var $_pkg;
7.     var $lastversion;
8.  
9.     function init(&$config, &$pkg, $lastversion)
10.     {
11.         $this->_config = &$config;
12.         $this->_ui = &PEAR_Frontend::singleton();
13.         $this->_pkg = &$pkg;
14.         $this->lastversion = $lastversion;
15.         return true;
16.     }
17.  
18.     function run($answers, $phase)
19.     {
20.     }
21. }
22. ?>

Initializing environment

This phase is important and allow script to communicate with a backend logger ($this->_ui), get information from your PEAR installation copy ($this->_config), get information on package release you are trying to install/upgrade ($this->_pkg) and the previous version installed (if any).

You may also add other data you think it's necessary to task proceed. For example a database existence indicator ($this->databaseExists), and what kind of driver we could use: either mysql or mysqli ($this->mysqliAvailable).

1. <?php
2. class server_mysqlinstall_postinstall
3. {
4. //...
5.     var $databaseExists;
6.     var $mysqliAvailable;
7.  
8.     function init(&$config, &$pkg, $lastversion)
9.     {
10.         //...
11.         $this->databaseExists  = false;
12.         $this->mysqliAvailable = extension_loaded('mysqli');
13.  
14.     }
15. //...
16. }
17. ?>

Proceeding post install task

Deeper inside class server_mysqlinstall_postfix and run() method, we find :

• a way to commit action (each paramgroup id).

• and another to revert action : _undoOnError

1. <?php
2. class server_mysqlinstall_postinstall
3. {
4. //...
5.  
6.     function run($answers, $phase)
7.     {
8.         switch ($phase) {
9.             case 'databaseSetup' :
10.                 return $this->createDatabase($answers);
11.                 break;
12.             case '_undoOnError' :
13.                 // answers contains paramgroups that succeeded in reverse order
14.                 foreach ($answers as $group) {
15.                     switch ($group) {
16.                         case 'databaseCreate' :
17.                             if ($this->lastversion || $this->databaseExists) {
18.                                 // don't uninstall the database
19.                                 break;
20.                             }
21.                             // code to drop the database
22.                         // ... other case ...
23.                     }
24.                 }
25.                 // ...
26.                 break;
27.         }
28.     }
29. }
30. ?>

Explore in details one action (paramgroup id): databaseCreate specialized to creating new database (default is peartest) given by param name database of this paramgroup.

1. <?php
2. class server_mysqlinstall_postinstall
3. {
4.     var $dbhost;
5.     var $db;
6.     var $user;
7.     var $password;
8. //...
9.  
10.     function createDatabase($answers)
11.     {
12.         $this->dbhost   = $answers['dbhost'];
13.         $this->db       = $answers['database'];
14.         $this->user     = $answers['user'];
15.         $this->password = $answers['password'];
16.  
17.         // Try to connect to database
18.         $conn = $this->getDBConnection();
19.         if (!$conn) {
20.             return false;
21.         }
22.  
23.         if ($this->mysqliAvailable) {
24.             $query = mysqli_select_db($conn, $this->db);
25.         } else {
26.             $query = mysql_select_db($this->db, $conn);
27.         }
28.         if ($query) {
29.             // upgrading database schema/data ?
30.             $this->databaseExists = true;
31.             // ...
32.         } else {
33.             // create database
34.             $this->databaseExists = false;
35.  
36.             if ($this->mysqliAvailable) {
37.                 $query = mysqli_query($conn, 'CREATE DATABASE ' . $this->db);
38.                 if ($query) {
39.                     $query = mysqli_select_db($conn, $this->db);
40.                 }
41.             } else {
42.                 $query = mysql_query('CREATE DATABASE ' . $this->db, $conn);
43.                 if ($query) {
44.                     $query = mysql_select_db($this->db, $conn);
45.                 }
46.             }
47.  
48.             if (!$query) {
49.                 if ($this->mysqliAvailable) {
50.                     $err = mysqli_error($conn);
51.                 } else {
52.                     $err = mysql_error();
53.                 }
54.                 $this->_ui->outputData('Database creation failed: ' . $err);
55.                 $this->closeDB($conn);
56.                 return false;
57.             }
58.         }
59.         $this->closeDB($conn);
60.         return true;
61.     }
62.  
63.     function getDBConnection()
64.     {
65.         if ($this->mysqliAvailable) {
66.             $conn = mysqli_connect($this->dbhost, $this->user, $this->password);
67.         } else {
68.             $conn = mysql_connect($this->dbhost, $this->user, $this->password);
69.         }
70.         if (!$conn) {
71.             $this->_ui->outputData('Connection to mysql server failed');
72.             return false;
73.         }
74.         return $conn;
75.     }
76.  
77.     function closeDB($conn)
78.     {
79.         if ($this->mysqliAvailable) {
80.             mysqli_close($conn);
81.         } else {
82.             mysql_close($conn);
83.         }
84.     }
85. }
86. ?>

	Important
	In case of problem, don't forget to provide a way to revert action already applied. PEAR installer will then trigger _undoOnError phase run.

PHP and PEAR installer dependencies are required in all package.xml with at least the minimum version property set.

           
$p2->setPhpDep('4.2.0');
           
          

           
 <dependencies>
  <required>
   <php>
    <min>4.2.0</min>
   </php>
  </required>
 </dependencies>
           
          

           
$p2->setPhpDep('4.2.0', '5.0.0');
           
          

           
 <dependencies>
  <required>
   <php>
    <min>4.2.0</min>
    <max>5.0.0</max>
   </php>
  </required>
 </dependencies>
           
          

           
$p2->setPhpDep('4.2.0', '5.0.0', array('5.0.0'));
           
          

           
 <dependencies>
  <required>
   <php>
    <min>4.2.0</min>
    <max>5.0.0</max>
    <exclude>5.0.0</exclude>
   </php>
  </required>
 </dependencies>
           
          

           
$p2->setPhpDep('4.2.0', '5.1.0', array('5.0.0', '5.0.1'));
           
          

           
 <dependencies>
  <required>
   <php>
    <min>4.2.0</min>
    <max>5.1.0</max>
    <exclude>5.0.0</exclude>
    <exclude>5.0.1</exclude>
   </php>
  </required>
 </dependencies>
           
          

           
$p2->setPearinstallerDep('1.4.3');
           
          

           
 <dependencies>
  <required>
   <pearinstaller>
    <min>1.4.3</min>
   </pearinstaller>
  </required>
 </dependencies>
           
          

           
$p2->setPearinstallerDep('1.4.3', '1.4.11');
           
          

           
 <dependencies>
  <required>
   <pearinstaller>
    <min>1.4.3</min>
    <max>1.4.11</max>
   </pearinstaller>
  </required>
 </dependencies>
           
          

           
$p2->setPearinstallerDep('1.4.0', false, '1.4.3');
           
          

           
 <dependencies>
  <required>
   <pearinstaller>
    <min>1.4.0</min>
    <recommended>1.4.3</recommended>
   </pearinstaller>
  </required>
 </dependencies>
           
          

           
$p2->setPearinstallerDep('1.4.0', false, false,
    array('1.4.1', '1.4.2'));
           
          

           
 <dependencies>
  <required>
   <pearinstaller>
    <min>1.4.0</min>
    <exclude>1.4.1</exclude>
    <exclude>1.4.2</exclude>
   </pearinstaller>
  </required>
 </dependencies>
           
          

PEAR 1.4.0 and package.xml 2.0 supports more package dependencies than package.xml 1.0, but we will see in details what are differences and how we can do (try to do) the same job.

           
// 'has' relation
$p1->addDependency('PEAR',
    false, 'has', 'pkg', false);
           
          

           
<deps>
 <dep type="pkg" rel="has"
      optional="no">
      PEAR
 </dep>
</deps>
           
          

           
// 'greater or equal' relation
$p1->addDependency('Archive_Tar',
    '1.0.0', 'ge', 'pkg', false);
           
          

           
<deps>
 <dep type="pkg"
      rel="ge" version="1.0.0"
      optional="no">
      Archive_Tar
 </dep>
</deps>
           
          

           
// 'greater than' relation
$p1->addDependency('MDB2',
    '2.1.0', 'gt', 'pkg', true);
           
          

           
<deps>
 <dep type="pkg"
      rel="gt" version="2.1.0"
      optional="yes">
      MDB2
 </dep>
</deps>
           
          

           
// 'less or equal' relation
$p1->addDependency('Console_Getopt',
    '1.2', 'le', 'pkg');
           
          

           
<deps>
 <dep type="pkg"
      rel="le" version="1.2"
      optional="no">
      Console_Getopt
 </dep>
</deps>
           
          

           
// 'less than' relation
$p1->addDependency('Text_Highlighter',
    '0.7.0', 'lt', 'pkg', true);
           
          

           
<deps>
 <dep type="pkg"
      rel="lt" version="0.7.0"
      optional="yes">
      Text_Highlighter
 </dep>
</deps>
           
          

           
// 'between' relation
$p1->addDependency('PEAR_PackageFileManager',
    '1.6.0a1', 'ge');
$p1->addDependency('PEAR_PackageFileManager',
    '1.6.0b5', 'le');
           
          

           
<deps>
 <dep type="pkg"
      rel="ge" version="1.6.0a1"
      optional="no">
      PEAR_PackageFileManager
 </dep>
 <dep type="pkg"
      rel="le" version="1.6.0b5"
      optional="no">
      PEAR_PackageFileManager
 </dep>
</deps>
           
          

           
// 'conflicting' dependency
$p1->addDependency('DB',
    false, 'not', 'pkg');
           
          

           
<deps>
 <dep type="pkg" rel="not">DB</dep>
</deps>
           
          

           
// 'has' relation
$p2->addPackageDepWithChannel('required',
    'PEAR', 'pear.php.net');
           
          

           
<dependencies>
 <required>
<!-- ... -->
  <package>
   <name>PEAR</name>
   <channel>pear.php.net</channel>
  </package>
 </required>
</dependencies>
           
          

           
// 'greater or equal' relation
$p2->addPackageDepWithChannel('required',
    'Archive_Tar', 'pear.php.net',
    '1.0.0');
           
          

           
<dependencies>
 <required>
<!-- ... -->
  <package>
   <name>Archive_Tar</name>
   <channel>pear.php.net</channel>
   <min>1.0.0</min>
  </package>
 </required>
</dependencies>
           
          

           
// 'greater than' relation
$p2->addPackageDepWithChannel('optional',
    'MDB2', 'pear.php.net',
    '2.1.0', false, false, '2.1.0');
           
          

           
<dependencies>
 <required>
<!-- ... -->
 </required>
 <optional>
  <package>
   <name>MDB2</name>
   <channel>pear.php.net</channel>
   <min>2.1.0</min>
   <exclude>2.1.0</exclude>
  </package>
 </optional>
</dependencies>
           
          

           
// 'less or equal' relation
$p2->addPackageDepWithChannel('required',
    'Console_Getopt', 'pear.php.net',
    false, '1.3.0');
           
          

           
<dependencies>
 <required>
<!-- ... -->
  <package>
   <name>Console_Getopt</name>
   <channel>pear.php.net</channel>
   <max>1.3.0</max>
  </package>
 </required>
</dependencies>
           
          

           
// 'less than' relation
$p2->addPackageDepWithChannel('optional',
    'Text_Highlighter', 'pear.php.net',
    false, '0.7.0', false, '0.7.0');
           
          

           
<dependencies>
 <required>
<!-- ... -->
 </required>
 <optional>
  <package>
   <name>Text_Highlighter</name>
   <channel>pear.php.net</channel>
   <max>0.7.0</min>
   <exclude>0.7.0</exclude>
  </package>
 </optional>
</dependencies>
           
          

           
// 'between' relation
$p2->addPackageDepWithChannel('required',
    'PEAR_PackageFileManager', 'pear.php.net',
    '1.6.0a1', '1.6.0b5');
           
          

           
<dependencies>
 <required>
<!-- ... -->
  <package>
   <name>PEAR_PackageFileManager</name>
   <channel>pear.php.net</channel>
   <min>1.6.0a1</min>
   <max>1.6.0b5</max>
  </package>
 </required>
</dependencies>
           
          

           
// 'conflicting' dependency
$p2->addConflictingPackageDepWithChannel('DB',
    'pear.php.net');
           
          

           
<dependencies>
 <required>
<!-- ... -->
  <package>
   <name>DB</name>
   <channel>pear.php.net</channel>
   <conflicts/>
  </package>
 </required>
</dependencies>
           
          

With package.xml 2.0, uri-based

When you use uri-based package dependencies rather than channel-based package dependencies (see previously), you have to use: addPackageDepWithUri() method instead of addPackageDepWithChannel().

Here is a simple example to produce:

1. <require>
2.  <package>
3.   <name>Foo<name>
4.   <uri>http://www.example.com/Foo-1.3.0 </uri>
5.  </package>
6. </require>

you should write:

1. $p2->addPackageDepWithUri('required', 'Foo', 'http://www.example.com/Foo-1.3.0' );

	Important
	Do not append tgz or tar extension, when you give the uri. PEAR installer will try to fetch http://www.example.com/Foo-1.3.0.tgz or http://www.example.com/Foo-1.3.0.tar

	Note
	List of package installed through pseudo channel __uri may be displayed, on command line, with : pear list -a

As with all dependencies that support versioning, all standard versioning tags are supported (min, max, recommended, exclude). In addition, the <conflicts> tag is supported to create a negative dependency.

With package.xml 1.0

Table 10.5. php extension dependencies version 1.0

PHP code	XML equivalent
// 'has' relation $p1->addDependency('gettext', false, 'has', 'ext');	<deps> <dep type="ext" rel="has" optional="no"> gettext </dep> </deps>

	Caution
	Do not use comparaison operator with version, on php extension dependency, it won't work as you would expected.

           
// 'has' relation
$p2->addExtensionDep('required', 'gettext');
           
          

           
<dependencies>
 <required>
<!-- ... -->
  <extension>
   <name>gettext</name>
  </extension>
 </required>
</dependencies>
           
          

           
// 'greater or equal' relation
$p2->addExtensionDep('optional', 'gd', '2.0.0');
           
          

           
<dependencies>
 <optional>
<!-- ... -->
  <extension>
   <name>gd</name>
   <min>2.0.0</min>
  </extension>
 </optional>
</dependencies>
           
          

Dealing with OS dependency to restrict a package installation is made with call to addOsDep() method.

For example, if we want to restrict a package installation on linux OS, or on every OS except windows, we should write :

           
$p2->addOsDep('linux');
           
          

           
<dependencies>
 <required>
<!-- ... -->
  <os>
   <name>linux</name>
  </os>
 </required>
</dependencies>
           
          

           
$p2->addOsDep('windows', true);
           
          

           
<dependencies>
 <required>
<!-- ... -->
  <os>
   <name>windows</name>
   <conflicts />
  </os>
 </required>
</dependencies>
           
          

Dealing with Architecture dependency to restrict a package installation to a specific OS and processor architecture is made with call to addArchDep() method.

For example, if we want to restrict a package installation on linux OS, and intel 8086 family processor, or on every architecture except Mac OS X (darwin), we should write :

           
$p2->addArchDep('linux-*-i?86-*');
           
          

           
<dependencies>
 <required>
<!-- ... -->
  <arch>
   <pattern>linux-*-i?86-*</pattern>
  </arch>
 </required>
</dependencies>
           
          

           
$p2->addArchDep('darwin', true);
           
          

           
<dependencies>
 <required>
<!-- ... -->
  <arch>
   <pattern>darwin</pattern>
   <conflicts />
  </arch>
 </required>
</dependencies>
           
          

Default role mapping array separates extension into seven categories.

Once a package that reference, manage, the new role is properly installed in your system, you can use it, and add it to the default role mapping array.

We suppose to have previously installed a package that manage the new role web. Here we will assume that all log files (*.log) will be copied into directory declared by <locationconfig> tag of xml web file role (see PEAR/Installer/Role/Web.xml).

However, if a user does not have the package installed that provides the custom role web, then the error message on installation will simply say File ... has invalid role "web" should be one of data, doc, php, script, test which is not very helpful.

If you don't want to give the same behavior to all file with same extension, but only to one or a set of them, then use option directive exceptions.

This problem may be solve easily by adding a <usersrole> tag documenting package to install that will handle the new role. Uses methods : addUsesrole() with (replace role) or without (append role) its resetUsesrole() companion.

           
$p2->resetUsesrole();
// use channel-based package
$p2->addUsesrole('web', 'Role_Web', 'pearified.com');
           
          

           
<usesrole>
 <role>web</role>
 <package>Role_Web</package>
 <channel>pearified.com</channel>
</usesrole>
           
          

           
$p2->resetUsesrole();
// use uri-based package
$p2->addUsesrole('web',
    'http://pearified.com/Role-1.1.1');
           
          

           
<usesrole>
 <role>web</role>
 <uri>http://pearified.com/Role-1.1.1</uri>
</usesrole>
           
          

	Tip
	If Role_Web package is not installed, then PEAR installer take aware user with a message like This package contains role "web" and requires package "channel://pearified.com/Role_Web" to be used.

Standard file tasks provided by default, allow to : search-and-replace string into file contents, change line-ending, and add a complex postinstall script.

If you want to specialize your installation with a complex task, you will need first to learn how to create customized task in PHP .

Once a package that reference, manage, the new task file is properly installed in your system (into directory PEAR/Task/), you can use it with a call to addTaskToFile().

We suppose to have previously installed a package that manage the new task stripwhitespace.

	Note
	Install the PEAR_Task_Stripwhitespace package version 0.1.0 on __URI channel. pear install http://pear.laurent-laville.org/get/PEAR_Task_Stripwhitespace-0.1.0.tgz

This script will generate something like :

	Important
	Allways generate file list contents with generateContents() before trying to add a task to one of file with addTaskToFile().

However, if a user does not have the package installed that provides the custom task stripwhitespace, then the error message on installation will simply say Unknown task "stripwhitespace" which is not very helpful.

This problem may be solve easily by adding a <userstask> tag documenting package to install that will handle the new task. Uses methods : addUsestask() with (replace task) or without (append task) its resetUsestask() companion.

           
$p2->resetUsestask();
// use channel-based package
$p2->addUsestask('foo',
    'Task_Foo', 'pear.example.com');
           
          

           
<usestask>
 <task>foo</task>
 <package>Task_Foo</package>
 <channel>pear.example.com</channel>
</usestask>
           
          

           
$p2->resetUsestask();
// use uri-based package
$p2->addUsestask('foo',
    'http://pear.example.com/Task_Foo-0.1.0');
           
          

           
<usestask>
 <task>foo</task>
 <package>Task_Foo</package>
 <uri>http://pear.example.com/Task_Foo-0.1.0</uri>
</usestask>
           
          

	Tip
	If Task_Foo package is not installed, then PEAR installer take aware user with a message like This package contains task "foo" and requires package "http://pear.example.com/Task_Foo-0.1.0.tgz" to be used.

If you want to retrieve information from an old version, or just count releases, you have only to use one method: getChangelog().

We will create a RSS newsfeed with result of getChangelog() assisted by PEAR package XML_Serializer .

	Note
	Original article create a RSS newsfeed is locate at http://freedomink.org/node/62

If you don't want to keep history of changes when you generate a new release, then you have only to set option clearchangelog to true.

	Warning
	This option is only available since stable release 1.6.0