> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://symfony.com/doc/current/components/process.html).
Elle offre une API concise pour appeler des commandes shell depuis Laravel et traiter les résultats.

```mermaid theme={null}
flowchart LR
    A["Application Laravel"] --> B["Façade<br>Process"]
    B --> C["Commande shell"]
    C --> D["ProcessResult<br>(output / exitCode)"]
    D --> A
```

## Lancer un processus

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

```php theme={null}
use Illuminate\Support\Facades\Process;

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

return $result->output();
```

L'instance `ProcessResult` expose plusieurs méthodes.

```php theme={null}
$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.

```php theme={null}
$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).

```php theme={null}
$result = Process::path(__DIR__)->run('ls -la');
```

### Entrée standard

`input()` fournit stdin.

```php theme={null}
$result = Process::input('Hello World')->run('cat');
```

### Timeout

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

```php theme={null}
$result = Process::timeout(120)->run('bash import.sh');
```

Utilisez aussi les helpers `CarbonInterval`.

```php theme={null}
use function Illuminate\Support\minutes;

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

Désactiver le timeout : `forever()`.

```php theme={null}
$result = Process::forever()->run('bash import.sh');
```

Timeout d'inactivité (secondes sans sortie) :

```php theme={null}
$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.

```php theme={null}
$result = Process::forever()
    ->env(['IMPORT_PATH' => __DIR__])
    ->run('bash import.sh');
```

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

```php theme={null}
$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.

```php theme={null}
$result = Process::quietly()->run('bash import.sh');
```

### Sortie en temps réel

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

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

## Pipelines

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

```php theme={null}
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 :

```php theme={null}
$result = Process::pipe([
    'cat example.txt',
    'grep -i "laravel"',
]);
```

`as()` nomme chaque processus.

```php theme={null}
$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.

```php theme={null}
$process = Process::timeout(120)->start('bash import.sh');

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

$result = $process->wait();
```

### PID et signaux

`id()` retourne le PID.

```php theme={null}
$process = Process::start('bash import.sh');

return $process->id();
```

`signal()` envoie un signal.

```php theme={null}
$process->signal(SIGUSR2);
```

### Sortie asynchrone

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

```php theme={null}
$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.

```php theme={null}
$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.

```php theme={null}
$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.

```php theme={null}
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.

```php theme={null}
[$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.

```php theme={null}
$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 :

```php theme={null}
$pool->signal(SIGUSR2);
```

## Tests

### Faker de processus

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

```php theme={null}
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.

```php theme={null}
Process::fake([
    '*' => Process::result(
        output: 'Test output',
        errorOutput: 'Test error output',
        exitCode: 1,
    ),
]);
```

### Faker une commande précise

```php theme={null}
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 :

```php theme={null}
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.

```php theme={null}
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

<Columns cols={2}>
  <Card title="Console Artisan" icon="terminal" href="/fr/artisan">
    Créez des commandes personnalisées qui invoquent des processus.
  </Card>

  <Card title="Queues" icon="list" href="/fr/queues">
    Comparaison avec le traitement asynchrone.
  </Card>
</Columns>


## Related topics

- [WebSocket (Jetstream / Firehose)](/fr/packages/laravel-bluesky/websocket.md)
- [Labeler](/fr/packages/laravel-bluesky/labeler.md)
- [Laravel Reverb](/fr/reverb.md)
- [Cache](/fr/cache.md)
- [Structure d'application Laravel 11+](/fr/advanced/app-structure.md)