Class: PEAR_PackageFileManager
Source Location: Program_Root/PackageFileManager.php
Class PEAR_PackageFileManager
Class Overview
PEAR :: PackageGenerate updates the <filelist></filelist> section of a PEAR package.xml file to reflect the current files in preparation for a release.
The PEAR_PackageGenerate class uses a plugin system to generate the list of files in a package. This allows both standard recursive directory parsing (plugin type file) and more intelligent options such as the CVS browser PEAR_PackageFileManager_Cvs, which grabs all files in a local CVS checkout to create the list, ignoring any other local files. Other options include specifying roles for file extensions (all .php files are role="php", for example), roles for directories (all directories named "tests" are given role="tests" by default), and exceptions. Exceptions are specific pathnames with * and ? wildcards that match a default role, but should have another. For example, perhaps a debug.tpl template would normally be data, but should be included in the docs role. Along these lines, to exclude files entirely, use the ignore option. Required options for a release include version, baseinstalldir, state, and packagedirectory (the full path to the local location of the package to create a package.xml file for) Example usage: 1 <?php 2 require_once('PEAR/PackageFileManager.php'); 3 $packagexml = new PEAR_PackageFileManager; 4 $e = $packagexml->setOptions( 5 array('baseinstalldir' => 'PhpDocumentor', 6 'version' => '1.2.1', 7 'packagedirectory' => 'C:/Web Pages/chiara/phpdoc2/', 8 'state' => 'stable', 9 'filelistgenerator' => 'cvs', // generate from cvs, use file for directory 10 'notes' => 'We\'ve implemented many new and exciting features', 11 'ignore' => array('TODO', 'tests/'), // ignore TODO, all files in tests/ 12 'installexceptions' => array('phpdoc' => '/*'), // baseinstalldir ="/" for phpdoc 13 'dir_roles' => array('tutorials' => 'doc'), 14 'exceptions' => array('README' => 'doc', // README would be data, now is doc 15 'PHPLICENSE.txt' => 'doc'))); // same for the license 16 if (PEAR::isError($e)) { 17 echo $e->getMessage(); 18 die(); 19 } 20 $packagexml->addRole('pkg', 'doc'); // add a new role mapping 21 $e = $packagexml->writePackageFile(); 22 if (PEAR::isError($e)) { 23 echo $e->getMessage(); 24 die(); 25 } 26 ?> 27 28 In addition, a package.xml file can now be generated from 29 scratch, with the usage of new options package, summary, description, and 30 the use of the method
Located in Program_Root/PackageFileManager.php [line 171]
|
Methods
|
Method Summary
void|PEAR_Error |
addConfigureOption() |
Add an install-time configuration option for building of source |
void|PEAR_Error |
addDependency() |
Add a dependency on another package, or an extension/php |
void |
addMaintainer() |
Add a maintainer to the list of maintainers. |
void |
addRole() |
Add an extension/role mapping to the role mapping option |
void |
debugPackageFile() |
ALWAYS use this to test output before overwriting your package.xml!! |
PEAR_Error |
raiseError() |
Utility function to shorten error generation code |
void|PEAR_Error |
setOptions() |
Set package.xml generation options |
void|PEAR_Error |
writePackageFile() |
Writes the package.xml file out with the newly created <release></release> tag |
Methods
PEAR_PackageFileManager PEAR_PackageFileManager(
)
|
|
Does nothing, use setOptions
API Tags:
void|PEAR_Error addConfigureOption(
string
$name, string
$prompt, [string
$default = null]
)
|
|
Add an install-time configuration option for building of source
This option is only useful to PECL projects that are built upon installation
Parameters:
string |
$name: |
name of the option |
string |
$prompt: |
prompt to display to the user |
string |
$default: |
default value |
Information Tags:
Throws: | PEAR_PACKAGEFILEMANAGER_RUN_SETOPTIONS |
void|PEAR_Error addDependency(
string
$name, [string
$version = false], [string
$operator = 'ge'], [string
$type = 'pkg']
)
|
|
Add a dependency on another package, or an extension/php
This will overwrite an existing dependency if it is found. In other words, if a dependency on PHP 4.1.0 exists, and addDependency('php', '4.3.0', 'ge', 'php') is called, the existing dependency on PHP 4.1.0 will be overwritten with the new one on PHP 4.3.0
Parameters:
string |
$name: |
Dependency element name |
string |
$version: |
Dependency version |
string |
$operator: |
A specific operator for the version, this can be one of: 'has', 'not', 'lt', 'le', 'eq', 'ne', 'ge', or 'gt' |
string |
$type: |
Dependency type. This can be one of: 'pkg', 'ext', 'php', 'prog', 'os', 'sapi', or 'zend' |
Information Tags:
Throws: | PEAR_PACKAGEFILEMANAGER_RUN_SETOPTIONS |
void addMaintainer(
string
$handle, lead|developer|contributor|helper
$role, string
$name, string
$email
)
|
|
Add a maintainer to the list of maintainers.
Every maintainer must have a valid account at pear.php.net. The first parameter is the account name (for instance, cellog is the handle for Greg Beaver at pear.php.net). Every maintainer has one of four possible roles: - lead: the primary maintainer
- developer: an important developer on the project
- contributor: self-explanatory
- helper: ditto
Finally, specify the name and email of the maintainer
Parameters:
string |
$handle: |
username on pear.php.net of maintainer |
lead|developer|contributor|helper |
$role: |
role of maintainer |
string |
$name: |
full name of maintainer |
string |
$email: |
email address of maintainer |
void addRole(
string
$extension, string
$role
)
|
|
Add an extension/role mapping to the role mapping option
Parameters:
string |
$extension: |
file extension |
string |
$role: |
role |
ALWAYS use this to test output before overwriting your package.xml!!
API Tags:
PEAR_Error raiseError(
mixed
$code, [mixed
$i1 = ''], [mixed
$i2 = '']
)
|
|
Utility function to shorten error generation code
1 function raiseError($code, $i1 = '', $i2 = '')
2 {
3 return PEAR::raiseError('PEAR_PackageFileManager Error: ' .
4 sprintf($GLOBALS['_PEAR_PACKAGEFILEMANAGER_ERRORS'][$this->_options['lang']][$code],
5 $i1, $i2));
6 }
API Tags:
void|PEAR_Error setOptions(
[array
$options = array()]
)
|
|
Set package.xml generation options
The options array is indexed as follows: 1 $options = array('option_name' => <optionvalue>);
The documentation below simplifies this description through the use of option_name without quotes Configuration options: - lang: lang controls the language in which error messages are
displayed. There are currently only English error messages,
but any contributed will be added over time.<br />
Possible values: en (default)
- packagefile: the name of the packagefile, defaults to package.xml
- pathtopackagefile: the path to an existing package file to read in,
if different from the packagedirectory
- packagedirectory: the path to the base directory of the package. For
package PEAR_PackageFileManager, this path is
/path/to/pearcvs/pear/PEAR_PackageFileManager where
/path/to/pearcvs is a local path on your hard drive
- outputdirectory: the path in which to place the generated package.xml
by default, this is ignored, and the package.xml is
created in the packagedirectory
- filelistgenerator: the <filelist> section plugin which will be used.
In this release, there are two generator plugins,
file and cvs. For details, see the docs for these
plugins
- usergeneratordir: For advanced users. If you write your own filelist
generator plugin, use this option to tell
PEAR_PackageFileManager where to find the file that
contains it. If the plugin is named foo, the class
must be named PEAR_PackageFileManager_Foo
no matter where it is located. By default, the Foo
plugin is located in PEAR/PackageFileManager/Foo.php.
If you pass /path/to/foo in this option, setOptions
will look for PEAR_PackageFileManager_Foo in
/path/to/foo/Foo.php
package.xml simple options: - baseinstalldir: The base directory to install this package in. For
package PEAR_PackageFileManager, this is "PEAR", for
package PEAR, this is "/"
- license: The license this release is released under. Default is
PHP License if left unspecified
- notes: Release notes, any text describing what makes this release unique
- changelognotes: notes for the changelog, this should be more detailed than
the release notes. By default, PEAR_PackageFileManager uses
the notes option for the changelog as well
- version: The version number for this release. Remember the convention for
numbering: initial alpha is between 0 and 1, add b<beta number> for
beta as in 1.0b1, the integer portion of the version should specify
backwards compatibility, as in 1.1 is backwards compatible with 1.0,
but 2.0 is not backwards compatible with 1.10. Also note that 1.10
is a greater release version than 1.1 (think of it as "one point ten"
and "one point one"). Bugfix releases should be a third decimal as in
1.0.1, 1.0.2
- package: [optional] Package name. Use this to create a new package.xml, or
overwrite an existing one from another package used as a template
- summary: [optional] Summary of package purpose
- description: [optional] Description of package purpose. Note that the above
three options are not optional when creating a new package.xml
from scratch
package.xml complex options: - roles: this is an array mapping file extension to install role. This
specifies default behavior that can be overridden by the exceptions
option and dir_roles option. use addRole()
to add a new role to the pre-existing array - dir_roles: this is an array mapping directory name to install role. All
files in a directory whose name matches the directory will be
given the install role specified. Single files can be excluded
from this using the exceptions option. The directory should be
a relative path from the baseinstalldir, or "/" for the baseinstalldir
- exceptions: specify file role for specific files. This array maps all files
matching the exact name of a file to a role as in "file.ext" => "role"
- installexceptions: array mapping of specific filenames to baseinstalldir values. Use
this to force the installation of a file into another directory,
such as forcing a script to be in the root scripts directory so that
it will be in the path
- deps: dependency array. Pass in an empty array to clear all dependencies, and use
addDependency() to add new ones/replace existing ones - maintainers: maintainers array. Pass in an empty array to clear all maintainers, and
use addMaintainer()
to add a new maintainer/replace existing maintainer - configure_options: array specifies build options for PECL packages (you should probably
use PECL_Gen instead, but it's here for completeness)
- ignore: an array of filenames, directory names, or wildcard expressions specifying
files to exclude entirely from the package.xml. Wildcards are operating system
wildcards * and ?. file*foo.php will exclude filefoo.php, fileabrfoo.php and
filewho_is_thisfoo.php. file?foo.php will exclude fileafoo.php and will not
exclude fileaafoo.php. test/ will exclude all directories and subdirectories of
ANY directory named test encountered in directory parsing. *test* will exclude
all files and directories that contain test in their name
Parameters:
API Tags:
See: | PEAR_PackageFileManager_Generator_CVS |
See: | PEAR_PackageFileManager_Generator_File |
Information Tags:
Throws: | PEAR_PACKAGEFILEMANAGER_NOBASEDIR |
Throws: | PEAR_PACKAGEFILEMANAGER_GENERATOR_NOTFOUND_ANYWHERE |
Throws: | PEAR_PACKAGEFILEMANAGER_GENERATOR_NOTFOUND |
Throws: | PEAR_PACKAGEFILEMANAGER_NOPKGDIR |
Throws: | PEAR_PACKAGEFILEMANAGER_NOVERSION |
Throws: | PEAR_PACKAGEFILEMANAGER_NOSTATE |
void|PEAR_Error writePackageFile(
[boolean
$debuginterface = null]
)
|
|
Writes the package.xml file out with the newly created <release></release> tag
ALWAYS use debugPackageFile to verify that output is correct before overwriting your package.xml
Parameters:
boolean |
$debuginterface: |
null if no debugging, true if web interface, false if command-line |
Information Tags:
Throws: | PEAR_PACKAGEFILEMANAGER_DEST_UNWRITABLE |
Usedby: | PEAR_PackageFileManager::debugPackageFile() - calls with the debug parameter set based on
whether it is called from the command-line or web interface |
Throws: | PEAR_PACKAGEFILEMANAGER_CANTOPEN_TMPPKGFILE |
Throws: | PEAR_PACKAGEFILEMANAGER_CANTCOPY_PKGFILE |
Throws: | PEAR_PACKAGEFILEMANAGER_ADD_MAINTAINERS |
Throws: | PEAR_PACKAGEFILEMANAGER_CANTWRITE_PKGFILE |
Throws: | PEAR_PACKAGEFILEMANAGER_RUN_SETOPTIONS |
|
|