getopt
(PHP 4 >= 4.3.0, PHP 5, PHP 7)
getopt — Извлечение параметров из списка аргументов командной строки
Описание
$options
[, array $longopts
] )Анализирует параметры переданные в скрипт.
Список параметров
-
options - Каждый символ в этой строке будет рассматриваться как параметр и сравниваться с символами, переданными в скрипт, перед которыми будет стоять дефис (-). Например, строка параметров "x" распознается, как параметр -x. Допускаются только символы a-z, A-Z и 0-9.
-
longopts - Массив параметров. Каждый элемент массива будет использоваться как строковый параметр и сравниваться с параметрами, переданными в скрипт, перед которыми будет стоять двойной дефис (--). Например, элемент longopts "opt" будет расшифровываться как --opt.
Аргумент options может содержать следующие элементы:
- Отдельные символы (не имеющие значений)
- Символы, за которыми следует двоеточие (после двоеточия должно быть значение параметра)
- Символы, за которыми следует два двоеточия (значение параметра необязательно)
Замечание: Необязательные значения нельзя отделять от других пробелом " ".
Замечание:
Форматы
optionsиlongoptsпрактически совпадают. Различие состоит только в том, чтоlongoptsпринимает массив параметров (в котором каждый элемент является параметром) в то время, какoptionsпринимает строку (где параметром является каждый символ).
Возвращаемые значения
Функция вернет массив параметров / пар аргументов или FALSE в случае неудачи.
Замечание:
Как только встретится первый символ, не являющийся параметром, разбор строки команды будет завершен, а оставшаяся часть строки будет проигнорирована.
Список изменений
| Версия | Описание |
|---|---|
| 5.3.0 | Добавлена поддержка "=" в качестве разделителя параметр/значение. |
| 5.3.0 | Добавлена поддержка необязательных значений параметров, (задаваемая "::"). |
| 5.3.0 |
Аргумент longopts доступен на всех системах.
|
| 5.3.0 | Функция больше не зависит от системы, теперь работает в и на Windows. |
Примеры
Пример #1 Пример использования getopt(): основное
<?php
// Скрипт example.php
$options = getopt("f:hp:");
var_dump($options);
?>
shell> php example.php -fvalue -h
Результат выполнения данного примера:
array(2) {
["f"]=>
string(5) "value"
["h"]=>
bool(false)
}
Пример #2 Пример использования getopt(): добавление длинных опций
<?php
// Скрипт example.php
$shortopts = "";
$shortopts .= "f:"; // Обязательное значение
$shortopts .= "v::"; // Необязательное значение
$shortopts .= "abc"; // Эти параметры не принимают никаких значений
$longopts = array(
"required:", // Обязательное значение
"optional::", // Необязательное значение
"option", // Нет значения
"opt", // Нет значения
);
$options = getopt($shortopts, $longopts);
var_dump($options);
?>
shell> php example.php -f "value for f" -v -a --required value --optional="optional value" --option
Результат выполнения данного примера:
array(6) {
["f"]=>
string(11) "value for f"
["v"]=>
bool(false)
["a"]=>
bool(false)
["required"]=>
string(5) "value"
["optional"]=>
string(14) "optional value"
["option"]=>
bool(false)
}
Пример #3 Пример использования getopt(): Передача нескольких параметров как одного
<?php
// Скрипт example.php
$options = getopt("abc");
var_dump($options);
?>
shell> php example.php -aaac
Результат выполнения данного примера:
array(2) {
["a"]=>
array(3) {
[0]=>
bool(false)
[1]=>
bool(false)
[2]=>
bool(false)
}
["c"]=>
bool(false)
}
- PHP Руководство
- Функции по категориям
- Индекс функций
- Справочник функций
- Изменение поведения PHP
- PHP Опции и Информация
- assert_options
- assert
- cli_get_process_title
- cli_set_process_title
- dl
- extension_loaded
- gc_collect_cycles
- gc_disable
- gc_enable
- gc_enabled
- gc_mem_caches
- get_cfg_var
- get_current_user
- get_defined_constants
- get_extension_funcs
- get_include_path
- get_included_files
- get_loaded_extensions
- get_magic_quotes_gpc
- get_magic_quotes_runtime
- get_required_files
- get_resources
- getenv
- getlastmod
- getmygid
- getmyinode
- getmypid
- getmyuid
- getopt
- getrusage
- ini_alter
- ini_get_all
- ini_get
- ini_restore
- ini_set
- magic_quotes_runtime
- main
- memory_get_peak_usage
- memory_get_usage
- php_ini_loaded_file
- php_ini_scanned_files
- php_logo_guid
- php_sapi_name
- php_uname
- phpcredits
- phpinfo
- phpversion
- putenv
- restore_include_path
- set_include_path
- set_magic_quotes_runtime
- set_time_limit
- sys_get_temp_dir
- version_compare
- zend_logo_guid
- zend_thread_id
- zend_version
Коментарии
"phpnotes at kipu dot co dot uk" and "tim at digicol dot de" are both wrong or misleading. Sean was correct. Quoted space-containing strings on the command line are one argument. It has to do with how the shell handles the command line, more than PHP. PHP's getopt() is modeled on and probably built upon the Unix/POSIX/C library getopt(3) which treats strings as strings, and does not break them apart on white space.
Here's proof:
$ cat opt.php
#! /usr/local/bin/php
<?php
$options = getopt("f:");
print_r($options);
?>
$ opt.php -f a b c
Array
(
[f] => a
)
$ opt.php -f 'a b c'
Array
(
[f] => a b c
)
$ opt.php -f "a b c"
Array
(
[f] => a b c
)
$ opt.php -f a\ b\ c
Array
(
[f] => a b c
)
$
There are 2 simpler (and much faster) methods for getting good getopt() operation without creating your own handler.
1. Use the Console_Getopt PEAR class (should be standard in most PHP installations) which lets you specify both short and long form options as well as whether or not arguments supplied to an option are themselves 'optional'. Very simple to use and requires very little code to operate compaired to writing own handler.
2. If you cannot load external PEAR objects, use your shell's getopt() functions (which in BASHs case work very well) to process options and have your shell script then call your PHP script with a rigid argument structure that is very easy for PHP to digest such as:
% myfile.php -a TRUE -b FALSE -c ARGUMENT ...
If the initial arguments are invalid you can have the shell script return an error without calling the PHP script. Sounds convoluted but is a very simple solution and in fact PHP's own % pear command uses this method. /usr/bin/pear is a shell script that does some simle checking before calling pearcmd.php and repassing the arguments on to it.
The second method is by far the best for portability because it allows a single shell script to check a few things like your PHP version and respond acordingly e.g. does it call your PHP4 or PHP5 compatible script? Also, because getopt() is not available on Windows, The second solution allows you to do Windows specific testing as a BAT file (as oposed to BASH, ZSH or Korn on UNIX).
About getopt(String):
Parses the command-line arguments into an associative array, using the function's String parameter to specify arguments and options, thus:
* arguments are specified as any letter followed by a colon, e.g. "h:".
* arguments are returned as "h" => "value".
* options are specified as any letter not followed by a colon, e.g. "r".
* options are returned as "r" => (boolean) false.
Also note that:
1) Options or arguments not passed in the command-line parameters are not set in the returned associative array.
2) Options or arguments present in the command-line arguments multiple times are returned as an enumerated array within the returned associative array.
After you use the getopt function you can use the following script to update the $argv array:
<?php
$options = "c:ho:s:t:uvV";
$opts = getopt( $options );
foreach( $opts as $o => $a )
{
while( $k = array_search( "-" . $o, $argv ) )
{
if( $k )
unset( $argv[$k] );
if( preg_match( "/^.*".$o.":.*$/i", $options ) )
unset( $argv[$k+1] );
}
}
$argv = array_merge( $argv );
?>
Note: I used the array_merge function to reindex the array's keys.
Cheers, Koen Bollen
This is how I handle arguments with getopt: I use switch within a foreach at the beginning of a program.
<?php
$opts = getopt('hs:');
// Handle command line arguments
foreach (array_keys($opts) as $opt) switch ($opt) {
case 's':
// Do something with s parameter
$something = $opts['s'];
break;
case 'h':
print_help_message();
exit(1);
}
print "$something\n";
?>
Although very interesting, koenbollen at gnospamail dot com's update of the argv array fails when option values follow the option with no space :
Indeed
php MyScript.php5 -t5
and
php MyScript.php5 -t 5
with $options="t:" are treated as the same by getopt.
This upgraded function should take care of it :
File : shift_test.php5
<?php
function shift($options_array)
{
foreach( $options_array as $o => $a )
{
// Look for all occurrences of option in argv and remove if found :
// ----------------------------------------------------------------
// Look for occurrences of -o (simple option with no value) or -o<val> (no space in between):
while($k=array_search("-".$o.$a,$GLOBALS['argv']))
{ // If found remove from argv:
if($k)
unset($GLOBALS['argv'][$k]);
}
// Look for remaining occurrences of -o <val> (space in between):
while($k=array_search("-".$o,$GLOBALS['argv']))
{ // If found remove both option and value from argv:
if($k)
{ unset($GLOBALS['argv'][$k]);
unset($GLOBALS['argv'][$k+1]);
}
}
}
// Reindex :
$GLOBALS['argv']=array_merge($GLOBALS['argv']);
}
print_r($argv);
$options_array=getopt('t:h');
shift($options_array);
print_r($argv);
?>
>php shift_test.php5 -h -t4 param1 param2
will ouptut :
Array
(
[0] => test.php5
[1] => -h
[2] => -t4
[3] => param1
[4] => param2
)
Array
(
[0] => test.php5
[1] => param1
[2] => param2
)
>php shift_test.php5 -h -t 4 param1 param2
will ouptut :
Array
(
[0] => test.php5
[1] => -h
[2] => -t
[3] => 4
[4] => param1
[5] => param2
)
Array
(
[0] => test.php5
[1] => param1
[2] => param2
)
One thing of important note would be that getopt() actually respects the '--' option to end an option list. Thus given the code:
test.php:
<?php
$options = getopt("m:g:h:");
if (!is_array($options) ) {
print "There was a problem reading in the options.\n\n";
exit(1);
}
$errors = array();
print_r($options);
?>
And running:
# ./test.php ./run_vfs -h test1 -g test2 -m test3 -- this is a test -m green
Will return:
Array
(
[h] => test1
[g] => test2
[m] => test3
)
Whereas running:
# /test.php ./run_vfs -h test1 -g test2 -m test3 this is a test -m green
Will return:
Array
(
[h] => test1
[g] => test2
[m] => Array
(
[0] => test3
[1] => green
)
)
After getopt() of PHP5.3.0 (on Windows) ignored some parameters if there was a syntactical problem, I decided to code my own generic parameter parser.
<?php
/**
* Parses $GLOBALS['argv'] for parameters and assigns them to an array.
*
* Supports:
* -e
* -e <value>
* --long-param
* --long-param=<value>
* --long-param <value>
* <value>
*
* @param array $noopt List of parameters without values
*/
function parseParameters($noopt = array()) {
$result = array();
$params = $GLOBALS['argv'];
// could use getopt() here (since PHP 5.3.0), but it doesn't work relyingly
reset($params);
while (list($tmp, $p) = each($params)) {
if ($p{0} == '-') {
$pname = substr($p, 1);
$value = true;
if ($pname{0} == '-') {
// long-opt (--<param>)
$pname = substr($pname, 1);
if (strpos($p, '=') !== false) {
// value specified inline (--<param>=<value>)
list($pname, $value) = explode('=', substr($p, 2), 2);
}
}
// check if next parameter is a descriptor or a value
$nextparm = current($params);
if (!in_array($pname, $noopt) && $value === true && $nextparm !== false && $nextparm{0} != '-') list($tmp, $value) = each($params);
$result[$pname] = $value;
} else {
// param doesn't belong to any option
$result[] = $p;
}
}
return $result;
}
?>
A call like: php.exe -f test.php -- alfons -a 1 -b2 -c --d 2 --e=3=4 --f "alber t" hans wurst
and an in-program call parseParameters(array('f')); would yield in a resulting array:
Array
(
[0] => alfons
[a] => 1
[b2] => 1
[c] => 1
[d] => 2
[e] => 3=4
[f] => 1
[1] => alber t
[2] => hans
[3] => wurst
)
As you can see, values without an identifier are stored with numeric indexes. Existing identifiers without values get "true".
It seems under PHP 5.3.2, getopt() makes a script fail to load if called via HTTP without any conditions. You'll need something like if(isset($_SERVER['argc'])) $args = getopt(); to prevent that.Here's another way of removing options found by getopt() from the argv[] array. It handles the different kind of parameters without eating chunks that do not belong to an --option. (-nr foo param1 param2 foo)
<?php
$parameters = array(
'n' => 'noparam',
'r:' => 'required:',
'o::' => 'optional::',
);
$options = getopt(implode('', array_keys($parameters)), $parameters);
$pruneargv = array();
foreach ($options as $option => $value) {
foreach ($argv as $key => $chunk) {
$regex = '/^'. (isset($option[1]) ? '--' : '-') . $option . '/';
if ($chunk == $value && $argv[$key-1][0] == '-' || preg_match($regex, $chunk)) {
array_push($pruneargv, $key);
}
}
}
while ($key = array_pop($pruneargv)) unset($argv[$key]);
?>
getopt() only returns the options specified if they were listed in the options.
So you cant make a switch() use default: to complain of an unknown option. :(
Sometimes you will want to run a script from both the command line and as a web page, for example to debug with better output or a command line version that writes an image to the system but a web version that prints the image in the browser. You can use this function to get the same options whether passed as command line arguments or as $_REQUEST values.
<?php
/**
* Get options from the command line or web request
*
* @param string $options
* @param array $longopts
* @return array
*/
function getoptreq ($options, $longopts)
{
if (PHP_SAPI === 'cli' || empty($_SERVER['REMOTE_ADDR'])) // command line
{
return getopt($options, $longopts);
}
else if (isset($_REQUEST)) // web script
{
$found = array();
$shortopts = preg_split('@([a-z0-9][:]{0,2})@i', $options, 0, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY);
$opts = array_merge($shortopts, $longopts);
foreach ($opts as $opt)
{
if (substr($opt, -2) === '::') // optional
{
$key = substr($opt, 0, -2);
if (isset($_REQUEST[$key]) && !empty($_REQUEST[$key]))
$found[$key] = $_REQUEST[$key];
else if (isset($_REQUEST[$key]))
$found[$key] = false;
}
else if (substr($opt, -1) === ':') // required value
{
$key = substr($opt, 0, -1);
if (isset($_REQUEST[$key]) && !empty($_REQUEST[$key]))
$found[$key] = $_REQUEST[$key];
}
else if (ctype_alnum($opt)) // no value
{
if (isset($_REQUEST[$opt]))
$found[$opt] = false;
}
}
return $found;
}
return false;
}
?>
Example
<?php
// php script.php -a -c=XXX -e=YYY -f --two --four=ZZZ --five=5
// script.php?a&c=XXX&e=YYY&f&two&four=ZZZ&five=5
$opts = getoptreq('abc:d:e::f::', array('one', 'two', 'three:', 'four:', 'five::'));
var_dump($opts);
/**
array(7) {
'a' => bool(false)
'c' => string(3) "XXX"
'e' => string(3) "YYY"
'f' => bool(false)
'two' => bool(false)
'four' => string(3) "ZZZ"
'five' => string(1) "5"
}
*/
?>
As already mentioned getopt() will stop parsing options upon the '--'. Sometimes you will have options and arguments but the user may not always provide the explicit -- option.
Below is a quick way to collect options and arguments regardless of the -- consistently.
#!/usr/bin/php
<?php
$options = getopt('hl::m:v:a', [
'help',
'list::',
'module:',
'version:',
'all',
]);
var_dump( $options );
$args = array_search('--', $argv);
$args = array_splice($argv, $args ? ++$args : (count($argv) - count($opt)));
var_dump( $args );
?>
To elaborate on what 'ch1902' said, there certainly are instances where you may need to execute a script via CLI and the HTTP protocol. In such an instance, you can normalize how your script parses via CLI (using getopt()) as well as via HTTP (using $_GET) with the following simplified code:
<?php
// PHP 5.4+ only due to the new array brace style.
function request(array $options = []) {
// Set the default values.
$defaults = [
'params' => '',
'os' => '',
'username' => posix_getpwuid(posix_geteuid())['name'],
'env' => ''
];
$options += $defaults;
// Sufficient enough check for CLI.
if ('cli' === PHP_SAPI) {
return getopt('', ['params:', 'os::', 'username::', 'env::']) + $options;
}
return $_GET + $options;
}
print_r(request());
?>
The above code would yield the results below when access via CLI and HTTP.
/**
* params = foo/bar
* username = housni.yakoob
*/
// CLI
$ php script.php --params=foo/bar --username=housni.yakoob
Array
(
[params] => foo/bar
[username] => housni.yakoob
[os] =>
[env] =>
)
// HTTP
script.php?params=foo/bar&username=housni.yakoob
Array
(
[params] => foo/bar
[username] => housni.yakoob
[os] =>
[env] =>
)
/**
* params = foo/bar
* username = Not provided, therefore, the default value will be used.
*/
// CLI
$ whoami && php script.php --params=foo/bar
housni // <-- Current users usersname (output of `whoami`).
Array
(
[params] => foo/bar
[os] =>
[username] => housni
[env] =>
)
// HTTP
script.php?params=foo/bar
Array
(
[params] => foo/bar
[os] =>
// The username of my Apache user, the result of posix_getpwuid(posix_geteuid())['name']
[username] => www-data
[env] =>
)
As you can see, the output is consistent when the script is executed via the CLI or the web.
when using -f option to indicate script name, php does not allow to use double dash -- to define options after the script name;
For example, the following command cannot be execute:
php -f myscript.php --config "myconfig.ini"
Your description on getopt is either wrong or the documentation of the function is wrong.
-- snippet --
array getopt ( string $options [, array $longopts [, int &$optind ]] )
--
As I read this only the first parameter string $options is required.
-- snippet --
longopts
An array of options. Each ...
optind
If the optind parameter is present, ...
--
This means that "longopts" is optional, but the third parameter "optind" is required (although the description leaves room for interpretation). This is against the possibilities of PHP because when a parameter is declared optional all following parameters must be declared optional as well.
See functions.arguments Example #4 and #5.
The immutable embedded stub (PHPStorm) [ https://github.com/JetBrains/phpstorm-stubs/blob/master/standard/standard_3.php ] specifies this:
-- snippet --
function getopt ($options, array $longopts = null, &$optind) {}
--
Which is also wrong, but probably based upon this documentation.
if you use command like below
php [filename] [argument without (-) ] [options]
getopt don't return value. you can use this function
function getoptions() {
global $argv,$argc;
$options = array();
for($i = 0;$i < $argc;$i++) {
$arg = $argv[$i];
if(strlen($arg) > 1 && $arg[0] == '-') {
if($arg[1] == '-' && $i + 1 < $argc) { $i++; $options[substr($arg,2,strlen($arg))] = $argv[$i]; }
else $options[$arg[1]] = substr($arg,2,strlen($arg));
}
}
return $options;
}
Beware, this function can be dangerous for options following arguments when, for example, you make use of a --dry-run option, due to this behaviour:
"Note: The parsing of options will end at the first non-option found, anything that follows is discarded."
My script was doing a live run even though I specified --dry-run as the last part of the command like this `php foo.php arg1 --dry-run`: getopt() did NOT include dry-run in its list of options resulting in my script executing a live run.
Be sure to wrap your head around this PHP jewel that took me a while to comprehend:
The returned array will contain a boolean FALSE for options that HAVE been specified.
Because why use TRUE to indicate "yes, it's there" when you can also use FALSE for that purpose, right? This is completely counter-intuitive and is most certainly only ever possible in PHP-land.
$opts = getopt('', $params = ['ogrn:','inn:','kpp::','host:','port:','user:','pass:','path:','pattern:']) + ['kpp' => 0,'port' => 21,'path' => '/','pattern' => '.+\.dbf'];
array_map(function ($param) use ($opts) {
$matches = [];
if ((bool)preg_match('/(?<param>[^:\s]+)\b:$/sU', $param, $matches)
&& (!array_key_exists($matches['param'], $opts) || empty($opts[$matches['param']])))
die(sprintf('<prtg><error>1</error><text>%s not set</text></text></error></prtg>', $matches['param']));
}, $params);
getopt() simply ignores unnecessary options specified in argv.
Many times, it does not work well to handle errors in command line.
A package PEAR::Console_Getopt can handle this problem, but it requires additonal installation.
GNU getopt(1) does well at shell level.
Following is my extended getopt() can detect unnecessary options:
<?php
function getoptex($sopt, $lopt, &$ind)
{
global $argv, $argc;
$sopts = getopt($sopt, $lopt);
$sopts_cnt = count($sopts); // single-option count based on original sopt
$asopt = $sopt . implode("", range("a", "z")) . implode("", range("A", "Z")) . implode("", range("0", "9"));
$asopts = getopt($asopt, $lopt);
$asopts_cnt = count($asopts); // actual single-option count including all single options even if is not listed as sopt
$lopt_trim = array();
foreach ($lopt as $o) {
$lopt_trim[] = trim($o, ":");
}
$alopts_cnt = 0;
$alopts_flag = true;
for ($i = 1; $i < $argc; $i++) {
if ($argv[$i] === "--") { // end of option
break;
}
if (strpos($argv[$i], "--") === 0) { // actual long-option
$alopts_cnt++;
$o = substr($argv[$i], 2);
if (! in_array($o, $lopt_trim)) { // but it is not listed as lopt
$alopts_flag = false;
} else {
if (in_array(($o . ":"), $lopt)) { // if the option requires value
$i++; // assume next is the value
if ($i >= $argc) { // and the value is missing
$alopts_flag = false;
break;
}
}
}
}
}
//var_dump($sopts, $asopts, $lopts, $alopts_cnt, $alopts_flag);
if ($sopts_cnt != $asopts_cnt || (! $alopts_flag)) {
return false;
} else {
return getopt($sopt, $lopt, $ind);
}
}
?>
Unfortunately, even using Example #4 do not allow to easily detect a bad -x or --xx argument as the last -x or --xx is always “eaten” even if it is bad:
If I use this (Example #4) :
<?php
// Script example.php
$rest_index = null;
$opts = getopt('a:b:', [], $rest_index);
$pos_args = array_slice($argv, $rest_index);
var_dump($pos_args);
?>
shell> php example.php -a 1 -b 2
shell> php example.php -a 1 -b 2 --test
shell> php example.php -a 1 -tb 2
All return the same result (-t and --test not defined) :
array(0) {
}
(last one use combining single letters, making user testing much much more complicated)
> This function will return an array of option / argument pairs, or false on failure.
I note that on my PHP 7.4 installation, getopt returns an empty array for no options specified, not FALSE as the doc states. Although "failure" is rather non-specific. Maybe that doesn't include the condition of no options.
This documentation never really explains the logic behind $short_options and just expects that you get it from reading the examples.
So if you are like me and start to think that the order of letters between the ":" characters has anything to say, think simpler.
It really is...
- every letter in the string will be allowed as a parameter,
- if that letter has ONE colon after it, then it will require a value
- if it has TWO colons, then it can accept a value
- the order of the letters does not matter at all as long as the colons are where they belong.
That means that these two examples are the same: "ab::c:def:" <-> "adec:f:b::"
As noted the options not required or optional (parameter does not accept any value) only returns the index key with a value of FALSE when provided as an argument. That is counter-intuitive to how the option will likely be used, so simply leverage the keys existence and reset the variable's index for that option:
<?php
$options = getopt('', ['update', 'insert']);
$options['update'] = array_key_exists('update', $options);
$options['insert'] = array_key_exists('insert', $options);
var_dump($options);
?>
shell> php testfile.php --insert
array(2) {
["update"]=>
bool(false)
["insert"]=>
bool(true)
}
Note that if you are mangling $argv separate from getopt(), that getopt() expects $argv to start with the command name in $argv[0]. So if you've shifted $argv, getopt() will start parsing at the second token, which means it will either miss the first option, or start parsing on the first option's value, breaking parsing.
$cmd = array_shift($argv);
$key_id=array_shift($argv);
array_unshift($argv,"");
$opts = getopt("a:b:c:");
getopt() skips over $argv[0] to start its parsing at $argv[1]. It doesn't really matter what is in $argv[0].