Docs For Class Pearfarm

Pearfarm_PackageSpec

Description

Pearfarm_PackageSpec is a simplified DSL for creating basic pear pacakges.

Instead of having to learn about the complexities of PEAR you can just specify a few basic facts and Pearfarm will build you a reasonable package.xml.

If you don't already have a pearfarm.spec file for your project, just run "pearfarm init" and an example spec file will be generated for you. Then you need only edit the boilerplate in the pearfarm.spec file and customize it for your needs, using these docs as a reference.

To build a PEAR package based on your pearfarm.spec, run "pear package". Pay careful attention to any errors and warnings you see; pearfarm itself doesn't do much error checking since "pear package" already does a lot.

NOTE: this code was hacked up quickly one weekend and isn't particularly pretty. I was learning PEAR architecture at the same time. My apologies in advance.

NOTE: below are the meta-method docs for stuff done via __call. Phpdoc sucks so they don't show up very well.

object Pearfarm_PackageSpec setName(string $value): Set the package name.
object Pearfarm_PackageSpec setChannel(string $value): Set the channel. If you are deploying via pearfarm, this should be <pearfarm-username>.pearfarm.org.
object Pearfarm_PackageSpec setSummary(string $value): Set the Summary of the pacakge.
object Pearfarm_PackageSpec setDescription(string $value): Set the detailed Description of the package.
object Pearfarm_PackageSpec setReleaseVersion(string $value): Set the release version string.
object Pearfarm_PackageSpec setReleaseStability(string $value): Set the release stability (devel, alpha, beta, stable)
object Pearfarm_PackageSpec setApiVersion(string $value): Set the API version string.
object Pearfarm_PackageSpec setApiStability(string $value): Set the API stability (devel, alpha, beta, stable)
object Pearfarm_PackageSpec setNotes(string $value): Set the notes for the package. Typically you should include a link to your project web site here.

Located in /PackageSpec.php (line 38)

Class Constant Summary

LICENSE_APACHE = 'APACHE'

LICENSE_BSD = 'BSD'

LICENSE_GPL = 'GPL'

LICENSE_GPL3 = 'GPL3'

LICENSE_LGPL = 'LGPL'

LICENSE_LGPL3 = 'LGPL3'

LICENSE_MIT = 'MIT'

LICENSE_PHP = 'PHP'

OPT_BASEDIR = 'basedir'

OPT_DEBUG = 'debug'

PLATFORM_ANY = 'any'

PLATFORM_WIN = 'windows'

ROLE_DATA = 'data'

ROLE_DOC = 'doc'

ROLE_PHP = 'php'

ROLE_SCRIPT = 'script'

ROLE_TEST = 'test'

Variable Summary

mixed $apiStability

mixed $apiVersion

mixed $channel

mixed $dependsOnExtensions

mixed $dependsOnPearInstallerVersionExclude

mixed $dependsOnPearInstallerVersionMax

mixed $dependsOnPearInstallerVersionMin

mixed $dependsOnPearInstallerVersionRecommended

mixed $dependsOnPEARPackages

mixed $dependsOnPHPVersionExclude

mixed $dependsOnPHPVersionMax

mixed $dependsOnPHPVersionMin

mixed $description

mixed $excludeFilesRegexs

mixed $executables

mixed $files

mixed $license

mixed $maintainers

mixed $name

mixed $notes

mixed $options

mixed $releaseStability

mixed $releaseVersion

mixed $summary

Method Summary

static object Pearfarm_PackageSpec create ([array $options = array()])

Pearfarm_PackageSpec __construct ([array $options = array()])

object Pearfarm_PackageSpec addExcludeFiles (mixed $excludeFiles)

object Pearfarm_PackageSpec addExcludeFilesRegex (mixed $regexs)

object Pearfarm_PackageSpec addExecutable (string $scriptFilePath, [string $renameTo = NULL], [string $platform = self::PLATFORM_ANY])

object Pearfarm_PackageSpec addFile (Pearfarm_PackageSpecFile $f)

object Pearfarm_PackageSpec addFilesRegex (mixed $regexs, [string $role = self::ROLE_PHP], [array $options = array()])

