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',
);

服务提供器会自动注册一个别名，但如果你想知道，这就是它

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

用法

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

初始化一个新命令

这可以通过在服务提供器中注册的快捷方式来完成

$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 进行单元测试的更多信息，请参阅以下文档

netson / l4shell

维护者

详细信息