Docs For Class PEAR_PackageFileManager2

[line 199]
PEAR_PackageFileManager2, like PEAR_PackageFileManager, is designed to create and manipulate package.xml version 2.0.

The PEAR_PackageFileManager2 class can work directly with PEAR_PackageFileManager to create parallel package.xml files, version 1.0 and 2.0, that represent the same project, but take advantage of package.xml 2.0-specific features.

Like PEAR_PackageFileManager, The PEAR_PackageFileManager2 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.

Example usage is similar to PEAR_PackageFileManager:

 <?php

 require_once('PEAR/PackageFileManager2.php');
 PEAR::setErrorHandling(PEAR_ERROR_DIE);
 //require_once 'PEAR/Config.php';
 //PEAR_Config::singleton('/path/to/unusualpearconfig.ini');
 // use the above lines if the channel information is not validating
 $pfm = new PEAR_PackageFileManager2;
 // for an existing package.xml use
 // $pfm = <a href="../PEAR_PackageFileManager2/PEAR_PackageFileManager2.html#methodimportOptions">importOptions()</a> instead
 $e = $pfm->setOptions(
 array('baseinstalldir' => 'PhpDocumentor',
  'packagedirectory' => 'C:/Web Pages/chiara/phpdoc2/',
  'filelistgenerator' => 'cvs', // generate from cvs, use file for directory
  'ignore' => array('TODO', 'tests/'), // ignore TODO, all files in tests/
  'installexceptions' => array('phpdoc' => '/*'), // baseinstalldir ="/" for phpdoc
  'dir_roles' => array('tutorials' => 'doc'),
  'exceptions' => array('README' => 'doc', // README would be data, now is doc
                        'PHPLICENSE.txt' => 'doc'))); // same for the license
 $pfm->setPackage('MyPackage');
 $pfm->setSummary('this is my package');
 $pfm->setDescription('this is my package description');
 $pfm->setChannel('mychannel.example.com');
 $pfm->setAPIVersion('1.0.0');
 $pfm->setReleaseVersion('1.2.1');
 $pfm->setReleaseStability('stable');
 $pfm->setAPIStability('stable');
 $pfm->setNotes("We've implemented many new and exciting features");
 $pfm->setPackageType('php'); // this is a PEAR-style php script package
 $pfm->addRelease(); // set up a release section
 $pfm->setOSInstallCondition('windows');
 $pfm->addInstallAs('pear-phpdoc.bat', 'phpdoc.bat');
 $pfm->addIgnoreToRelease('pear-phpdoc');
 $pfm->addRelease(); // add another release section for all other OSes
 $pfm->addInstallAs('pear-phpdoc', 'phpdoc');
 $pfm->addIgnoreToRelease('pear-phpdoc.bat');
 $pfm->addRole('pkg', 'doc'); // add a new role mapping
 $pfm->setPhpDep('4.2.0');
 $pfm->setPearinstallerDep('1.4.0a12');
 $pfm->addMaintainer('lead', 'cellog', 'Greg Beaver', 'cellog@php.net');
 $pfm->setLicense('PHP License', 'http://www.php.net/license');
 $pfm->generateContents(); // create the <contents> tag
 // replace @PHP-BIN@ in this file with the path to php executable!  pretty neat
 $test->addReplacement('pear-phpdoc', 'pear-config', '@PHP-BIN@', 'php_bin');
 $test->addReplacement('pear-phpdoc.bat', 'pear-config', '@PHP-BIN@', 'php_bin');
 $pkg = &$pfm->exportCompatiblePackageFile1(); // get a PEAR_PackageFile object
 // note use of <a href="../PEAR_PackageFileManager2/PEAR_PackageFileManager2.html#methoddebugPackageFile">debugPackageFile()</a> - this is VERY important
 if (isset($_GET['make']) || (isset($_SERVER['argv']) && @$_SERVER['argv'][1] == 'make')) {
     $pkg->writePackageFile();
     $pfm->writePackageFile();
 } else {
     $pkg->debugPackageFile();
     $pfm->debugPackageFile();
 }
 ?>

In addition, a package.xml file can now be generated from scratch, with the usage of new options package, summary, description, and the use of the addLead(), addDeveloper(), addContributor(), addHelper() methods

Author: Greg Beaver <cellog@php.net>
Version: Release: 1.0.2
Copyright: 2005-2009 The PEAR Group
Link: http://pear.php.net/package/PEAR_PackageFileManager2
Since: Class available since Release 1.0.0alpha1
License: New