object Pearfarm_PackageSpec addFilesSimple (mixed $files, [string $role = self::ROLE_PHP], [array $options = array()])

object Pearfarm_PackageSpec addGitFiles ()

object Pearfarm_PackageSpec addMaintainer (string $type, string $name, string $user, string $email, [ $active = true])

object Pearfarm_PackageSpec addPackageDependency (string $name, string $pkgSpec, [array $options = array()])

object Pearfarm_PackageSpec addSvnFiles ()

object Pearfarm_PackageSpecFile getFile (string $path)

object Pearfarm_PackageSpec setDependsOnPearInstallerVersion (string $min, [string $max = NULL], [string $recommended = NULL], [array $exclude = array()])

object Pearfarm_PackageSpec setDependsOnPHPVersion (string $min, [string $max = NULL], [array $exclude = array()])

object Pearfarm_PackageSpec setLicense (mixed $license, [string $licenseURI = NULL])

void writePackageFile ()

Variables

mixed $apiStability = NULL (line 71)

access: protected

mixed $apiVersion = NULL (line 70)

access: protected

mixed $channel = NULL (line 65)

access: protected

mixed $dependsOnExtensions = array() (line 86)

access: protected

mixed $dependsOnPearInstallerVersionExclude = array() (line 84)

access: protected

mixed $dependsOnPearInstallerVersionMax = NULL (line 82)

access: protected

mixed $dependsOnPearInstallerVersionMin = '1.4.0' (line 81)

access: protected

mixed $dependsOnPearInstallerVersionRecommended = NULL (line 83)

access: protected

mixed $dependsOnPEARPackages = array() (line 87)

access: protected

mixed $dependsOnPHPVersionExclude = array() (line 79)

access: protected

mixed $dependsOnPHPVersionMax = NULL (line 78)

access: protected

mixed $dependsOnPHPVersionMin = '5.0.0' (line 77)

access: protected

mixed $description = NULL (line 67)

access: protected

mixed $excludeFilesRegexs = array() (line 91)

access: protected

mixed $executables = array() (line 92)

access: protected

mixed $files = array() (line 90)

access: protected

mixed $license = NULL (line 72)

access: protected

mixed $maintainers = array() (line 74)

access: protected

mixed $name = NULL (line 64)

access: protected

mixed $notes = NULL (line 73)

access: protected

mixed $options = array() (line 61)

access: protected

mixed $releaseStability = NULL (line 69)

access: protected

mixed $releaseVersion = NULL (line 68)

access: protected

mixed $summary = NULL (line 66)

access: protected

Methods

static create (line 744)

Fluent interface bootstrap static constructor.

return: For fluent interface.
access: public

object Pearfarm_PackageSpec create ([array $options = array()])

array $options: Options hash to be passed to constructor.

Constructor __construct (line 110)

Pearfarm_PackageSpec constructor.

access: public

Pearfarm_PackageSpec __construct ([array $options = array()])

array $options: Options for the Pearfarm_PackageSpec object, see Pearfarm_PackageSpec::OPT_*

addExcludeFiles (line 224)

Add a file path which will cause a file that has been included previously to be excluded from the final package.

return: For fluent interface.
access: public

object Pearfarm_PackageSpec addExcludeFiles (mixed $excludeFiles)

mixed $excludeFiles: A filepath to a file to exclude, must be relative to project root, aka path/to/myfiletoexclude.php

addExcludeFilesRegex (line 208)

Add a regex pattern which will cause a file that has been included previously to be excluded from the final package.

return: For fluent interface.
access: public

object Pearfarm_PackageSpec addExcludeFilesRegex (mixed $regexs)

