vcn/commando

PHP CLI 命令行风格

维护者

详细信息

github.com/vcn/commando

主页

源代码

安装次数: 4,918

依赖项: 0

建议者: 0

安全性: 0

星星: 0

关注者: 2

分支: 80

v0.2.8 2015-12-03 12:42 UTC

Requires

MIT 8841d104598828c976e5ed80f405f594046cf258

  • Nate Good <me.woop@nategood.com>
  • Gerrit Drost <gdrost.woop@vcn.nl>

clicommandcommand lineautomationcommand line interfacescripting

This package is auto-updated.

Last update: 2024-09-06 09:42:11 UTC

README

从 https://github.com/nategood/commando 分支，因为该仓库似乎已被遗弃，我需要一个新的版本进行标记。

优雅的 PHP CLI 库

Build Status

Commando 是一个 PHP 命令行界面库，它美化和简化了为命令行使用而编写的 PHP 脚本的编写。

为什么？

PHP 的 $argv 魔术变量和全局 $_SERVER['argv'] 让我感到不舒服，getopt 也没有好太多，而大多数其他 PHP CLI 库都过于 OOP 浮肿。Commando 以最小的开销专注于业务，在处理 CLI 输入时移除常见的样板代码，同时提供一个干净、易读的接口。

安装

Commando 需要您运行 PHP 5.3 或更高版本。

Commando 遵循 PSR-0 标准，可以使用 Composer 安装。将 nategood/commando 添加到您的 composer.json

"require": {
    "nategood/commando": "*"
}

如果您是 Composer 新手...

目前，通过 Composer 安装是唯一支持的方式。

示例

以下是一个 PHP Commando 脚本示例，它展示了 Commando 的功能。假设它在一个名为 hello.php 的文件中。

<?php

require_once 'vendor/autoload.php';

$hello_cmd = new Commando\Command();

// Define first option
$hello_cmd->option()
    ->require()
    ->describedAs('A person\'s name');

// Define a flag "-t" a.k.a. "--title"
$hello_cmd->option('t')
    ->aka('title')
    ->describedAs('When set, use this title to address the person')
    ->must(function($title) {
        $titles = array('Mister', 'Mr', 'Misses', 'Mrs', 'Miss', 'Ms');
        return in_array($title, $titles);
    })
    ->map(function($title) {
        $titles = array('Mister' => 'Mr', 'Misses' => 'Mrs', 'Miss' => 'Ms');
        if (array_key_exists($title, $titles))
            $title = $titles[$title];
        return "$title. ";
    });

// Define a boolean flag "-c" aka "--capitalize"
$hello_cmd->option('c')
    ->aka('capitalize')
    ->aka('cap')
    ->describedAs('Always capitalize the words in a name')
    ->boolean();

$name = $hello_cmd['capitalize'] ? ucwords($hello_cmd[0]) : $hello_cmd[0];

echo "Hello {$hello_cmd['title']}$name!", PHP_EOL;

运行它

> php hello.php Nate
Hello, Nate!

> php hello.php --capitalize nate
Hello, Nate!

> php hello.php -c -t Mr 'nate good'
Hello, Mr. Nate Good!

需要注意的事项

  • Commando 实现 ArrayAccess，因此当您需要检索其值时，它表现得就像一个数组
  • 对于 "匿名"（即非命名的标志）参数，我们根据它们的数字索引来访问它们
  • 我们可以通过标志的名称或其别名在数组中访问选项值
  • 我们可以在选项定义中直接使用闭包来执行验证和映射操作

内建的帮助

Commando 内置自动 --help 支持。使用此标志调用您的脚本将打印出一个基于您的选项定义和 Commando 设置的漂亮的帮助页面。如果您定义了一个别名为 'help' 的选项，它将覆盖此内置支持。

help screenshot

错误消息

默认情况下，Commando 将捕获解析过程中发生的异常。Commando 会将格式化、用户友好的错误消息打印到标准错误，并以代码 1 退出。如果您希望 Commando 在这些情况下抛出异常，请在您的 Command 实例上调用 doNotTrapErrors 方法。

error screenshot

命令方法

这些选项在 "命令" 级别上工作

useDefaultHelp (bool help)

Commando 的默认行为是提供一个 --help 选项，该选项将输出一个基于您的选项定义生成的有用帮助页面。通过调用 useDefaultHelp(false) 禁用此功能。

setHelp (string help)

将附加到帮助页面的文本。使用此功能在高级上描述命令，以及一些命令的示例用法。

beepOnError (bool beep=true)

当发生错误时，打印字符使终端 "嘟嘟"。

getOptions

返回一个包含为命令提供的每个选项的 Option 数组。

getFlags

返回一个仅包含为命令提供的标志的 Option 数组。

getArguments

返回一个数组，其中只包含命令提供的参数的Options。数组的顺序与参数的顺序相同。

getFlagValues

返回命令提供的参数的关联数组值。例如：array('f' => 'value1')。

getArgumentValues

返回命令提供的参数的值数组。例如：array('value1', 'value2')。