PEAR_PackageFileManager2 (Constructor) [line 315]

PEAR_PackageFileManager2 PEAR_PackageFileManager2(
)

Does nothing, use factory

The constructor is not used in order to be able to return a PEAR_Error from setOptions

See: PEAR_PackageFileManager2::setOptions()
Since: 1.0.0a1
Access: public

[ Top ]

addGlobalReplacement [line 824]

void|PEAR_Error addGlobalReplacement(
string
$type, string
$from, string
$to)

Add a replacement option for all files

This sets an install-time complex search-and-replace function allowing the setting of platform-specific variables in all installed files.

if $type is php-const, then $to must be the name of a PHP Constant. If $type is pear-config, then $to must be the name of a PEAR config variable accessible through a PEAR_Config::get() method. If type is package-info, then $to must be the name of a section from the package.xml file used to install this file.

Throws: PEAR_PACKAGEFILEMANAGER2_INVALID_REPLACETYPE
Since: 1.0.0a1
Access: public

Parameters:

string	`$type`	—	variable type, either php-const, pear-config or package-info
string	`$from`	—	text to replace in the source file
string	`$to`	—	variable name to use for replacement

[ Top ]

addIgnore [line 382]

void addIgnore(
string|array
$ignore, [bool
$clear = false])

Add a pattern or patterns to ignore when generating the file list

Since: 1.6.0a2
Access: public

Parameters:

string\|array	`$ignore`	—	file pattern to ignore
bool	`$clear`	—	(optional) if true, the include array will be reset (useful for cloned packagefiles)

[ Top ]

addIgnoreToRelease [line 366]

void addIgnoreToRelease(
string
$path)

Add an <ignore> tag to a <phprelease> tag

See: PEAR_PackageFile_v2_rw::addIgnore()
Since: 1.6.0a3
Access: public

Parameters:

string $path — full path to filename to ignore

[ Top ]

addInclude [line 339]

void addInclude(
string|array
$include, [bool
$clear = false])

Add a pattern to include when generating the file list.

If any include options are specified, all files that do not match the inclusion patterns will be ignored

Note that to match partial path entries, you must start with a *, so to match "data/README" you need to use "*data/README"

Since: 1.6.0a2
Access: public

Parameters:

string\|array	`$include`	—	file pattern to include
bool	`$clear`	—	(optional) if true, the include array will be reset (useful for cloned packagefiles)

[ Top ]

addPostinstallTask [line 966]

void|PEAR_Error addPostinstallTask(
object
$task, string
$path)

Add post-installation script task to a post-install script.

The script must have been created with initPostinstallScript() and then populated using the API of PEAR_Task_Postinstallscript_rw.

Throws: PEAR_PACKAGEFILEMANAGER2_INVALID_POSTINSTALLSCRIPT
Since: 1.0.0a1
Access: public

Parameters:

object	`$task`	—	PEAR_Task_Postinstallscript_rw
string	`$path`	—	relative path of file (relative to packagedirectory option)

[ Top ]

addReplacement [line 866]

void|PEAR_Error addReplacement(
string
$path, string
$type, string
$from, string
$to)

Add a replacement option for a file, or files matching the glob pattern

This sets an install-time complex search-and-replace function allowing the setting of platform-specific variables in an installed file.

Throws: PEAR_PACKAGEFILEMANAGER2_INVALID_REPLACETYPE
Since: 1.0.0a1
Access: public

Parameters:

