Processus

Exécutez des commandes shell externes et gérez le synchrone, l’asynchrone et le parallèle avec la façade Process de Laravel.

​

Introduction

La façade Process de Laravel est un wrapper mince du composant Symfony Process. Elle offre une API concise pour appeler des commandes shell depuis Laravel et traiter les résultats.

​

Lancer un processus

Process::run() exécute une commande de manière synchrone.

use Illuminate\Support\Facades\Process;

$result = Process::run('ls -la');

return $result->output();

L’instance ProcessResult expose plusieurs méthodes.

$result = Process::run('ls -la');

$result->command();       // Commande exécutée
$result->successful();    // Code de sortie 0
$result->failed();        // Code non nul
$result->output();        // stdout
$result->errorOutput();   // stderr
$result->exitCode();      // Code de sortie

​

Lever une exception en cas d’échec

throw() ou throwIf() lèvent Illuminate\Process\Exceptions\ProcessFailedException si le code de sortie est non nul.

$result = Process::run('ls -la')->throw();

$result = Process::run('ls -la')->throwIf($condition);

​

Options

​

Répertoire de travail

path() définit le répertoire de travail (sinon celui de PHP).

$result = Process::path(__DIR__)->run('ls -la');

​

Entrée standard

input() fournit stdin.

$result = Process::input('Hello World')->run('cat');

​

Timeout

60 s par défaut. Modifiez avec timeout(). En cas de timeout, ProcessTimedOutException est levée.

$result = Process::timeout(120)->run('bash import.sh');

Utilisez aussi les helpers CarbonInterval.

use function Illuminate\Support\minutes;

$result = Process::timeout(minutes(2))->run('bash import.sh');

Désactiver le timeout : forever().

$result = Process::forever()->run('bash import.sh');

Timeout d’inactivité (secondes sans sortie) :

$result = Process::timeout(60)->idleTimeout(30)->run('bash import.sh');

​

Variables d’environnement

env() ajoute ou surcharge les variables. Les variables système sont héritées automatiquement.

$result = Process::forever()
    ->env(['IMPORT_PATH' => __DIR__])
    ->run('bash import.sh');

Pour supprimer une variable héritée, utilisez false.

$result = Process::forever()
    ->env(['LOAD_PATH' => false])
    ->run('bash import.sh');

​

Désactiver la sortie

quietly() évite de consommer de la mémoire quand la sortie est volumineuse.

$result = Process::quietly()->run('bash import.sh');

​

Sortie en temps réel

Passez une closure comme deuxième argument à run().

$result = Process::run('ls -la', function (string $type, string $output) {
    echo $output;
});

​

Pipelines

Process::pipe() enchaîne des commandes.

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()) {
    // ...
}

Tableau de commandes :

$result = Process::pipe([
    'cat example.txt',
    'grep -i "laravel"',
]);

as() nomme chaque processus.

$result = Process::pipe(function (Pipe $pipe) {
    $pipe->as('first')->command('cat example.txt');
    $pipe->as('second')->command('grep -i "laravel"');
}, function (string $type, string $output, string $key) {
    // $key : 'first' ou 'second'
});

​

Processus asynchrones

Process::start() lance un processus asynchrone. Vous pouvez continuer d’autres traitements en parallèle.

$process = Process::timeout(120)->start('bash import.sh');

while ($process->running()) {
    // Autre traitement
}

$result = $process->wait();

​

PID et signaux

id() retourne le PID.

$process = Process::start('bash import.sh');

return $process->id();

signal() envoie un signal.

$process->signal(SIGUSR2);

​

Sortie asynchrone

latestOutput() et latestErrorOutput() retournent le delta depuis le dernier appel.

$process = Process::timeout(120)->start('bash import.sh');

while ($process->running()) {
    echo $process->latestOutput();
    echo $process->latestErrorOutput();

    sleep(1);
}

waitUntil() attend une sortie spécifique.

$process = Process::start('bash import.sh');

$process->waitUntil(function (string $type, string $output) {
    return $output === 'Ready...';
});

​

Vérifier le timeout

ensureNotTimedOut() lève une exception si le processus dépasse le timeout.

$process = Process::timeout(120)->start('bash import.sh');

while ($process->running()) {
    $process->ensureNotTimedOut();

    sleep(1);
}

​

Processus parallèles

Process::pool() exécute plusieurs processus en parallèle.

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();

concurrently() fait le tout en une ligne.

[$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();

​

Nommer les processus

as() nomme les processus dans le pool.

$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();

Signal envoyé à tout le pool :

$pool->signal(SIGUSR2);

​

Tests

​

Faker de processus

Process::fake() évite d’exécuter réellement les commandes en test.

use Illuminate\Support\Facades\Process;

Process::fake();

$response = $this->get('/import');

Process::assertRan('bash import.sh');

Vous pouvez définir sortie et code de retour.

Process::fake([
    '*' => Process::result(
        output: 'Test output',
        errorOutput: 'Test error output',
        exitCode: 1,
    ),
]);

​

Faker une commande précise

Process::fake([
    'cat *'    => Process::result(output: 'file contents'),
    'ls -la'   => Process::result(output: 'file listing'),
]);

​

Séquence de retours

Pour retourner des résultats différents à chaque appel :

Process::fake([
    'ls *' => [
        Process::result('first time'),
        Process::result('second time'),
    ],
]);

​

Assertions

Méthode	Description
Process::assertRan('command')	La commande a été exécutée
Process::assertNotRan('command')	La commande n’a pas été exécutée
Process::assertRan(fn)	Vérification détaillée via closure
Process::assertRanTimes('command', 3)	N fois exécutée

​

Empêcher les processus non prévus

Process::preventStrayProcesses() lance une exception si une commande sans fake est exécutée.

Process::preventStrayProcesses();

Process::fake([
    'ls *' => Process::result('file listing'),
]);

// Exception : 'bash import.sh' n'a pas de fake
Process::run('bash import.sh');

​

Pages associées

Console Artisan

Créez des commandes personnalisées qui invoquent des processus.

Queues

Comparaison avec le traitement asynchrone.