Appearance
进程
简介
Laravel 为 Symfony Process 组件 提供了一个富有表现力的、最小化的 API,允许你从 Laravel 应用程序中方便地调用外部进程。Laravel 的进程功能专注于最常见的用例和出色的开发者体验。
调用进程
要调用一个进程,你可以使用 Process
Facade提供的 run
和 start
方法。run
方法将调用一个进程并等待进程执行完成,而 start
方法用于异步进程执行。我们将在本文档中检查这两种方法。首先,让我们看看如何调用一个基本的同步进程并检查其结果:
php
use Illuminate\Support\Facades\Process;
$result = Process::run('ls -la');
return $result->output();
当然,Process
Facade的 run
方法返回的 Illuminate\Contracts\Process\ProcessResult
实例提供了各种有用的方法,可以用于检查进程结果:
php
$result = Process::run('ls -la');
$result->successful();
$result->failed();
$result->exitCode();
$result->output();
$result->errorOutput();
抛出异常
如果你有一个进程结果并且希望在退出代码大于零(即表示失败)时抛出一个 Illuminate\Process\Exceptions\ProcessFailedException
实例,你可以使用 throw
和 throwIf
方法。如果进程没有失败,将返回进程结果实例:
php
$result = Process::run('ls -la')->throw();
$result = Process::run('ls -la')->throwIf($condition);
进程选项
当然,在调用进程之前,你可能需要自定义进程的行为。幸运的是,Laravel 允许你调整各种进程特性,例如工作目录、超时和环境变量。
工作目录路径
你可以使用 path
方法指定进程的工作目录。如果没有调用此方法,进程将继承当前执行的 PHP 脚本的工作目录:
php
$result = Process::path(__DIR__)->run('ls -la');
输入
你可以通过 "标准输入" 向进程提供输入,使用 input
方法:
php
$result = Process::input('Hello World')->run('cat');
超时
默认情况下,进程在执行超过 60 秒后将抛出一个 Illuminate\Process\Exceptions\ProcessTimedOutException
。但是,你可以通过 timeout
方法自定义此行为:
php
$result = Process::timeout(120)->run('bash import.sh');
或者,如果你想完全禁用进程超时,你可以调用 forever
方法:
php
$result = Process::forever()->run('bash import.sh');
idleTimeout
方法可用于指定进程在没有返回任何输出的情况下最多可以运行多少秒:
php
$result = Process::timeout(60)->idleTimeout(30)->run('bash import.sh');
环境变量
环境变量可以通过 env
方法提供给进程。调用的进程还将继承你的系统定义的所有环境变量:
php
$result = Process::forever()
->env(['IMPORT_PATH' => __DIR__])
->run('bash import.sh');
如果你希望从调用的进程中删除继承的环境变量,你可以为该环境变量提供 false
值:
php
$result = Process::forever()
->env(['LOAD_PATH' => false])
->run('bash import.sh');
TTY 模式
tty
方法可用于为你的进程启用 TTY 模式。TTY 模式将进程的输入和输出连接到你的程序的输入和输出,允许你的进程打开像 Vim 或 Nano 这样的编辑器作为进程:
php
Process::forever()->tty()->run('vim');
进程输出
如前所述,进程输出可以使用进程结果的 output
(stdout)和 errorOutput
(stderr)方法访问:
php
use Illuminate\Support\Facades\Process;
$result = Process::run('ls -la');
echo $result->output();
echo $result->errorOutput();
但是,也可以通过将闭包作为第二个参数传递给 run
方法来实时收集输出。该闭包将接收两个参数:"输出类型"(stdout
或 stderr
)和输出字符串本身:
php
$result = Process::run('ls -la', function (string $type, string $output) {
echo $output;
});
Laravel 还提供了 seeInOutput
和 seeInErrorOutput
方法,这些方法提供了一种方便的方式来确定给定的字符串是否包含在进程的输出中:
php
if (Process::run('ls -la')->seeInOutput('laravel')) {
// ...
}
禁用进程输出
如果你的进程正在写入你不感兴趣的大量输出,你可以通过完全禁用输出检索来节省内存。要实现这一点,在构建进程时调用 quietly
方法:
php
use Illuminate\Support\Facades\Process;
$result = Process::quietly()->run('bash import.sh');
管道
有时你可能希望将一个进程的输出作为另一个进程的输入。这通常被称为"将一个进程的输出管道到另一个进程"。Process
Facade提供的 pipe
方法可以轻松实现这一点。pipe
方法将同步执行管道中的进程并返回管道中最后一个进程的进程结果:
php
use Illuminate\Process\Pipe;
use Illuminate\Support\Facades\Process;
$result = Process::pipe(function (Pipe $pipe) {
$pipe->command('cat example.txt');
$pipe->command('grep -i "laravel"');
});
if ($result->successful()) {
// ...
}
如果你不需要自定义管道中的各个进程,你甚至可以将一个命令字符串数组直接传递给 pipe
方法:
php
$result = Process::pipe([
'cat example.txt',
'grep -i "laravel"',
]);
可以通过将闭包作为第二个参数传递给 pipe
方法来实时收集管道中进程的输出。该闭包将接收两个参数:"输出类型"(stdout
或 stderr
)和输出字符串本身:
php
$result = Process::pipe(function (Pipe $pipe) {
$pipe->command('cat example.txt');
$pipe->command('grep -i "laravel"');
}, function (string $type, string $output) {
echo $output;
});
Laravel 还允许你通过 as
方法为管道中的每个进程分配字符串键。此键还将传递给传递给 pipe
方法的输出闭包,允许你确定输出属于哪个进程:
php
$result = Process::pipe(function (Pipe $pipe) {
$pipe->as('first')->command('cat example.txt');
$pipe->as('second')->command('grep -i "laravel"');
})->start(function (string $type, string $output, string $key) {
// ...
});
异步进程
虽然 run
方法是同步调用进程,但 start
方法可用于异步调用进程。这允许你的应用程序在后台运行进程的同时继续执行其他任务。一旦进程被调用,你可以使用 running
方法来确定进程是否仍在运行:
php
$process = Process::timeout(120)->start('bash import.sh');
while ($process->running()) {
// ...
}
$result = $process->wait();
正如你可能已经注意到的,你可以调用 wait
方法等待进程执行完成并检索进程结果实例:
php
$process = Process::timeout(120)->start('bash import.sh');
// ...
$result = $process->wait();
进程 ID 和信号
id
方法可用于检索正在运行的进程的操作系统分配的进程 ID:
php
$process = Process::start('bash import.sh');
return $process->id();
你可以使用 signal
方法向正在运行的进程发送"信号"。预定义的信号常量列表可以在 PHP 文档 中找到:
php
$process->signal(SIGUSR2);
异步进程输出
当异步进程正在运行时,你可以使用 output
和 errorOutput
方法访问其当前的整个输出;但是,你可以使用 latestOutput
和 latestErrorOutput
访问自上次检索输出以来发生的进程输出:
php
$process = Process::timeout(120)->start('bash import.sh');
while ($process->running()) {
echo $process->latestOutput();
echo $process->latestErrorOutput();
sleep(1);
}
与 run
方法一样,也可以通过将闭包作为第二个参数传递给 start
方法来实时收集异步进程的输出。该闭包将接收两个参数:"输出类型"(stdout
或 stderr
)和输出字符串本身:
php
$process = Process::start('bash import.sh', function (string $type, string $output) {
echo $output;
});
$result = $process->wait();
并发进程
Laravel 还可以轻松管理一组并发的异步进程,允许你轻松同时执行多个任务。要开始,调用 pool
方法,该方法接受一个接收 Illuminate\Process\Pool
实例的闭包。
在此闭包中,你可以定义属于池的进程。一旦通过 start
方法启动了进程池,你可以通过 running
方法访问正在运行的进程的 集合:
php
use Illuminate\Process\Pool;
use Illuminate\Support\Facades\Process;
$pool = Process::pool(function (Pool $pool) {
$pool->path(__DIR__)->command('bash import-1.sh');
$pool->path(__DIR__)->command('bash import-2.sh');
$pool->path(__DIR__)->command('bash import-3.sh');
})->start(function (string $type, string $output, int $key) {
// ...
});
while ($pool->running()->isNotEmpty()) {
// ...
}
$results = $pool->wait();
如你所见,你可以等待池中的所有进程执行完成并解析它们的结果,使用 wait
方法。wait
方法返回一个可访问对象的数组,允许你通过其键访问池中每个进程的进程结果实例:
php
$results = $pool->wait();
echo $results[0]->output();
或者,为了提供更加表达性的语法,你可以使用 concurrently
方法启动异步进程池并立即等待其结果。这与 PHP 的数组解构功能结合使用时尤其有效:
php
[$first, $second, $third] = Process::concurrently(function (Pool $pool) {
$pool->path(__DIR__)->command('ls -la');
$pool->path(app_path())->command('ls -la');
$pool->path(storage_path())->command('ls -la');
});
echo $first->output();
命名池进程
使用数字键访问进程池结果并不是很表达性;因此,Laravel 允许你通过 as
方法为池中的每个进程分配字符串键。此键还将传递给传递给 start
方法的闭包,允许你确定输出属于哪个进程:
php
$pool = Process::pool(function (Pool $pool) {
$pool->as('first')->command('bash import-1.sh');
$pool->as('second')->command('bash import-2.sh');
$pool->as('third')->command('bash import-3.sh');
})->start(function (string $type, string $output, string $key) {
// ...
});
$results = $pool->wait();
return $results['first']->output();
池进程 ID 和信号
由于池的 running
方法提供了池中所有调用进程的集合,因此你可以轻松访问底层池进程 ID:
php
$processIds = $pool->running()->each->id();
并且,为了方便起见,你可以在进程池上调用 signal
方法向池中的每个进程发送信号:
php
$pool->signal(SIGUSR2);
测试
许多 Laravel 服务提供了功能,可以帮助你轻松快速地编写测试,而 Laravel 的进程服务也不例外。Process
Facade的 fake
方法允许你指示 Laravel 在调用进程时返回存根/虚拟结果。
伪造进程
为了探索 Laravel 伪造进程的能力,让我们想象一个调用进程的路由:
php
use Illuminate\Support\Facades\Process;
use Illuminate\Support\Facades\Route;
Route::get('/import', function () {
Process::run('bash import.sh');
return 'Import complete!';
});
在测试此路由时,我们可以通过在 Process
Facade上调用 fake
方法而不传递任何参数来指示 Laravel 对每个调用的进程返回一个伪造的、成功的进程结果。此外,我们甚至可以 断言 给定的进程是否"运行":
php
<?php
use Illuminate\Process\PendingProcess;
use Illuminate\Contracts\Process\ProcessResult;
use Illuminate\Support\Facades\Process;
test('process is invoked', function () {
Process::fake();
$response = $this->get('/import');
// Simple process assertion...
Process::assertRan('bash import.sh');
// Or, inspecting the process configuration...
Process::assertRan(function (PendingProcess $process, ProcessResult $result) {
return $process->command === 'bash import.sh' &&
$process->timeout === 60;
});
});
php
<?php
namespace Tests\Feature;
use Illuminate\Process\PendingProcess;
use Illuminate\Contracts\Process\ProcessResult;
use Illuminate\Support\Facades\Process;
use Tests\TestCase;
class ExampleTest extends TestCase
{
public function test_process_is_invoked(): void
{
Process::fake();
$response = $this->get('/import');
// Simple process assertion...
Process::assertRan('bash import.sh');
// Or, inspecting the process configuration...
Process::assertRan(function (PendingProcess $process, ProcessResult $result) {
return $process->command === 'bash import.sh' &&
$process->timeout === 60;
});
}
}
如前所述,调用 Process
Facade的 fake
方法将指示 Laravel 始终返回一个成功的进程结果且没有输出。但是,你可以轻松指定伪造进程的输出和退出代码,使用 Process
Facade的 result
方法:
php
Process::fake([
'*' => Process::result(
output: 'Test output',
errorOutput: 'Test error output',
exitCode: 1,
),
]);
伪造特定进程
正如你可能已经注意到的,Process
Facade允许你通过传递一个数组来为每个伪造进程指定不同的伪造结果。
数组的键应表示你希望伪造的命令模式,以及它们相关的结果。*
字符可用作通配符字符。任何没有被伪造的进程命令都将实际调用。你可以使用 Process
Facade的 result
方法构造存根/伪造这些命令的结果:
php
Process::fake([
'cat *' => Process::result(
output: 'Test "cat" output',
),
'ls *' => Process::result(
output: 'Test "ls" output',
),
]);
如果你不需要自定义伪造进程的退出代码或错误输出,你可能会发现将伪造进程结果指定为简单字符串更方便:
php
Process::fake([
'cat *' => 'Test "cat" output',
'ls *' => 'Test "ls" output',
]);
伪造进程序列
如果你正在测试的代码调用了多个具有相同命令的进程,你可能希望为每个进程调用分配不同的伪造进程结果。你可以通过 Process
Facade的 sequence
方法来实现这一点:
php
Process::fake([
'ls *' => Process::sequence()
->push(Process::result('First invocation'))
->push(Process::result('Second invocation')),
]);
伪造异步进程生命周期
到目前为止,我们主要讨论了使用 run
方法伪造同步进程。但是,如果你正在尝试测试与通过 start
调用的异步进程交互的代码,你可能需要一种更复杂的方式来描述你的伪造进程。
例如,让我们想象一个与异步进程交互的路由:
php
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Route;
Route::get('/import', function () {
$process = Process::start('bash import.sh');
while ($process->running()) {
Log::info($process->latestOutput());
Log::info($process->latestErrorOutput());
}
return 'Done';
});
为了正确伪造此进程,我们需要能够描述 running
方法应返回 true
的次数。此外,我们可能希望指定多行输出,这些输出应按顺序返回。为了实现这一点,我们可以使用 Process
Facade的 describe
方法:
php
Process::fake([
'bash import.sh' => Process::describe()
->output('First line of standard output')
->errorOutput('First line of error output')
->output('Second line of standard output')
->exitCode(0)
->iterations(3),
]);
让我们来看看上面的示例。使用 output
和 errorOutput
方法,我们可以指定多行输出,这些输出将按顺序返回。exitCode
方法可用于指定伪造进程的最终退出代码。最后,iterations
方法可用于指定 running
方法应返回 true
的次数。
可用的断言
如 前面讨论过的,Laravel 为你的功能测试提供了几个进程断言。我们将逐一讨论每个断言。
assertRan
断言给定的进程是否被调用:
php
use Illuminate\Support\Facades\Process;
Process::assertRan('ls -la');
assertRan
方法还接受一个闭包,该闭包将接收一个进程实例和一个进程结果,允许你检查进程的配置选项。如果此闭包返回 true
,断言将"通过":
php
Process::assertRan(fn ($process, $result) =>
$process->command === 'ls -la' &&
$process->path === __DIR__ &&
$process->timeout === 60
);
传递给 assertRan
闭包的 $process
是一个 Illuminate\Process\PendingProcess
实例,而 $result
是一个 Illuminate\Contracts\Process\ProcessResult
实例。
assertDidntRun
断言给定的进程是否未被调用:
php
use Illuminate\Support\Facades\Process;
Process::assertDidntRun('ls -la');
与 assertRan
方法一样,assertDidntRun
方法还接受一个闭包,该闭包将接收一个进程实例和一个进程结果,允许你检查进程的配置选项。如果此闭包返回 true
,断言将"失败":
php
Process::assertDidntRun(fn (PendingProcess $process, ProcessResult $result) =>
$process->command === 'ls -la'
);
assertRanTimes
断言给定的进程是否被调用了给定的次数:
php
use Illuminate\Support\Facades\Process;
Process::assertRanTimes('ls -la', times: 3);
assertRanTimes
方法还接受一个闭包,该闭包将接收一个进程实例和一个进程结果,允许你检查进程的配置选项。如果此闭包返回 true
且进程被调用了指定的次数,断言将"通过":
php
Process::assertRanTimes(function (PendingProcess $process, ProcessResult $result) {
return $process->command === 'ls -la';
}, times: 3);
防止游离进程
如果你想确保在整个测试或完整的测试套件中,所有调用的进程都已被伪造,你可以调用 preventStrayProcesses
方法。调用此方法后,任何没有相应伪造结果的进程都将抛出异常,而不是启动实际进程:
php
use Illuminate\Support\Facades\Process;
Process::preventStrayProcesses();
Process::fake([
'ls *' => 'Test output...',
]);
// Fake response is returned...
Process::run('ls -la');
// An exception is thrown...
Process::run('bash import.sh');