# Grupinis vykdymas

Užduočių paketai leidžia iškviesti užduočių grupę ir stebėti ją kaip vienetą. Galite užregistruoti atgalinio iškvietimo funkcijas, kurios suveikia užbaigus paketą, nepavykus kuriai nors užduočiai arba paketui baigus veikti, kad ir koks būtų rezultatas. Queuety automatiškai stebi eigą, nesėkmes ir atšaukimo būseną.

## Paketo kūrimas

Norėdami pradėti `BatchBuilder`, naudokite `Queuety::create_batch()`. Perduokite `Contracts\Job` egzempliorių masyvą, tada iškvieskite `dispatch()`, kad būtų sukurtas paketo įrašas ir visos užduotys.

```php
use Queuety\Queuety;

$batch = Queuety::create_batch( [
    new ImportUsersJob( $csv_chunk_1 ),
    new ImportUsersJob( $csv_chunk_2 ),
    new ImportUsersJob( $csv_chunk_3 ),
] )
    ->name( 'Import users' )
    ->on_queue( 'imports' )
    ->dispatch();

echo $batch->id; // The batch ID
```

`dispatch()` grąžina `Batch` reikšmės objektą su paketo būsena.

Vietoj užduočių egzempliorių taip pat galite perduoti apdorojimo funkcijos ir naudingojo turinio masyvus:

```php
$batch = Queuety::create_batch( [
    [ 'handler' => 'import_users', 'payload' => [ 'chunk' => 1 ] ],
    [ 'handler' => 'import_users', 'payload' => [ 'chunk' => 2 ] ],
] )->dispatch();
```

## Atgalinio iškvietimo funkcijos

Užregistruokite apdorojimo funkcijų klases, kurios bus iškviestos skirtingais paketo gyvavimo ciklo momentais. Kiekvienoje apdorojimo funkcijos klasėje turi būti metodas `handle( Batch $batch )`.

```php
$batch = Queuety::create_batch( $jobs )
    ->name( 'Import users' )
    ->then( ImportCompleteHandler::class )
    ->catch( ImportFailedHandler::class )
    ->finally( ImportCleanupHandler::class )
    ->dispatch();
```

| Metodas | Kada suveikia |
|---|---|
| `then( $handler_class )` | Kai visos užduotys sėkmingai užbaigtos (arba nustatytas `allow_failures()`) |
| `catch( $handler_class )` | Kai nepavyksta pirmoji paketo užduotis |
| `finally( $handler_class )` | Kai paketas baigia veikti, nesvarbu, ar pavyko |

### Atgalinio iškvietimo funkcijos apdorojimo klasės kūrimas

```php
use Queuety\Batch;

class ImportCompleteHandler {
    public function handle( Batch $batch ): void {
        // All users imported. Send a notification.
        error_log( "Batch {$batch->id} completed: {$batch->total_jobs} jobs processed." );
    }
}

class ImportFailedHandler {
    public function handle( Batch $batch ): void {
        error_log( "Batch {$batch->id} had a failure. Failed jobs: {$batch->failed_jobs}" );
    }
}

class ImportCleanupHandler {
    public function handle( Batch $batch ): void {
        // Runs regardless of outcome. Clean up temp files, etc.
    }
}
```

## Nesėkmių leidimas

Pagal numatytuosius nustatymus atgalinio iškvietimo funkcija `then` suveikia tik tada, jei visos paketo užduotys pavyksta. Iškvieskite `allow_failures()`, kad atgalinio iškvietimo funkcija `then` suveiktų net ir nepavykus kai kurioms užduotims.

```php
$batch = Queuety::create_batch( $jobs )
    ->then( ReportHandler::class )
    ->allow_failures()
    ->dispatch();
```

## Eigos stebėjimas

`Batch` reikšmės objektas suteikia eigos stebėjimo savybių ir metodų.

```php
$batch = Queuety::find_batch( $batch_id );

$batch->progress();      // 0-100 percentage
$batch->finished();      // true if all jobs are done
$batch->has_failures();  // true if any job failed
$batch->cancelled();     // true if the batch was cancelled

$batch->total_jobs;      // Total number of jobs
$batch->pending_jobs;    // Jobs still pending
$batch->failed_jobs;     // Number of failed jobs
$batch->failed_job_ids;  // Array of failed job IDs
```

| Metodas / savybė | Tipas | Aprašymas |
|---|---|---|
| `progress()` | `int` | Užbaigimo procentas nuo 0 iki 100 |
| `finished()` | `bool` | Ar paketas baigė veikti (visos užduotys užbaigtos arba nepavyko) |
| `has_failures()` | `bool` | Ar nepavyko kuri nors paketo užduotis |
| `cancelled()` | `bool` | Ar paketas buvo atšauktas |
| `$total_jobs` | `int` | Bendras užduočių skaičius pakete |
| `$pending_jobs` | `int` | Dar laukiančių užduočių skaičius |
| `$failed_jobs` | `int` | Nepavykusių užduočių skaičius |
| `$failed_job_ids` | `array` | Nepavykusių užduočių ID |
| `$name` | `string\|null` | Pasirinktinis paketo pavadinimas |
| `$created_at` | `DateTimeImmutable` | Paketo sukūrimo laikas |
| `$finished_at` | `DateTimeImmutable\|null` | Paketo užbaigimo laikas |
| `$cancelled_at` | `DateTimeImmutable\|null` | Paketo atšaukimo laikas |

## Atšaukimas

Atšaukite paketą per `BatchManager`. Atšaukus paketą nustatomos reikšmės `cancelled_at` ir `finished_at`, taip pat suveikia atgalinio iškvietimo funkcija `finally`.

```php
Queuety::batch_manager()->cancel( $batch_id );
```

Atšaukus paketas pažymimas kaip atšauktas ir užbaigtas, taip pat suveikia jo atgalinio iškvietimo funkcija `finally`. Užduotys nepakeičiamos: laukiančios užduotys atšauktame pakete vis tiek vykdomos, tačiau jų rezultatai nebeatnaujina paketo skaitiklių ir nesukelia `then`, `catch` ar `finally`. Jei užduotys neturi būti vykdomos, ištrinkite jas patys.

## Paketų paieška

Ieškokite paketo pagal jo ID:

```php
$batch = Queuety::find_batch( $batch_id );

if ( null === $batch ) {
    // Batch not found.
}
```

## Senų paketų valymas

Pašalinkite užbaigtus paketus, senesnius nei nurodytas dienų skaičius:

```php
$deleted = Queuety::batch_manager()->prune( 30 ); // Delete batches finished > 30 days ago
```

Ištrinami tik paketai, kurių laiko žyma `finished_at` nėra null. Aktyvūs paketai niekada nešalinami.