README

这个 Laravel 4 包是一个简单的 shell 命令（exec）包装器类。它允许您在不失去编写单元测试能力的情况下，向您的应用程序添加 exec() 命令。该包附带了一个 Facade，因此使用 Mockery 进行测试非常简单。

此包在 Windows 系统上无法工作。

安装

简单使用 composer

$ php composer.phar require netson/l4shell:1.2.*

或手动将需求添加到 composer.json 文件中

"require": {
     "netson/l4shell": "1.2.x"
}

包成功加载后，您必须将其添加到 Service Providers 数组中

// app/config/app.php
'providers' => array(
	...
	'Netson\L4shell\L4shellServiceProvider',
);

Service Provider 会自动注册别名，但以防您想知道，这就是它

'L4shell' => 'Netson\L4shell\Facades\Command'

用法

此包将整个命令（使用 escapeshellcmd()）和每个单独的参数（使用 escapdeshellarg()）进行转义。几乎所有方法都允许对象链，以便于设置。

初始化新的命令

这可以通过在 Service Provider 中注册的快捷方式完成

$command = L4shell::get();

或者通过手动创建一个新的对象

$command = new \Netson\L4shell\Command("command", array("arg1", "arg2"));

使用 get() 方法将初始化一个空的命令对象，并在执行命令之前需要您使用 setCommand() 和 setArguments() 方法（可选）。

示例命令：无参数

$command = L4shell::get();
$result = $command->setCommand('hostname')->execute();

如果命令执行成功，将返回命令的输出。如果命令无法执行，将抛出异常，包括命令的错误消息（除了使用 sendToDevNull() 方法；见下文）。

示例命令：带参数

添加参数时，请确保添加正确数量的占位符（sprintf 格式），否则将抛出异常。

$command = L4shell::get();
$result = $command->setCommand('hostname %s')->setArguments(array("-s"))->execute();

默认情况下，当您调用 setArguments() 方法时，任何现有的参数都将被替换，以避免在一系列连续命令中堆叠参数。但是，如果您想分步添加它们，可以通过向该方法传递第二个（可选）布尔参数来实现。

$command = L4shell::get();
$command->setCommand('ls %s %s')->setArguments(array("-a"));
// do something else ...
$command->setArguments(array("-l"), true); // add the optional second argument to keep existing arguments
$result = $command->execute();

如果您想手动清除任何现有参数，请使用以下方法

$command = L4shell::get();
$command->clearArguments();

示例命令：将输出发送到 /dev/null

该包有简单的方法将命令的输出发送到 /dev/null，因为您可能只对退出状态感兴趣，而不是输出文本。将输出发送到 /dev/null 将使任何输出消息变得无用，但当然退出代码仍然可用，并且在发生错误时将抛出异常。

$command = L4shell::get();
$result = $command->setCommand("hostname")->sendToDevNull()->execute(); // will return exit code (0), but no output message

示例命令：启用所有命令的日志记录

L4shell 允许您轻松地将所有对 shell 命令的调用记录到默认的 Laravel 日志。默认情况下，日志记录是启用的。日志记录使用默认的 Laravel 4 日志包（Monolog）。

对于每个成功的命令，将出现 3 或 4 条日志行，具体取决于是否设置了参数

设置命令 ...
设置参数 ...（可选）
执行命令 ...
命令成功执行

要禁用日志记录，发布包的配置文件

$ php artisan config:publish netson/l4shell

然后更改 app/config/packages/netson/l4shell/config.php 文件中的 enable_logging 选项。

或者，您可以在运行时更改日志设置

$command = L4shell::get();
$result = $command->setLogging(true)->setCommand("hostname")->execute();

设置和取消设置执行路径

如果您希望从特定目录执行命令，可以使用以下方法

$command = L4shell::get();
$result = $command->setExecutionPath("/path/to/your/folder")->setCommand("ls")->execute();

执行路径是一个静态变量，这意味着在这种情况下，如果只设置一次，将影响之后执行的所有命令。

注意： 执行路径在执行命令之前被更改，并在命令执行后立即恢复到原始设置。这样，您不必记住恢复工作目录，并且它不会影响之后运行的任何脚本。

如果您想取消设置执行路径，只需调用该方法而不带任何参数

$command = L4shell::get();
$result = $command->setExecutionPath()->setCommand("ls")->execute();

设置和取消设置可执行路径

如果包含您的可执行文件的文件夹不在执行命令的用户路径中，您可以使用以下方法

$command = L4shell::get();
$result = $command->setExecutablePath("/usr/bin")->setCommand("ls")->execute();

这将有效地将您的命令从简单的 $ ls 变为 $ /usr/bin/ls。这同样是一个静态变量，意味着设置将跨越命令持久存在。

如果您想取消设置可执行路径（例如，从本地目录运行命令），只需调用该方法不带任何参数

$command = L4shell::get();
$result = $command->setExecutablePath()->setCommand("ls")->execute();

防止某些字符被转义

当您有一个特定的需要使用通常会被 escapeshellcmd() 或 escapeshellarg() 函数转义的字符的 shell 命令时，您可以使用 setAllowedCharacters() 方法。该方法接受一个数组，其中的字符不会被 L4shell 转义

$command = L4shell::setCommand('find ./ -maxdepth 1 -name %s')->setArguments(array("*.txt"))->setAllowedCharacters(array("*"));
// returned with allowed characters: find ./ -maxdepth 1 -name '*.txt'
// returned without allowed characters: find ./ -maxdepth 1 -name '\*.txt'

由于此方法完全绕过了潜在危险字符的转义，请务必谨慎使用此方法！！

单元测试

使用 L4shell 时，对模块/包进行单元测试很简单。只需在测试中使用 Mockery 风格的调用即可

public function testSomething ()
{
    L4shell::shouldReceive('get')->once();
    L4shell::shouldReceive('execute')->once()->andReturn("your message");
}
public function tearDown ()
{
    \Mockery::close();
}

有关使用 Laravel 4 进行单元测试的更多信息，请查看以下文档

sprik / l4shell

维护者

详细信息