string	`$path`	—	relative path of file (relative to packagedirectory option) glob patterns are allowed (eg. {Dir1,Dir2}/*.php)
string	`$type`	—	variable type, either php-const, pear-config or package-info
string	`$from`	—	text to replace in the source file
string	`$to`	—	variable name to use for replacement

[ Top ]

addRole [line 792]

void|PEAR_Error addRole(
string
$extension, string
$role)

Add an extension/role mapping to the role mapping option

Roles influence both where a file is installed and how it is installed. Files with role="data" are in a completely different directory hierarchy from the program files of role="php"

In PEAR 1.3b2, these roles are

php (most common)
data
doc
test
script (gives the file an executable attribute)
src

Throws: PEAR_PACKAGEFILEMANAGER2_INVALID_ROLE
Since: 1.0.0a1
Access: public

Parameters:

string	`$extension`	—	file extension
string	`$role`	—	file role

[ Top ]

addUnixEol [line 923]

void addUnixEol(
string
$path)

Convert a file to unix line endings on installation

Since: 1.0.0a1
Access: public

Parameters:

string $path — relative path of file (relative to packagedirectory option)

[ Top ]

addWindowsEol [line 902]

void addWindowsEol(
string
$path)

Convert a file to windows line endings on installation

Since: 1.0.0a1
Access: public

Parameters:

string $path — relative path of file (relative to packagedirectory option)

[ Top ]

debugPackageFile [line 1145]

true|PEAR_Error debugPackageFile(
)

ALWAYS use this to test output before overwriting your package.xml!!

This method instructs writePackageFile() to simply print the package.xml to output, either command-line or web-friendly (this is automatic based on the existence of $_SERVER['PATH_TRANSLATED']

Since: 1.0.0a1
Access: public
Uses: PEAR_PackageFileManager2::writePackageFile() - calls with the debug parameter set based on whether it is called from the command-line or web interface

[ Top ]

detectDependencies [line 999]

void|PEAR_Error detectDependencies(
[array
$options = array()])

Uses PEAR::PHP_CompatInfo package to detect dependencies (extensions, php version)

Since: 1.0.0a1
Throws: PEAR_PACKAGEFILEMANAGER2_RUN_SETOPTIONS
Throws: PEAR_PACKAGEFILEMANAGER2_NO_PHPCOMPATINFO
Access: public

Parameters:

array $options — (optional) parser options for PHP_CompatInfo

[ Top ]

getOptions [line 759]

array getOptions(
[bool
$withTasks = false])

Get the existing options

Since: 1.0.0a1
Access: public

Parameters:

bool $withTasks — (optional) Returns full options (=false) or without replacements (=true)

[ Top ]

getWarnings [line 1174]

array getWarnings(
)

Retrieve the list of warnings

Since: 1.0.0a1
Access: public

[ Top ]

importFromPackageFile1 [line 666]

PEAR_PackageFileManager2|PEAR_Error &importFromPackageFile1(
string
$packagefile, [array
$options = array()])

Convert a package xml 1.0 to 2.0 with user and default options

Since: 1.0.0a1
Access: public

Parameters:

string	`$packagefile`	—	name of package file
array	`$options`	—	(optional) list of generation options

[ Top ]

importOptions [line 694]

PEAR_PackageFileManager2|PEAR_Error &importOptions(
string
$packagefile, [array
$options = array()])

Import options from an existing package.xml

Since: 1.0.0a1
Access: public

Parameters:

string	`$packagefile`	—	name of package file
array	`$options`	—	(optional) list of generation options

[ Top ]

initPostinstallScript [line 944]

PEAR_Task_Postinstallscript_rw &initPostinstallScript(
string
$path)

Get a post-installation task object for manipulation prior to adding it

Since: 1.0.0a1
Access: public

Parameters:

string $path — relative path of file (relative to packagedirectory option)

[ Top ]

isIncludeable [line 1021]

boolean isIncludeable(
string
$file)

Returns whether or not a file is in the include path.

Return: true if the file is in the include path, false otherwise
Since: 1.0.0a1
Access: public

Parameters:

string $file — path to filename

[ Top ]

pushWarning [line 1161]

void pushWarning(
integer
$code, array
$info)

Store a warning on the warning stack

Since: 1.0.0a1
Access: public

Parameters:

integer	`$code`	—	error code
array	`$info`	—	additional specific error info

[ Top ]

raiseError [line 1214]

PEAR_Error raiseError(
integer
$code, [string
$i1 = ''], [string
$i2 = ''])

Utility function to shorten error generation code

function raiseError($code, $i1 = '', $i2 = '')

    {
        return PEAR::raiseError('PEAR_PackageFileManager2 Error: ' .
                    sprintf($GLOBALS['_PEAR_PACKAGEFILEMANAGER2_ERRORS'][$this->_options['lang']][$code],
                    $i1, $i2), $code);
    }

Since: 1.0.0a1
Access: public

Parameters:

integer	`$code`	—	error code
string	`$i1`	—	(optional) additional specific error info #1
string	`$i2`	—	(optional) additional specific error info #2

[ Top ]

setOld [line 1585]

void setOld(
)

Since: 1.0.0a1

[ Top ]

setOptions [line 500]

void|PEAR_Error setOptions(
[array
$options = array()], [boolean
$internal = false])

Set package.xml generation options

The options array is indexed as follows:

 $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.
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
changelogoldtonew: True if the ChangeLog should list from oldest entry to newest. Set to false if you would like new entries first
simpleoutput: True if the package.xml should be human-readable
clearchangelog: True if change log should not be generated/updated
addhiddenfiles: True if you wish to add hidden files/directories that begin with . like .bashrc. This is only used by the File generator. The CVS generator will use all files in CVS regardless of format

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 "/"
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

WARNING: all complex options that require a file path are case-sensitive

package.xml complex options:

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
include: an array of filenames, directory names, or wildcard expressions specifying files to include in the listing. All other files will be ignored. Wildcards are in the same format as ignore
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"
globalreplacements: a list of replacements that should be performed on every single file. The format is the same as replacements
globalreplaceexceptions: a list of exact filenames that should not have global replacements performed (useful for images and large files) note that this is not exported to package.xml 1.0!!

See: PEAR_PackageFileManager_File
See: PEAR_PackageFileManager_CVS
Throws: PEAR_PACKAGEFILEMANAGER2_PKGDIR_NOTREAL
Since: 1.0.0a1
Throws: PEAR_PACKAGEFILEMANAGER2_PATHTOPKGDIR_NOTREAL
Throws: PEAR_PACKAGEFILEMANAGER2_NOPKGDIR
Throws: PEAR_PACKAGEFILEMANAGER2_OUTPUTDIR_NOTREAL
Throws: PEAR_PACKAGEFILEMANAGER2_GENERATOR_NOTFOUND
Throws: PEAR_PACKAGEFILEMANAGER2_GENERATOR_NOTFOUND_ANYWHERE
Throws: PEAR_PACKAGEFILEMANAGER2_NOBASEDIR
Access: public

Parameters:

array	`$options`	—	(optional) list of generation options
boolean	`$internal`	—	(optional) private function call

[ Top ]

specifySubpackage [line 622]

void|false specifySubpackage(
object
&$pm, [boolean
$dependency = null], [boolean
$required = false])

Define a link between a subpackage and the parent package

In many cases, a subpackage is developed in the same directory as the parent package, and the files should be excluded from the package.xml version 2.0.

Since: 1.0.0a1
Access: public

Parameters:

object	`&$pm`	—	PEAR_PackageFileManager2 object representing the subpackage's package.xml
boolean	`$dependency`	—	dependency type to add, use true for a package dependency, false for a subpackage dependency
boolean	`$required`	—	(optional) whether the dependency should be required or optional

[ Top ]

writePackageFile [line 1049]

true|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

Throws: PEAR_PACKAGEFILEMANAGER2_INVALID_PACKAGE
Since: 1.0.0a1
Throws: PEAR_PACKAGEFILEMANAGER2_DEST_UNWRITABLE
Throws: PEAR_PACKAGEFILEMANAGER2_CANTWRITE_PKGFILE
Throws: PEAR_PACKAGEFILEMANAGER2_CANTCOPY_PKGFILE
Throws: PEAR_PACKAGEFILEMANAGER2_CANTOPEN_TMPPKGFILE
Access: public
Usedby: PEAR_PackageFileManager2::debugPackageFile() - calls with the debug parameter set based on whether it is called from the command-line or web interface

Parameters:

boolean $debuginterface — null if no debugging, true if web interface, false if command-line

[ Top ]

Class: PEAR_PackageFileManager2

Class Overview

Author(s):

Version:

Copyright:

Methods

Inherited Variables

Inherited Methods

Class Details

Method Detail

PEAR_PackageFileManager2 (Constructor) [line 315]

addGlobalReplacement [line 824]

Parameters:

addIgnore [line 382]

Parameters:

addIgnoreToRelease [line 366]

Parameters:

addInclude [line 339]

Parameters:

addPostinstallTask [line 966]

Parameters:

addReplacement [line 866]

Parameters:

addRole [line 792]

Parameters:

addUnixEol [line 923]

Parameters:

addWindowsEol [line 902]

Parameters:

debugPackageFile [line 1145]

detectDependencies [line 999]

Parameters:

getOptions [line 759]

Parameters:

getWarnings [line 1174]

importFromPackageFile1 [line 666]

Parameters:

importOptions [line 694]

Parameters:

initPostinstallScript [line 944]

Parameters:

isIncludeable [line 1021]

Parameters:

pushWarning [line 1161]

Parameters:

raiseError [line 1214]

Parameters:

setOld [line 1585]

setOptions [line 500]

Parameters:

specifySubpackage [line 622]

Parameters:

writePackageFile [line 1049]

Parameters: