# Dávkové zpracování

Dávky umožňují spustit skupinu úloh a sledovat ji jako jeden celek. Můžete registrovat zpětná volání, která se spustí při dokončení dávky, při selhání kterékoli úlohy nebo při dokončení dávky bez ohledu na výsledek. Queuety automaticky sleduje průběh, chyby a stav zrušení.

## Vytvoření dávky

Pomocí `Queuety::create_batch()` zahajte `BatchBuilder`. Předávejte pole instancí `Contracts\Job` a poté voláním `dispatch()` vytvořte záznam dávky i všechny úlohy.

```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()` vrací objekt s hodnotou `Batch` a stavem dávky.

Místo instancí úloh můžete předat také pole dvojic obslužná rutina + data:

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

## Zpětná volání

Zaregistrujte třídy obslužných rutin, které se mají volat v různých fázích životního cyklu dávky. Každá třída obslužné rutiny musí mít metodu `handle( Batch $batch )`.

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

| Metoda | Kdy se spustí |
|---|---|
| `then( $handler_class )` | Všechny úlohy byly úspěšně dokončeny (nebo je nastaveno `allow_failures()`) |
| `catch( $handler_class )` | První úloha v dávce selže |
| `finally( $handler_class )` | Dávka se dokončí, ať už úspěšně, nebo neúspěšně |

### Vytvoření obslužné rutiny zpětného volání

```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.
    }
}
```

## Povolení chyb

Ve výchozím nastavení se zpětné volání `then` spustí pouze tehdy, když uspějí všechny úlohy v dávce. Voláním `allow_failures()` umožníte spuštění zpětného volání `then` i při selhání některých úloh.

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

## Sledování průběhu

Objekt hodnoty `Batch` poskytuje vlastnosti a metody pro sledování průběhu.

```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
```

| Metoda/vlastnost | Typ | Popis |
|---|---|---|
| `progress()` | `int` | Procento dokončení od 0 do 100 |
| `finished()` | `bool` | Zda je dávka dokončena (všechny úlohy byly dokončeny nebo selhaly) |
| `has_failures()` | `bool` | Zda některá úloha v dávce selhala |
| `cancelled()` | `bool` | Zda byla dávka zrušena |
| `$total_jobs` | `int` | Celkový počet úloh v dávce |
| `$pending_jobs` | `int` | Počet dosud čekajících úloh |
| `$failed_jobs` | `int` | Počet neúspěšných úloh |
| `$failed_job_ids` | `array` | ID neúspěšných úloh |
| `$name` | `string\|null` | Volitelný název dávky |
| `$created_at` | `DateTimeImmutable` | Kdy byla dávka vytvořena |
| `$finished_at` | `DateTimeImmutable\|null` | Kdy byla dávka dokončena |
| `$cancelled_at` | `DateTimeImmutable\|null` | Kdy byla dávka zrušena |

## Zrušení

Dávku zrušíte prostřednictvím `BatchManager`. Zrušením dávky se nastaví `cancelled_at` a `finished_at` a spustí se zpětné volání `finally`.

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

Zrušení označí dávku jako zrušenou a dokončenou a spustí její zpětné volání `finally`. Úloh se nedotkne: čekající úlohy ve zrušené dávce se přesto spustí, ale jejich výsledky už neaktualizují počítadla dávky ani nespouštějí `then`, `catch` nebo `finally`. Pokud se úlohy nemají spustit, odstraňte je sami.

## Vyhledání dávek

Vyhledejte dávku podle jejího ID:

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

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

## Odstranění starých dávek

Odstraňte dokončené dávky starší než zadaný počet dní:

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

Odstraní se pouze dávky s časovým razítkem `finished_at`, které není null. Aktivní dávky se nikdy neodstraňují.