命令选项定义方法

这些选项在“选项”级别上工作，即使它们被链接到一个Command实例

option (mixed $name = null)

别名：o

定义一个新选项。当设置name时，该选项将是一个命名的“标志”选项。可以是短形式选项（例如，选项-f的缩写为f）或长形式（例如，选项--foo的缩写为foo）。如果没有定义name，则选项是一个匿名参数，并且未来将通过其位置引用。

flag (string $name)

与option相同，但只能用于定义“标志”类型选项（即必须在命令行上指定带有-标志的选项）。

argument ()

与option相同，但只能用于定义“参数”类型选项（即不使用-标志在命令行上指定的选项）。

alias (string $alias)

别名：a，aka

为命名选项添加别名。此方法可以多次调用以添加多个别名。

description (string $description)

别名：d，describe，describedAs

描述此选项的文本。此文本将用于构建“帮助”页面，因此它是面向最终用户的。

require (bool $require)

别名：r，required

要求指定此标志

needs (string|array $options)

别名：无

要求设置其他$options才能使用此选项。

must (Closure $rule)

别名：无

定义一个规则以验证输入。接受一个函数，该函数接受一个字符串$value，并返回一个布尔值，表示$value是否有效。

map (Closure $map)

别名：cast，castTo

对选项的值执行映射操作。接受一个函数，该函数接受一个字符串$value，并返回混合类型（你可以映射到你想要的任何类型）。

referToAs (string $name)

别名：title，referredToAs

添加一个名称来通过名称引用参数选项。使帮助文档对于匿名“参数”选项更加清晰。

boolean ()

别名：无

指定标志是布尔类型标志。

default (mixed $defaultValue)

别名：defaultsTo

如果未指定值，则默认为$defaultValue。

对于boolean()类型标志，当标志存在时，此选项的值是$defaultValue的否定。也就是说，如果您有一个默认值为true的标志-b，当-b作为命令行标志存在时，该选项的值将是false。

file ()

别名：expectsFile

为此选项指定的值必须是有效的文件路径。当使用相对路径时，将转换为完全合格的文件路径，并且可选地支持globbing。请参阅file.php示例。

贡献

Commando强烈鼓励提交拉取请求。提交拉取请求时，请

  • 所有拉取请求应针对dev分支（而不是master）
  • 确保您的代码遵循在PSR-1和PSR-2中规定的编码标准
  • 确保您为您的更改添加适当的测试覆盖率
  • 通过phpunit ./tests在测试目录中运行所有单元测试
  • 在适当的位置包含注释，并添加描述性的拉取请求消息

灵感

在MIT许可证下发布。

变更日志

v0.2.7

  • getOptions已添加（附带一些更好的文档）

v0.2.6

  • 添加了对“needs”的支持，用于定义选项之间的依赖关系（感谢@enygma）PR #31
  • 修复了与长参数名称相关的问题问题 #30

v0.2.5

  • 修复了布尔选项默认值的问题，布尔选项自动默认为false（不太可能，但可能是破坏性更改）PR #19

v0.2.4

  • 添加了定义选项默认值的能力

v0.2.3

  • 改进了帮助格式化PR #12

v0.2.2

  • 修复了打印重复帮助的bug PR #10

v0.2.1

  • 添加了对要求选项为有效文件路径或glob的支持
  • 返回一个完全限定的文件路径名（例如，转换相对路径）
  • 在glob的情况下返回文件路径数组
  • 请参阅示例目录中的file.php示例

v0.2.0

此更新的主要目标是更好地区分标志选项和参数选项。在Commando中，标志是我们定义的选项，当它们在命令行中指定时需要名称。参数是没有以这种方式命名的选项。在下面的示例中，'-f'和'--long'在Commando术语中被描述为“标志”类型选项，分别具有'value1'和'value2'的值，而value3、value4和value5被描述为“参数”类型选项。

php command.php -f value1 --long value2 value3 value4 value5
  • 添加了Command::getArguments()以返回一个“参数”类型的Option数组（请参阅argumentsVsFlags.php示例）
  • 添加了Command::getFlags()以返回一个“标志”类型的Option数组（请参阅argumentsVsFlags.php示例）
  • 添加了Command::getArgumentValues()以返回“参数”的所有值的数组
  • 添加了Command::getFlagValues()以返回所有“标志”值的数组
  • Command现在实现了Iterator接口，将迭代所有选项，从参数开始，然后按字母顺序继续到标志
  • 现在可以定义选项，除了使用Command::option($name)外，还可以使用Command::flag($name)和Command::argument()
  • 添加了添加“标题”的能力，以便通过名称引用参数，使帮助文档更加清晰（运行help.php示例）
  • 清理了生成的帮助文档
  • 修复了显示错误时额外颜色化红色行的bug

v0.1.4

  • 修复了具有多个单词的选项值的bug

v0.1.3

  • 在终端中添加了蜂鸣声支持
  • 添加了Commando::beepOnError()

v0.1.2

  • 更新了终端，以正确使用tput

Bitdeli Badge