选项解析器¶
- class Cake\Console\ConsoleOptionParser¶
控制台应用程序通常使用选项和参数作为从终端获取信息到命令的主要方式。
定义选项解析器¶
命令和 Shell 提供了一个 buildOptionParser($parser) 钩子方法，您可以使用它来定义命令的选项和参数
protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser
{
// Define your options and arguments.
// Return the completed parser
return $parser;
}
Shell 类使用 getOptionParser() 钩子方法来定义它们的选项解析器
public function getOptionParser()
{
// Get an empty parser from the framework.
$parser = parent::getOptionParser();
// Define your options and arguments.
// Return the completed parser
return $parser;
}
使用参数¶
- Cake\Console\ConsoleOptionParser::addArgument($name, $params = [])¶
位置参数在命令行工具中经常使用，ConsoleOptionParser 允许您定义位置参数，以及将其设置为必填参数。您可以使用 $parser->addArgument(); 一次添加一个参数，或者使用 $parser->addArguments(); 一次添加多个参数。
$parser->addArgument('model', ['help' => 'The model to bake']);
创建参数时，您可以使用以下选项：
help用于显示此参数的帮助文本。required该参数是否为必填参数。index参数的索引，如果不定义，参数将被放在参数的末尾。如果您两次定义相同的索引，第一个选项将被覆盖。choices此参数的有效选择数组。如果为空，所有值都是有效的。当 parse() 遇到无效值时，将引发异常。
标记为必填参数的参数在解析命令时，如果省略，将会抛出异常。所以您不必在 shell 中处理它。
添加多个参数¶
- Cake\Console\ConsoleOptionParser::addArguments(array $args)¶
如果您有一个包含多个参数的数组，可以使用 $parser->addArguments() 一次添加多个参数。
$parser->addArguments([
'node' => ['help' => 'The node to create', 'required' => true],
'parent' => ['help' => 'The parent node', 'required' => true],
]);
与 ConsoleOptionParser 上的所有构建器方法一样，addArguments 可以用作流畅方法链的一部分。
验证参数¶
创建位置参数时，可以使用 required 标志来指示调用 shell 时必须存在参数。此外，您可以使用 choices 来强制参数来自有效选择列表
$parser->addArgument('type', [
'help' => 'The type of node to interact with.',
'required' => true,
'choices' => ['aro', 'aco'],
]);
以上将创建一个必填参数，并对输入进行验证。如果参数缺失或值不正确，将会抛出异常，shell 将被停止。
使用选项¶
- Cake\Console\ConsoleOptionParser::addOption($name, array $options = [])¶
选项或标志用于命令行工具，为命令提供无序的键值参数。选项可以定义详细和简短的别名。它们可以接受值（例如 --connection=default）或布尔型选项（例如 --verbose）。选项使用 addOption() 方法定义
$parser->addOption('connection', [
'short' => 'c',
'help' => 'connection',
'default' => 'default',
]);
以上允许您在调用 shell 时使用 cake myshell --connection=other、cake myshell --connection other 或 cake myshell -c other。
布尔开关不接受或使用值，它们的存在只是在解析的参数中启用它们
$parser->addOption('no-commit', ['boolean' => true]);
此选项在使用时，例如 cake mycommand --no-commit something，其值为 true，而 ‘something’ 将被视为位置参数。
创建选项时，可以使用以下选项来定义选项的行为
short- 此选项的单字母变体，如果没有，则不定义。help- 此选项的帮助文本。用于生成选项的帮助信息。default- 此选项的默认值。如果未定义，则默认值为true。boolean- 选项不使用任何值，它只是一个布尔开关。默认为false。multiple- 选项可以多次提供。启用此选项时，解析后的选项将是一个值数组。choices- 此选项的有效选择数组。如果为空，所有值都是有效的。当 parse() 遇到无效值时，将引发异常。
添加多个选项¶
- Cake\Console\ConsoleOptionParser::addOptions(array $options)¶
如果您有一个包含多个选项的数组，可以使用 $parser->addOptions() 一次添加多个选项。
$parser->addOptions([
'node' => ['short' => 'n', 'help' => 'The node to create'],
'parent' => ['short' => 'p', 'help' => 'The parent node'],
]);
与 ConsoleOptionParser 上的所有构建器方法一样，addOptions 可以用作流畅方法链的一部分。
验证选项¶
选项可以像位置参数一样提供一组选择。当选项定义了选择时，这些选择是该选项唯一有效的选择。所有其他值将引发 InvalidArgumentException
$parser->addOption('accept', [
'help' => 'What version to accept.',
'choices' => ['working', 'theirs', 'mine'],
]);
使用布尔选项¶
选项可以定义为布尔选项，这在您需要创建一些标志选项时很有用。与具有默认值的选项类似，布尔选项始终将自身包含到解析后的参数中。当标志存在时，它们被设置为 true，当它们不存在时，它们被设置为 false
$parser->addOption('verbose', [
'help' => 'Enable verbose output.',
'boolean' => true
]);
以下选项将在解析后的参数中始终具有值。当不包含时，其默认值为 false，当定义时，其值为 true。
从数组构建 ConsoleOptionParser¶
- Cake\Console\ConsoleOptionParser::buildFromArray($spec)¶
选项解析器也可以定义为数组。在数组中，您可以为 arguments、options、description 和 epilog 定义键。参数和选项的值应遵循 Cake\Console\ConsoleOptionParser::addArguments() 和 Cake\Console\ConsoleOptionParser::addOptions() 使用的格式。您也可以单独使用 buildFromArray 来构建选项解析器
public function getOptionParser()
{
return ConsoleOptionParser::buildFromArray([
'description' => [
__("Use this command to grant ACL permissions. Once executed, the "),
__("ARO specified (and its children, if any) will have ALLOW access "),
__("to the specified ACO action (and the ACO's children, if any).")
],
'arguments' => [
'aro' => ['help' => __('ARO to check.'), 'required' => true],
'aco' => ['help' => __('ACO to check.'), 'required' => true],
'action' => ['help' => __('Action to check')],
],
]);
}
合并选项解析器¶
- Cake\Console\ConsoleOptionParser::merge($spec)¶
构建组命令时，您可能想要组合多个解析器
$parser->merge($anotherParser);
请注意，每个解析器的参数顺序必须相同，并且选项也必须兼容才能使其工作。因此，不要使用不同的键来表示不同的东西。
从 Shell 获取帮助¶
通过使用选项解析器定义您的选项和参数，CakePHP 可以自动生成基本的帮助信息，并为您的每个命令添加 --help 和 -h。使用这些选项之一将允许您查看生成的帮助内容
bin/cake bake --help
bin/cake bake -h
这两种方法都会生成 bake 的帮助信息。您还可以获取嵌套命令的帮助
bin/cake bake model --help
bin/cake bake model -h
以上内容会为您提供 bake 的 model 命令的特定帮助信息。
获取 XML 格式的帮助¶
在构建自动化工具或需要与 CakePHP shell 命令交互的开发工具时，将帮助信息以机器可解析的格式提供非常有用。通过在请求帮助时提供 xml 选项，您可以将帮助内容作为 XML 返回
cake bake --help xml
cake bake -h xml
以上内容将返回一个包含所选 shell 的生成的帮助信息、选项和参数的 XML 文档。示例 XML 文档将如下所示
<?xml version="1.0"?>
<shell>
<command>bake fixture</command>
<description>Generate fixtures for use with the test suite. You can use
`bake fixture all` to bake all fixtures.</description>
<epilog>
Omitting all arguments and options will enter into an interactive
mode.
</epilog>
<options>
<option name="--help" short="-h" boolean="1">
<default/>
<choices/>
</option>
<option name="--verbose" short="-v" boolean="1">
<default/>
<choices/>
</option>
<option name="--quiet" short="-q" boolean="1">
<default/>
<choices/>
</option>
<option name="--count" short="-n" boolean="">
<default>10</default>
<choices/>
</option>
<option name="--connection" short="-c" boolean="">
<default>default</default>
<choices/>
</option>
<option name="--plugin" short="-p" boolean="">
<default/>
<choices/>
</option>
<option name="--records" short="-r" boolean="1">
<default/>
<choices/>
</option>
</options>
<arguments>
<argument name="name" help="Name of the fixture to bake.
Can use Plugin.name to bake plugin fixtures." required="">
<choices/>
</argument>
</arguments>
</shell>
自定义帮助输出¶
您可以通过添加描述和尾注来进一步丰富生成的帮助内容。
设置描述¶
- Cake\Console\ConsoleOptionParser::setDescription($text)¶
描述显示在参数和选项信息之上。通过传入数组或字符串，您可以设置描述的值
// Set multiple lines at once
$parser->setDescription(['line one', 'line two']);
// Read the current value
$parser->getDescription();
设置尾注¶
- Cake\Console\ConsoleOptionParser::setEpilog($text)¶
获取或设置选项解析器的尾注。尾注显示在参数和选项信息之后。通过传入数组或字符串，您可以设置尾注的值
// Set multiple lines at once
$parser->setEpilog(['line one', 'line two']);
// Read the current value
$parser->getEpilog();