mixed $regexs: A string regex pattern (must include //) or an array of patterns.

addExecutable (line 407)

Add an "exectuable" file to your package.

The file must have already been added to the package; this function just makes a previously included file be tagged as an executable in your packate so that when installed PEAR will place it in the bin/ directory.

This function is a high-level abstraction to the package.xml format for convenience reasons.

Executables added with this function get two replace-tasks added to them:

'/usr/bin/env php' => pear-installation "php_bin" location
'@php_bin@' => pear-installation "php_bin" location
'@pear_directory@' => pear-installation "php_dir" location

This allows you to write your executable script in a way that makes it easy to run locally and when installed via pear if you write your exectuables so that they have the following shbang line:

#!/usr/bin/env php

Here is example PHP code of making your executable run properly from download and PEAR installs:

if (strpos('@php_bin@', '@php_bin') === 0) { // not a pear install
define('PEARFARM_INCLUDE_PREFIX', dirname(__FILE__));
define('PEARFARM_CMD', 'php pearfarm');
} else {
define('PEARFARM_INCLUDE_PREFIX', 'pearfarm');
define('PEARFARM_CMD', 'pearfarm');
}

Here is example shell script code of making your executable run properly from download and PEAR installs:

PROGRAM_RUN_FROM_DIR=`pwd`
PEAR_INSTALL_DIR="@pear_directory@"
if [ ${PEAR_INSTALL_DIR:0:15} == "@pear_directory" ] ; then
# is not pear install
# we never really expect PROJECT_HOME to be set... we get this info from the path to this executable
# echo "WARNING: PROJECT_HOME environment not set. Attempting to guess."
# try to find myproject
## resolve links - $0 may be a symlink
PRG="$0"
progname=`basename "$0"`
# need this for relative symlinks
dirname_prg=`dirname "$PRG"`
cd "$dirname_prg"
while [ -h "$PRG" ] ; do
ls=`ls -ld "$PRG"`
link=`expr "$ls" : '.*-> $.*$$'`
if expr "$link" : '/.*' > /dev/null; then
PRG="$link"
else
PRG=`dirname "$PRG"`"/$link"
fi
done
cd "$PROGRAM_RUN_FROM_DIR"
PROJECT_HOME=`dirname "$PRG"`/..
# make it fully qualified
PROJECT_HOME=`cd "$PROJECT_HOME" && pwd`
else
# is a pear install
PROJECT_HOME="@pear_directory@/myproject"
fi

return: For fluent interface.
throws: object Exception If the provided file path hasn't already been added to the spec.
access: public

object Pearfarm_PackageSpec addExecutable (string $scriptFilePath, [string $renameTo = NULL], [string $platform = self::PLATFORM_ANY])

string $scriptFilePath: The project-relative path to the executable.
string $renameTo: The name the executable should have once installed. Defaults to the name of the file.
string $platform: One of the Pearfarm_PackageSpec::PLATFORM_* constants specificying which platform this executable runs on.

addFile (line 134)

Add a Pearfarm_PackageSpecFile to the list of files to add to the package.

return: For fluent interface.
access: public

object Pearfarm_PackageSpec addFile (Pearfarm_PackageSpecFile $f)

object Pearfarm_PackageSpecFile $f

addFilesRegex (line 170)

Add files to the PEAR package based on regex filter of file paths.

return: For fluent interface.
access: public

object Pearfarm_PackageSpec addFilesRegex (mixed $regexs, [string $role = self::ROLE_PHP], [array $options = array()])

mixed $regexs: A string regex pattern (must include //) or an array of patterns.
string $role: The "role" of the file for PEAR's benefit; one of Pearfarm_PackageSpec::ROLE_*
array $options: An array of options to pass to new Pearfarm_PackageSpecFile().

addFilesSimple (line 150)

Add a file or files to the package based on simple paths.

Paths should be relative to project root, ie: path/to/myfile.php.

return: For fluent interface.
access: public

object Pearfarm_PackageSpec addFilesSimple (mixed $files, [string $role = self::ROLE_PHP], [array $options = array()])

mixed $files: A string filename, or an array of filenames
string $role: The "role" of the file for PEAR's benefit; one of Pearfarm_PackageSpec::ROLE_*
array $options: An array of options to pass to new Pearfarm_PackageSpecFile()

addGitFiles (line 242)

Add all files that git knows about to the package.

return: For fluent interface.
throws:
access: public

object Pearfarm_PackageSpec addGitFiles ()

addMaintainer (line 289)

Add a maintainer.

return: For fluent interface.
access: public

object Pearfarm_PackageSpec addMaintainer (string $type, string $name, string $user, string $email, [ $active = true])

string $type: Type
string $name: Name
string $user: Username (I think this is the "PEAR" username, meaning it's n/a for pearfarm)
string $email: Email address
$active

addPackageDependency (line 437)

Add a package dependency.

If your package depends on another pear package, this is how to manifest it.

return: For fluent interface.
access: public

object Pearfarm_PackageSpec addPackageDependency (string $name, string $pkgSpec, [array $options = array()])

string $name: The name of the dependency
string $pkgSpec: Either a channel name, or a URI.
array $options: Options hash. Pass any of required (bool), name, channel, uri, min, max, recommended, recommendedMin, recommendedMax, exclude (array of version strings), conflict (bool).

addSvnFiles (line 260)

Add all files that svn knows about to the package.

return: For fluent interface.
throws:
access: public

object Pearfarm_PackageSpec addSvnFiles ()

getFile (line 193)

Get the object Pearfarm_PackageSpecFile for the given path.

return: NULL if not found.
access: public

object Pearfarm_PackageSpecFile getFile (string $path)

string $path: The path (relative to the project root, ie a/b/c.php)

setDependsOnPearInstallerVersion (line 321)

Set the PEAR installer version dependency info.

return: For fluent interface.
access: public

object Pearfarm_PackageSpec setDependsOnPearInstallerVersion (string $min, [string $max = NULL], [string $recommended = NULL], [array $exclude = array()])

string $min: Minimum version.
string $max: Maximum version.
string $recommended: Recommended version.
array $exclude: An array of strings of exact versions that the package is *not* compatible with.

setDependsOnPHPVersion (line 303)

Set the php version dependency info.

return: For fluent interface.
access: public

object Pearfarm_PackageSpec setDependsOnPHPVersion (string $min, [string $max = NULL], [array $exclude = array()])

string $min: Minimum version.
string $max: Maximum version.
array $exclude: An array of strings of exact versions that the package is *not* compatible with.

setLicense (line 485)

Set the license for the package.

There are three forms:

setLicense(Pearfarm_PackageSpec::LICENSE_MIT)
setLicense(array('name' => 'MIT', 'uri' => 'http://www.opensource.org/licenses/mit-license.php'))
setLicense('MIT', 'http://www.opensource.org/licenses/mit-license.php')

return: For fluent interface.
access: public

object Pearfarm_PackageSpec setLicense (mixed $license, [string $licenseURI = NULL])

mixed $license: Form #1: string, one of the Pearfarm_PackageSpec::LICENSE_* constants. Form #2: array, in form array('name' => 'MIT', 'url' => 'http://www.opensource.org/licenses/mit-license.php') Form #3: string, Name of license
string $licenseURI: Used only with Form #3, URI of license.

writePackageFile (line 561)

Outputs the package.xml file to the location speficied in self::OPT_BASEDIR

access: public

void writePackageFile ()

Class Constants

LICENSE_APACHE = 'APACHE' (line 47)

LICENSE_BSD = 'BSD' (line 41)

LICENSE_GPL = 'GPL' (line 43)

LICENSE_GPL3 = 'GPL3' (line 45)

LICENSE_LGPL = 'LGPL' (line 44)

LICENSE_LGPL3 = 'LGPL3' (line 46)

LICENSE_MIT = 'MIT' (line 40)

LICENSE_PHP = 'PHP' (line 42)

OPT_BASEDIR = 'basedir' (line 58)

OPT_DEBUG = 'debug' (line 59)

PLATFORM_ANY = 'any' (line 55)

PLATFORM_WIN = 'windows' (line 56)

ROLE_DATA = 'data' (line 53)

ROLE_DOC = 'doc' (line 51)

ROLE_PHP = 'php' (line 49)

ROLE_SCRIPT = 'script' (line 50)

ROLE_TEST = 'test' (line 52)

Documentation generated on Tue, 12 Jan 2010 21:04:29 -0500 by phpDocumentor 1.4.3