| Current File : /home/k/a/r/karenpetzb/www/items/category/Console.tar |
Getopt.php 0000604 00000075005 15071177310 0006524 0 ustar 00 <?php
/**
* Zend_Console_Getopt is a class to parse options for command-line
* applications.
*
* LICENSE
*
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* http://framework.zend.com/license/new-bsd
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to license@zend.com so we can send you a copy immediately.
*
* @category Zend
* @package Zend_Console_Getopt
* @copyright Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
* @version $Id: $
*/
/**
* @see Zend_Console_Getopt_Exception
*/
require_once 'Zend/Console/Getopt/Exception.php';
/**
* Zend_Console_Getopt is a class to parse options for command-line
* applications.
*
* Terminology:
* Argument: an element of the argv array. This may be part of an option,
* or it may be a non-option command-line argument.
* Flag: the letter or word set off by a '-' or '--'. Example: in '--output filename',
* '--output' is the flag.
* Parameter: the additional argument that is associated with the option.
* Example: in '--output filename', the 'filename' is the parameter.
* Option: the combination of a flag and its parameter, if any.
* Example: in '--output filename', the whole thing is the option.
*
* The following features are supported:
*
* - Short flags like '-a'. Short flags are preceded by a single
* dash. Short flags may be clustered e.g. '-abc', which is the
* same as '-a' '-b' '-c'.
* - Long flags like '--verbose'. Long flags are preceded by a
* double dash. Long flags may not be clustered.
* - Options may have a parameter, e.g. '--output filename'.
* - Parameters for long flags may also be set off with an equals sign,
* e.g. '--output=filename'.
* - Parameters for long flags may be checked as string, word, or integer.
* - Automatic generation of a helpful usage message.
* - Signal end of options with '--'; subsequent arguments are treated
* as non-option arguments, even if they begin with '-'.
* - Raise exception Zend_Console_Getopt_Exception in several cases
* when invalid flags or parameters are given. Usage message is
* returned in the exception object.
*
* The format for specifying options uses a PHP associative array.
* The key is has the format of a list of pipe-separated flag names,
* followed by an optional '=' to indicate a required parameter or
* '-' to indicate an optional parameter. Following that, the type
* of parameter may be specified as 's' for string, 'w' for word,
* or 'i' for integer.
*
* Examples:
* - 'user|username|u=s' this means '--user' or '--username' or '-u'
* are synonyms, and the option requires a string parameter.
* - 'p=i' this means '-p' requires an integer parameter. No synonyms.
* - 'verbose|v-i' this means '--verbose' or '-v' are synonyms, and
* they take an optional integer parameter.
* - 'help|h' this means '--help' or '-h' are synonyms, and
* they take no parameter.
*
* The values in the associative array are strings that are used as
* brief descriptions of the options when printing a usage message.
*
* The simpler format for specifying options used by PHP's getopt()
* function is also supported. This is similar to GNU getopt and shell
* getopt format.
*
* Example: 'abc:' means options '-a', '-b', and '-c'
* are legal, and the latter requires a string parameter.
*
* @category Zend
* @package Zend_Console_Getopt
* @copyright Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
* @version Release: @package_version@
* @since Class available since Release 0.6.0
*
* @todo Handle params with multiple values, e.g. --colors=red,green,blue
* Set value of parameter to the array of values. Allow user to specify
* the separator with Zend_Console_Getopt::CONFIG_PARAMETER_SEPARATOR.
* If this config value is null or empty string, do not split values
* into arrays. Default separator is comma (',').
*
* @todo Handle params with multiple values specified with separate options
* e.g. --colors red --colors green --colors blue should give one
* option with an array(red, green, blue).
* Enable with Zend_Console_Getopt::CONFIG_CUMULATIVE_PARAMETERS.
* Default is that subsequent options overwrite the parameter value.
*
* @todo Handle flags occurring multiple times, e.g. -v -v -v
* Set value of the option's parameter to the integer count of instances
* instead of a boolean.
* Enable with Zend_Console_Getopt::CONFIG_CUMULATIVE_FLAGS.
* Default is that the value is simply boolean true regardless of
* how many instances of the flag appear.
*
* @todo Handle flags that implicitly print usage message, e.g. --help
*
* @todo Handle freeform options, e.g. --set-variable
* Enable with Zend_Console_Getopt::CONFIG_FREEFORM_FLAGS
* All flag-like syntax is recognized, no flag generates an exception.
*
* @todo Handle numeric options, e.g. -1, -2, -3, -1000
* Enable with Zend_Console_Getopt::CONFIG_NUMERIC_FLAGS
* The rule must specify a named flag and the '#' symbol as the
* parameter type. e.g., 'lines=#'
*
* @todo Enable user to specify header and footer content in the help message.
*
* @todo Feature request to handle option interdependencies.
* e.g. if -b is specified, -a must be specified or else the
* usage is invalid.
*
* @todo Feature request to implement callbacks.
* e.g. if -a is specified, run function 'handleOptionA'().
*/
class Zend_Console_Getopt
{
/**
* The options for a given application can be in multiple formats.
* modeGnu is for traditional 'ab:c:' style getopt format.
* modeZend is for a more structured format.
*/
const MODE_ZEND = 'zend';
const MODE_GNU = 'gnu';
/**
* Constant tokens for various symbols used in the mode_zend
* rule format.
*/
const PARAM_REQUIRED = '=';
const PARAM_OPTIONAL = '-';
const TYPE_STRING = 's';
const TYPE_WORD = 'w';
const TYPE_INTEGER = 'i';
/**
* These are constants for optional behavior of this class.
* ruleMode is either 'zend' or 'gnu' or a user-defined mode.
* dashDash is true if '--' signifies the end of command-line options.
* ignoreCase is true if '--opt' and '--OPT' are implicitly synonyms.
*/
const CONFIG_RULEMODE = 'ruleMode';
const CONFIG_DASHDASH = 'dashDash';
const CONFIG_IGNORECASE = 'ignoreCase';
/**
* Defaults for getopt configuration are:
* ruleMode is 'zend' format,
* dashDash (--) token is enabled,
* ignoreCase is not enabled.
*
* @var array Config
*/
protected $_getoptConfig = array(
self::CONFIG_RULEMODE => self::MODE_ZEND,
self::CONFIG_DASHDASH => true,
self::CONFIG_IGNORECASE => false
);
/**
* Stores the command-line arguments for the calling applicaion.
*
* @var array
*/
protected $_argv = array();
/**
* Stores the name of the calling applicaion.
*
* @var string
*/
protected $_progname = '';
/**
* Stores the list of legal options for this application.
*
* @var array
*/
protected $_rules = array();
/**
* Stores alternate spellings of legal options.
*
* @var array
*/
protected $_ruleMap = array();
/**
* Stores options given by the user in the current invocation
* of the application, as well as parameters given in options.
*
* @var array
*/
protected $_options = array();
/**
* Stores the command-line arguments other than options.
*
* @var array
*/
protected $_remainingArgs = array();
/**
* State of the options: parsed or not yet parsed?
*
* @var boolean
*/
protected $_parsed = false;
/**
* The constructor takes one to three parameters.
*
* The first parameter is $rules, which may be a string for
* gnu-style format, or a structured array for Zend-style format.
*
* The second parameter is $argv, and it is optional. If not
* specified, $argv is inferred from the global argv.
*
* The third parameter is an array of configuration parameters
* to control the behavior of this instance of Getopt; it is optional.
*
* @param array $rules
* @param array $argv
* @param array $getoptConfig
* @return void
*/
public function __construct($rules, $argv = null, $getoptConfig = array())
{
$this->_progname = $_SERVER['argv'][0];
$this->setOptions($getoptConfig);
$this->addRules($rules);
if (!is_array($argv)) {
$argv = array_slice($_SERVER['argv'], 1);
}
if (isset($argv)) {
$this->addArguments((array)$argv);
}
}
/**
* Return the state of the option seen on the command line of the
* current application invocation. This function returns true, or the
* parameter to the option, if any. If the option was not given,
* this function returns null.
*
* The magic __get method works in the context of naming the option
* as a virtual member of this class.
*
* @param string $key
* @return string
*/
public function __get($key)
{
return $this->getOption($key);
}
/**
* Test whether a given option has been seen.
*
* @param string $key
* @return boolean
*/
public function __isset($key)
{
$this->parse();
if (isset($this->_ruleMap[$key])) {
$key = $this->_ruleMap[$key];
return isset($this->_options[$key]);
}
return false;
}
/**
* Set the value for a given option.
*
* @param string $key
* @param string $value
* @return void
*/
public function __set($key, $value)
{
$this->parse();
if (isset($this->_ruleMap[$key])) {
$key = $this->_ruleMap[$key];
$this->_options[$key] = $value;
}
}
/**
* Return the current set of options and parameters seen as a string.
*
* @return string
*/
public function __toString()
{
return $this->toString();
}
/**
* Unset an option.
*
* @param string $key
* @return void
*/
public function __unset($key)
{
$this->parse();
if (isset($this->_ruleMap[$key])) {
$key = $this->_ruleMap[$key];
unset($this->_options[$key]);
}
}
/**
* Define additional command-line arguments.
* These are appended to those defined when the constructor was called.
*
* @param array $argv
* @return Zend_Console_Getopt Provides a fluent interface
*/
public function addArguments($argv)
{
$this->_argv = array_merge($this->_argv, $argv);
$this->_parsed = false;
return $this;
}
/**
* Define full set of command-line arguments.
* These replace any currently defined.
*
* @param array $argv
* @return Zend_Console_Getopt Provides a fluent interface
*/
public function setArguments($argv)
{
$this->_argv = $argv;
$this->_parsed = false;
return $this;
}
/**
* Define multiple configuration options from an associative array.
* These are not program options, but properties to configure
* the behavior of Zend_Console_Getopt.
*
* @param array $getoptConfig
* @return Zend_Console_Getopt Provides a fluent interface
*/
public function setOptions($getoptConfig)
{
if (isset($getoptConfig)) {
foreach ($getoptConfig as $key => $value) {
$this->setOption($key, $value);
}
}
return $this;
}
/**
* Define one configuration option as a key/value pair.
* These are not program options, but properties to configure
* the behavior of Zend_Console_Getopt.
*
* @param string $configKey
* @param string $configValue
* @return Zend_Console_Getopt Provides a fluent interface
*/
public function setOption($configKey, $configValue)
{
if ($configKey !== null) {
$this->_getoptConfig[$configKey] = $configValue;
}
return $this;
}
/**
* Define additional option rules.
* These are appended to the rules defined when the constructor was called.
*
* @param array $rules
* @return Zend_Console_Getopt Provides a fluent interface
*/
public function addRules($rules)
{
$ruleMode = $this->_getoptConfig['ruleMode'];
switch ($this->_getoptConfig['ruleMode']) {
case self::MODE_ZEND:
if (is_array($rules)) {
$this->_addRulesModeZend($rules);
break;
}
// intentional fallthrough
case self::MODE_GNU:
$this->_addRulesModeGnu($rules);
break;
default:
/**
* Call addRulesModeFoo() for ruleMode 'foo'.
* The developer should subclass Getopt and
* provide this method.
*/
$method = '_addRulesMode' . ucfirst($ruleMode);
$this->$method($rules);
}
$this->_parsed = false;
return $this;
}
/**
* Return the current set of options and parameters seen as a string.
*
* @return string
*/
public function toString()
{
$this->parse();
$s = array();
foreach ($this->_options as $flag => $value) {
$s[] = $flag . '=' . ($value === true ? 'true' : $value);
}
return implode(' ', $s);
}
/**
* Return the current set of options and parameters seen
* as an array of canonical options and parameters.
*
* Clusters have been expanded, and option aliases
* have been mapped to their primary option names.
*
* @return array
*/
public function toArray()
{
$this->parse();
$s = array();
foreach ($this->_options as $flag => $value) {
$s[] = $flag;
if ($value !== true) {
$s[] = $value;
}
}
return $s;
}
/**
* Return the current set of options and parameters seen in Json format.
*
* @return string
*/
public function toJson()
{
$this->parse();
$j = array();
foreach ($this->_options as $flag => $value) {
$j['options'][] = array(
'option' => array(
'flag' => $flag,
'parameter' => $value
)
);
}
/**
* @see Zend_Json
*/
require_once 'Zend/Json.php';
$json = Zend_Json::encode($j);
return $json;
}
/**
* Return the current set of options and parameters seen in XML format.
*
* @return string
*/
public function toXml()
{
$this->parse();
$doc = new DomDocument('1.0', 'utf-8');
$optionsNode = $doc->createElement('options');
$doc->appendChild($optionsNode);
foreach ($this->_options as $flag => $value) {
$optionNode = $doc->createElement('option');
$optionNode->setAttribute('flag', utf8_encode($flag));
if ($value !== true) {
$optionNode->setAttribute('parameter', utf8_encode($value));
}
$optionsNode->appendChild($optionNode);
}
$xml = $doc->saveXML();
return $xml;
}
/**
* Return a list of options that have been seen in the current argv.
*
* @return array
*/
public function getOptions()
{
$this->parse();
return array_keys($this->_options);
}
/**
* Return the state of the option seen on the command line of the
* current application invocation.
*
* This function returns true, or the parameter value to the option, if any.
* If the option was not given, this function returns false.
*
* @param string $flag
* @return mixed
*/
public function getOption($flag)
{
$this->parse();
if ($this->_getoptConfig[self::CONFIG_IGNORECASE]) {
$flag = strtolower($flag);
}
if (isset($this->_ruleMap[$flag])) {
$flag = $this->_ruleMap[$flag];
if (isset($this->_options[$flag])) {
return $this->_options[$flag];
}
}
return null;
}
/**
* Return the arguments from the command-line following all options found.
*
* @return array
*/
public function getRemainingArgs()
{
$this->parse();
return $this->_remainingArgs;
}
/**
* Return a useful option reference, formatted for display in an
* error message.
*
* Note that this usage information is provided in most Exceptions
* generated by this class.
*
* @return string
*/
public function getUsageMessage()
{
$usage = "Usage: {$this->_progname} [ options ]\n";
$maxLen = 20;
foreach ($this->_rules as $rule) {
$flags = array();
if (is_array($rule['alias'])) {
foreach ($rule['alias'] as $flag) {
$flags[] = (strlen($flag) == 1 ? '-' : '--') . $flag;
}
}
$linepart['name'] = implode('|', $flags);
if (isset($rule['param']) && $rule['param'] != 'none') {
$linepart['name'] .= ' ';
switch ($rule['param']) {
case 'optional':
$linepart['name'] .= "[ <{$rule['paramType']}> ]";
break;
case 'required':
$linepart['name'] .= "<{$rule['paramType']}>";
break;
}
}
if (strlen($linepart['name']) > $maxLen) {
$maxLen = strlen($linepart['name']);
}
$linepart['help'] = '';
if (isset($rule['help'])) {
$linepart['help'] .= $rule['help'];
}
$lines[] = $linepart;
}
foreach ($lines as $linepart) {
$usage .= sprintf("%s %s\n",
str_pad($linepart['name'], $maxLen),
$linepart['help']);
}
return $usage;
}
/**
* Define aliases for options.
*
* The parameter $aliasMap is an associative array
* mapping option name (short or long) to an alias.
*
* @param array $aliasMap
* @throws Zend_Console_Getopt_Exception
* @return Zend_Console_Getopt Provides a fluent interface
*/
public function setAliases($aliasMap)
{
foreach ($aliasMap as $flag => $alias)
{
if ($this->_getoptConfig[self::CONFIG_IGNORECASE]) {
$flag = strtolower($flag);
$alias = strtolower($alias);
}
if (!isset($this->_ruleMap[$flag])) {
continue;
}
$flag = $this->_ruleMap[$flag];
if (isset($this->_rules[$alias]) || isset($this->_ruleMap[$alias])) {
$o = (strlen($alias) == 1 ? '-' : '--') . $alias;
/**
* @see Zend_Console_Getopt_Exception
*/
throw new Zend_Console_Getopt_Exception(
"Option \"$o\" is being defined more than once.");
}
$this->_rules[$flag]['alias'][] = $alias;
$this->_ruleMap[$alias] = $flag;
}
return $this;
}
/**
* Define help messages for options.
*
* The parameter $help_map is an associative array
* mapping option name (short or long) to the help string.
*
* @param array $helpMap
* @return Zend_Console_Getopt Provides a fluent interface
*/
public function setHelp($helpMap)
{
foreach ($helpMap as $flag => $help)
{
if (!isset($this->_ruleMap[$flag])) {
continue;
}
$flag = $this->_ruleMap[$flag];
$this->_rules[$flag]['help'] = $help;
}
return $this;
}
/**
* Parse command-line arguments and find both long and short
* options.
*
* Also find option parameters, and remaining arguments after
* all options have been parsed.
*
* @return Zend_Console_Getopt|null Provides a fluent interface
*/
public function parse()
{
if ($this->_parsed === true) {
return;
}
$argv = $this->_argv;
$this->_options = array();
$this->_remainingArgs = array();
while (count($argv) > 0) {
if ($argv[0] == '--') {
array_shift($argv);
if ($this->_getoptConfig[self::CONFIG_DASHDASH]) {
$this->_remainingArgs = array_merge($this->_remainingArgs, $argv);
break;
}
}
if (substr($argv[0], 0, 2) == '--') {
$this->_parseLongOption($argv);
} else if (substr($argv[0], 0, 1) == '-' && ('-' != $argv[0] || count($argv) >1)) {
$this->_parseShortOptionCluster($argv);
} else {
$this->_remainingArgs[] = array_shift($argv);
}
}
$this->_parsed = true;
return $this;
}
/**
* Parse command-line arguments for a single long option.
* A long option is preceded by a double '--' character.
* Long options may not be clustered.
*
* @param mixed &$argv
* @return void
*/
protected function _parseLongOption(&$argv)
{
$optionWithParam = ltrim(array_shift($argv), '-');
$l = explode('=', $optionWithParam);
$flag = array_shift($l);
$param = array_shift($l);
if (isset($param)) {
array_unshift($argv, $param);
}
$this->_parseSingleOption($flag, $argv);
}
/**
* Parse command-line arguments for short options.
* Short options are those preceded by a single '-' character.
* Short options may be clustered.
*
* @param mixed &$argv
* @return void
*/
protected function _parseShortOptionCluster(&$argv)
{
$flagCluster = ltrim(array_shift($argv), '-');
foreach (str_split($flagCluster) as $flag) {
$this->_parseSingleOption($flag, $argv);
}
}
/**
* Parse command-line arguments for a single option.
*
* @param string $flag
* @param mixed $argv
* @throws Zend_Console_Getopt_Exception
* @return void
*/
protected function _parseSingleOption($flag, &$argv)
{
if ($this->_getoptConfig[self::CONFIG_IGNORECASE]) {
$flag = strtolower($flag);
}
if (!isset($this->_ruleMap[$flag])) {
/**
* @see Zend_Console_Getopt_Exception
*/
throw new Zend_Console_Getopt_Exception(
"Option \"$flag\" is not recognized.",
$this->getUsageMessage());
}
$realFlag = $this->_ruleMap[$flag];
switch ($this->_rules[$realFlag]['param']) {
case 'required':
if (count($argv) > 0) {
$param = array_shift($argv);
$this->_checkParameterType($realFlag, $param);
} else {
/**
* @see Zend_Console_Getopt_Exception
*/
throw new Zend_Console_Getopt_Exception(
"Option \"$flag\" requires a parameter.",
$this->getUsageMessage());
}
break;
case 'optional':
if (count($argv) > 0 && substr($argv[0], 0, 1) != '-') {
$param = array_shift($argv);
$this->_checkParameterType($realFlag, $param);
} else {
$param = true;
}
break;
default:
$param = true;
}
$this->_options[$realFlag] = $param;
}
/**
* Return true if the parameter is in a valid format for
* the option $flag.
* Throw an exception in most other cases.
*
* @param string $flag
* @param string $param
* @throws Zend_Console_Getopt_Exception
* @return bool
*/
protected function _checkParameterType($flag, $param)
{
$type = 'string';
if (isset($this->_rules[$flag]['paramType'])) {
$type = $this->_rules[$flag]['paramType'];
}
switch ($type) {
case 'word':
if (preg_match('/\W/', $param)) {
/**
* @see Zend_Console_Getopt_Exception
*/
throw new Zend_Console_Getopt_Exception(
"Option \"$flag\" requires a single-word parameter, but was given \"$param\".",
$this->getUsageMessage());
}
break;
case 'integer':
if (preg_match('/\D/', $param)) {
/**
* @see Zend_Console_Getopt_Exception
*/
throw new Zend_Console_Getopt_Exception(
"Option \"$flag\" requires an integer parameter, but was given \"$param\".",
$this->getUsageMessage());
}
break;
case 'string':
default:
break;
}
return true;
}
/**
* Define legal options using the gnu-style format.
*
* @param string $rules
* @return void
*/
protected function _addRulesModeGnu($rules)
{
$ruleArray = array();
/**
* Options may be single alphanumeric characters.
* Options may have a ':' which indicates a required string parameter.
* No long options or option aliases are supported in GNU style.
*/
preg_match_all('/([a-zA-Z0-9]:?)/', $rules, $ruleArray);
foreach ($ruleArray[1] as $rule) {
$r = array();
$flag = substr($rule, 0, 1);
if ($this->_getoptConfig[self::CONFIG_IGNORECASE]) {
$flag = strtolower($flag);
}
$r['alias'][] = $flag;
if (substr($rule, 1, 1) == ':') {
$r['param'] = 'required';
$r['paramType'] = 'string';
} else {
$r['param'] = 'none';
}
$this->_rules[$flag] = $r;
$this->_ruleMap[$flag] = $flag;
}
}
/**
* Define legal options using the Zend-style format.
*
* @param array $rules
* @throws Zend_Console_Getopt_Exception
* @return void
*/
protected function _addRulesModeZend($rules)
{
foreach ($rules as $ruleCode => $helpMessage)
{
// this may have to translate the long parm type if there
// are any complaints that =string will not work (even though that use
// case is not documented)
if (in_array(substr($ruleCode, -2, 1), array('-', '='))) {
$flagList = substr($ruleCode, 0, -2);
$delimiter = substr($ruleCode, -2, 1);
$paramType = substr($ruleCode, -1);
} else {
$flagList = $ruleCode;
$delimiter = $paramType = null;
}
if ($this->_getoptConfig[self::CONFIG_IGNORECASE]) {
$flagList = strtolower($flagList);
}
$flags = explode('|', $flagList);
$rule = array();
$mainFlag = $flags[0];
foreach ($flags as $flag) {
if (empty($flag)) {
/**
* @see Zend_Console_Getopt_Exception
*/
throw new Zend_Console_Getopt_Exception(
"Blank flag not allowed in rule \"$ruleCode\".");
}
if (strlen($flag) == 1) {
if (isset($this->_ruleMap[$flag])) {
/**
* @see Zend_Console_Getopt_Exception
*/
throw new Zend_Console_Getopt_Exception(
"Option \"-$flag\" is being defined more than once.");
}
$this->_ruleMap[$flag] = $mainFlag;
$rule['alias'][] = $flag;
} else {
if (isset($this->_rules[$flag]) || isset($this->_ruleMap[$flag])) {
/**
* @see Zend_Console_Getopt_Exception
*/
throw new Zend_Console_Getopt_Exception(
"Option \"--$flag\" is being defined more than once.");
}
$this->_ruleMap[$flag] = $mainFlag;
$rule['alias'][] = $flag;
}
}
if (isset($delimiter)) {
switch ($delimiter) {
case self::PARAM_REQUIRED:
$rule['param'] = 'required';
break;
case self::PARAM_OPTIONAL:
default:
$rule['param'] = 'optional';
}
switch (substr($paramType, 0, 1)) {
case self::TYPE_WORD:
$rule['paramType'] = 'word';
break;
case self::TYPE_INTEGER:
$rule['paramType'] = 'integer';
break;
case self::TYPE_STRING:
default:
$rule['paramType'] = 'string';
}
} else {
$rule['param'] = 'none';
}
$rule['help'] = $helpMessage;
$this->_rules[$mainFlag] = $rule;
}
}
}
Getopt/Exception.php 0000604 00000003021 15071177310 0010447 0 ustar 00 <?php
/**
* Zend Framework
*
* LICENSE
*
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* http://framework.zend.com/license/new-bsd
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to license@zend.com so we can send you a copy immediately.
*
* @category Zend
* @package Zend_Console_Getopt
* @copyright Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
/**
* @see Zend_Console_Getopt_Exception
*/
require_once 'Zend/Exception.php';
/**
* @category Zend
* @package Zend_Console_Getopt
* @copyright Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class Zend_Console_Getopt_Exception extends Zend_Exception
{
/**
* Usage
*
* @var string
*/
protected $usage = '';
/**
* Constructor
*
* @param string $message
* @param string $usage
* @return void
*/
public function __construct($message, $usage = '')
{
$this->usage = $usage;
parent::__construct($message);
}
/**
* Returns the usage
*
* @return string
*/
public function getUsageMessage()
{
return $this->usage;
}
}
Exception.php 0000604 00000002214 15071551452 0007213 0 ustar 00 <?php
/**
* Zend Framework
*
* LICENSE
*
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* http://framework.zend.com/license/new-bsd
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to license@zend.com so we can send you a copy immediately.
*
* @category ZendX
* @package ZendX_Whois
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
* @version $Id: Exception.php 20165 2010-01-09 18:57:56Z bkarwin $
*/
/**
* @see ZendX_Exception
*/
require_once 'ZendX/Exception.php';
/**
* Exception class for ZendX_Console
*
* @category ZendX
* @package ZendX_Console
* @uses Zend_Exception
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class ZendX_Console_Exception extends ZendX_Exception
{
}
Process/Exception.php 0000604 00000002277 15071551452 0010642 0 ustar 00 <?php
/**
* Zend Framework
*
* LICENSE
*
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* http://framework.zend.com/license/new-bsd
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to license@zend.com so we can send you a copy immediately.
*
* @category ZendX
* @package ZendX_Console
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
* @version $Id: Exception.php 20165 2010-01-09 18:57:56Z bkarwin $
*/
/**
* @see ZendX_Console_Exception
*/
require_once 'ZendX/Console/Exception.php';
/**
* Exception class for ZendX_Console_Process
*
* @category ZendX
* @package ZendX_Console
* @uses ZendX_Console_Exception
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
class ZendX_Console_Process_Exception extends ZendX_Console_Exception
{
}
Process/Unix.php 0000604 00000046655 15071551452 0007637 0 ustar 00 <?php
/**
* Zend Framework
*
* LICENSE
*
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* http://framework.zend.com/license/new-bsd
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to license@zend.com so we can send you a copy immediately.
*
* @category ZendX
* @package ZendX_Console
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
* @version $Id: Unix.php 20165 2010-01-09 18:57:56Z bkarwin $
*/
/**
* ZendX_Console_Process_Unix allows you to spawn a class as a separated process
*
* @category ZendX
* @package ZendX_Console
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://framework.zend.com/license/new-bsd New BSD License
*/
abstract class ZendX_Console_Process_Unix
{
/**
* Void method
*/
const VOID_METHOD = 'void_method';
/**
* Return method
*/
const RETURN_METHOD = 'void_method';
/**
* Unique thread name
*
* @var string
*/
private $_name;
/**
* PID of the child process
*
* @var integer
*/
private $_pid = null;
/**
* UID of the child process owner
*
* @var integer
*/
private $_puid = null;
/**
* GUID of the child process owner
*
* @var integer
*/
private $_guid = null;
/**
* Whether the process is yet forked or not
*
* @var boolean
*/
private $_isRunning = false;
/**
* Wether we are into child process or not
*
* @var boolean
*/
private $_isChild = false;
/**
* A data structure to hold data for Inter Process Communications
*
* @var array
*/
private $_internalIpcData = array();
/**
* Key to access to Shared Memory Area.
*
* @var integer
*/
private $_internalIpcKey;
/**
* Key to access to Sync Semaphore.
*
* @var integer
*/
private $_internalSemKey;
/**
* Is Shared Memory Area OK? If not, the start() method will block.
* Otherwise we'll have a running child without any communication channel.
*
* @var boolean
*/
private $_ipcIsOkay;
/**
* Filename of the IPC segment file
*
* @var string
*/
private $_ipcSegFile;
/**
* Filename of the semaphor file
*
* @var string
*/
private $_ipcSemFile;
/**
* Constructor method
*
* Allocates a new pseudo-thread object. Optionally, set a PUID, a GUID and
* a UMASK for the child process. This also initialize Shared Memory
* Segments for process communications.
*
* @param integer $puid
* @param integer $guid
* @param integer $umask
* @throws ZendX_Console_Process_Exception When running on windows
* @throws ZendX_Console_Process_Exception When running in web enviroment
* @throws ZendX_Console_Process_Exception When shmop_* functions don't exist
* @throws ZendX_Console_Process_Exception When pcntl_* functions don't exist
* @throws ZendX_Console_Process_Exception When posix_* functions don't exist
*/
public function __construct($puid = null, $guid = null, $umask = null)
{
if (substr(PHP_OS, 0, 3) === 'WIN') {
require_once 'ZendX/Console/Process/Exception.php';
throw new ZendX_Console_Process_Exception('Cannot run on windows');
} else if (!in_array(substr(PHP_SAPI, 0, 3), array('cli', 'cgi'))) {
require_once 'ZendX/Console/Process/Exception.php';
throw new ZendX_Console_Process_Exception('Can only run on CLI or CGI enviroment');
} else if (!function_exists('shmop_open')) {
require_once 'ZendX/Console/Process/Exception.php';
throw new ZendX_Console_Process_Exception('shmop_* functions are required');
} else if (!function_exists('pcntl_fork')) {
require_once 'ZendX/Console/Process/Exception.php';
throw new ZendX_Console_Process_Exception('pcntl_* functions are required');
} else if (!function_exists('posix_kill')) {
require_once 'ZendX/Console/Process/Exception.php';
throw new ZendX_Console_Process_Exception('posix_* functions are required');
}
$this->_isRunning = false;
$this->_name = md5(uniqid(rand()));
$this->_guid = $guid;
$this->_puid = $puid;
if ($umask !== null) {
umask($umask);
}
// Try to create the shared memory segment. The variable
// $this->_ipcIsOkay contains the return code of this operation and must
// be checked before forking
if ($this->_createIpcSegment() && $this->_createIpcSemaphore()) {
$this->_ipcIsOkay = true;
} else {
$this->_ipcIsOkay = false;
}
}
/**
* Stop the child on destruction
*/
public function __destruct()
{
if ($this->isRunning()) {
$this->stop();
}
}
/**
* Causes this pseudo-thread to begin parallel execution.
*
* This method first checks of all the Shared Memory Segment. If okay, it
* forks the child process, attaches signal handler and returns immediatly.
* The status is set to running, and a PID is assigned. The result is that
* two pseudo-threads are running concurrently: the current thread (which
* returns from the call to the start() method) and the other thread (which
* executes its run() method).
*
* @throws ZendX_Console_Process_Exception When SHM segments can't be created
* @throws ZendX_Console_Process_Exception When process forking fails
* @return void
*/
public function start()
{
if (!$this->_ipcIsOkay) {
require_once 'ZendX/Console/Process/Exception.php';
throw new ZendX_Console_Process_Exception('Unable to create SHM segments for process communications');
}
// @see http://www.php.net/manual/en/function.pcntl-fork.php#41150
@ob_end_flush();
pcntl_signal(SIGCHLD, SIG_IGN);
$pid = @pcntl_fork();
if ($pid === -1) {
require_once 'ZendX/Console/Process/Exception.php';
throw new ZendX_Console_Process_Exception('Forking process failed');
} else if ($pid === 0) {
// This is the child
$this->_isChild = true;
// Sleep a second to avoid problems
sleep(1);
// Install the signal handler
pcntl_signal(SIGUSR1, array($this, '_sigHandler'));
// If requested, change process identity
if ($this->_guid !== null) {
posix_setgid($this->_guid);
}
if ($this->_puid !== null) {
posix_setuid($this->_puid);
}
// Run the child
try {
$this->_run();
} catch (Exception $e) {
// We have to catch any exceptions and clean up the process,
// else we will have a memory leak.
}
// Destroy the child after _run() execution. Required to avoid
// unuseful child processes after execution
exit(0);
} else {
// Else this is the parent
$this->_isChild = false;
$this->_isRunning = true;
$this->_pid = $pid;
}
}
/**
* Causes the current thread to die.
*
* The relative process is killed and disappears immediately from the
* processes list.
*
* @return boolean
*/
public function stop()
{
$success = false;
if ($this->_pid > 0) {
$status = 0;
posix_kill($this->_pid, 9);
pcntl_waitpid($this->_pid, $status, WNOHANG);
$success = pcntl_wifexited($status);
$this->_cleanProcessContext();
}
return $success;
}
/**
* Test if the pseudo-thread is already started.
*
* @return boolean
*/
public function isRunning()
{
return $this->_isRunning;
}
/**
* Set a variable into the shared memory segment, so that it can accessed
* both from the parent and from the child process. Variable names
* beginning with underlines are only permitted to interal functions.
*
* @param string $name
* @param mixed $value
* @throws ZendX_Console_Process_Exception When an invalid variable name is supplied
* @return void
*/
public function setVariable($name, $value)
{
if ($name[0] === '_') {
require_once 'ZendX/Console/Process/Exception.php';
throw new ZendX_Console_Process_Exception('Only internal functions may use underline (_) as variable prefix');
}
$this->_writeVariable($name, $value);
}
/**
* Get a variable from the shared memory segment. Returns NULL if the
* variable doesn't exist.
*
* @param string $name
* @return mixed
*/
public function getVariable($name)
{
$this->_readFromIpcSegment();
if (isset($this->_internalIpcData[$name])) {
return $this->_internalIpcData[$name];
} else {
return null;
}
}
/**
* Read the time elapsed since the last child setAlive() call.
*
* This method is useful because often we have a pseudo-thread pool and we
* need to know each pseudo-thread status. If the child executes the
* setAlive() method, the parent with getLastAlive() can know that child is
* alive.
*
* @return integer
*/
public function getLastAlive()
{
$pingTime = $this->getVariable('_pingTime');
return ($pingTime === null ? 0 : (time() - $pingTime));
}
/**
* Returns the PID of the current pseudo-thread.
*
* @return integer
*/
public function getPid()
{
return $this->_pid;
}
/**
* Set a pseudo-thread property that can be read from parent process
* in order to know the child activity.
*
* Practical usage requires that child process calls this method at regular
* time intervals; parent will use the getLastAlive() method to know
* the elapsed time since the last pseudo-thread life signals...
*
* @return void
*/
protected function _setAlive()
{
$this->_writeVariable('_pingTime', time());
}
/**
* This is called from within the parent; all the communication stuff
* is done here.
*
* @param string $methodName
* @param array $argList
* @param string $type
* @return mixed
*/
protected function _callCallbackMethod($methodName, array $argList = array(), $type = self::VOID_METHOD)
{
// This is the parent, so we really cannot execute the method. Check
// arguments passed to the method.
if ($type === self::RETURN_METHOD) {
$this->_internalIpcData['_callType'] = self::RETURN_METHOD;
} else {
$this->_internalIpcData['_callType'] = self::VOID_METHOD;
}
// These setting are common to both the calling types
$this->_internalIpcData['_callMethod'] = $methodName;
$this->_internalIpcData['_callInput'] = $argList;
// Write the IPC data to the shared segment
$this->_writeToIpcSegment();
// Now we need to differentiate a bit.
switch ($this->_internalIpcData['_callType']) {
case VOID_METHOD:
// Notify the child so it can process the request
$this->_sendSigUsr1();
break;
case RETURN_METHOD:
// Set the semaphorew
shmop_write($this->_internalSemKey, 1, 0);
// Notify the child so it can process the request
$this->_sendSigUsr1();
// Block until the child process return
$this->_waitForIpcSemaphore();
// Read from the SHM segment. The result is stored into
// $this->_internalIpcData['_callOutput']
$this->_readFromIpcSegment();
// Data are returned. Now we can reset the semaphore
shmop_write($this->_internalSemKey, 0, 1);
// Return the result. Hence no break required here
return $this->_internalIpcData['_callOutput'];
}
}
/**
* This method actually implements the pseudo-thread logic.
*
* @return void
*/
abstract protected function _run();
/**
* Sends signal to the child process
*
* @return void
*/
private function _sendSigUsr1()
{
if ($this->_pid > 0) {
posix_kill($this->_pid, SIGUSR1);
}
}
/**
* Acutally Write a variable to the shared memory segment
*
* @param string $name
* @param mixed $value
* @return void
*/
private function _writeVariable($name, $value)
{
$this->_internalIpcData[$name] = $value;
$this->_writeToIpcSegment();
}
/**
* Destroy thread context and free relative resources.
*
* @return void
*/
private function _cleanProcessContext()
{
shmop_delete($this->_internalIpcKey);
shmop_delete($this->_internalSemKey);
shmop_close($this->_internalIpcKey);
shmop_close($this->_internalSemKey);
@unlink($this->_ipcSegFile);
@unlink($this->_ipcSemFile);
$this->_isRunning = false;
$this->_pid = null;
}
/**
* This is the signal handler that makes the communications between client
* and server possible.
*
* @param integer $signo
* @return void
*/
private function _sigHandler($signo)
{
switch ($signo) {
case SIGTERM:
// Handle shutdown tasks. Hence no break is require
exit;
case SIGUSR1:
// This is the User-defined signal we'll use. Read the SHM segment
$this->_readFromIpcSegment();
if (isset($this->_internalIpcData['_callType'])) {
$method = $this->_internalIpcData['_callMethod'];
$params = $this->_internalIpcData['_callInput'];
switch ($this->_internalIpcData['_callType']) {
case self::VOID_METHOD:
// Simple call the (void) method and return immediatly
// no semaphore is placed into parent, so the processing
// is async
call_user_func(array($this, $method), $params);
break;
case self::RETURN_METHOD:
// Process the request
$this->_internalIpcData['_callOutput'] = call_user_func(array($this, $method), $params);
// Write the result into IPC segment
$this->_writeToIPCsegment();
// Unlock the semaphore but block _writeToIpcSegment()
shmop_write($this->_internalSemKey, 0, 0);
shmop_write($this->_internalSemKey, 1, 1);
break;
}
}
break;
default:
// Ignore all other singals
break;
}
}
/**
* Wait for IPC Semaphore
*
* @return void
*/
private function _waitForIpcSemaphore()
{
while (true) {
$okay = shmop_read($this->_internalSemKey, 0, 1);
if ($okay === 0) {
break;
}
usleep(10);
}
}
/**
* Read data from IPC segment
*
* @throws ZendX_Console_Process_Exception When writing of SHM segment fails
* @return void
*/
private function _readFromIpcSegment()
{
$serializedIpcData = shmop_read($this->_internalIpcKey,
0,
shmop_size($this->_internalIpcKey));
if ($serializedIpcData === false) {
require_once 'ZendX/Console/Process/Exception.php';
throw new ZendX_Console_Process_Exception('Fatal error while reading SHM segment');
}
$data = @unserialize($serializedIpcData);
if ($data !== false) {
$this->_internalIpcData = $data;
}
}
/**
* Write data to IPC segment
*
* @throws ZendX_Console_Process_Exception When writing of SHM segment fails
* @return void
*/
private function _writeToIpcSegment()
{
// Read the transaction bit (2 bit of _internalSemKey segment). If it's
// value is 1, we're into the execution of a PHP_FORK_RETURN_METHOD, so
// we must not write to segment (data corruption)
if (shmop_read($this->_internalSemKey, 1, 1) === 1) {
return;
}
$serializedIpcData = serialize($this->_internalIpcData);
// Set the exchange array (IPC) into the shared segment
$shmBytesWritten = shmop_write($this->_internalIpcKey,
$serializedIpcData,
0);
// Check if lenght of SHM segment is enougth to contain data
if ($shmBytesWritten !== strlen($serializedIpcData)) {
require_once 'ZendX/Console/Process/Exception.php';
throw new ZendX_Console_Process_Exception('Fatal error while writing to SHM segment');
}
}
/**
* Create an IPC segment
*
* @throws ZendX_Console_Process_Exception When SHM segment can't be created
* @return boolean
*/
private function _createIpcSegment()
{
$this->_ipcSegFile = realpath(sys_get_temp_dir()) . '/' . rand() . $this->_name . '.shm';
touch($this->_ipcSegFile);
$shmKey = ftok($this->_ipcSegFile, 't');
if ($shmKey === -1) {
require_once 'ZendX/Console/Process/Exception.php';
throw new ZendX_Console_Process_Exception('Could not create SHM segment');
}
$this->_internalIpcKey = @shmop_open($shmKey, 'c', 0644, 10240);
if (!$this->_internalIpcKey) {
@unlink($this->_ipcSegFile);
return false;
}
return true;
}
/**
* Create IPC semaphore
*
* @throws ZendX_Console_Process_Exception When semaphore can't be created
* @return boolean
*/
private function _createIpcSemaphore()
{
$this->_ipcSemFile = realpath(sys_get_temp_dir()) . '/' . rand() . $this->_name . '.sem';
touch($this->_ipcSemFile);
$semKey = ftok($this->_ipcSemFile, 't');
if ($semKey === -1) {
require_once 'ZendX/Console/Process/Exception.php';
throw new ZendX_Console_Process_Exception('Could not create semaphore');
}
$this->_internalSemKey = @shmop_open($semKey, 'c', 0644, 10);
if (!$this->_internalSemKey) {
@unlink($this->_ipcSemFile);
return false;
}
return true;
}
}