# Spracovanie dávok

Dávky umožňujú odoslať skupinu úloh a sledovať ju ako jeden celok. Môžete zaregistrovať spätné funkcie, ktoré sa spustia po dokončení dávky, pri zlyhaní ľubovoľnej úlohy alebo vždy po skončení dávky bez ohľadu na výsledok. Queuety automaticky sleduje priebeh, zlyhania a stav zrušenia.

## Vytvorenie dávky

Na spustenie `BatchBuilder` použite `Queuety::create_batch()`. Odovzdajte pole inštancií `Contracts\Job` a potom zavolajte `dispatch()`, čím vytvoríte záznam dávky aj všetky ú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()` vracia objekt hodnoty `Batch` so stavom dávky.

Namiesto inštancií úloh môžete odovzdať aj polia obslužná trieda + údaje:

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

## Spätné funkcie

Zaregistrujte triedy obslužných funkcií, ktoré sa majú volať v rôznych fázach životného cyklu dávky. Každá trieda musí mať metódu `handle( Batch $batch )`.

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

| Metóda | Kedy sa spustí |
|---|---|
| `then( $handler_class )` | Po úspešnom dokončení všetkých úloh (alebo pri nastavení `allow_failures()`) |
| `catch( $handler_class )` | Pri zlyhaní prvej úlohy v dávke |
| `finally( $handler_class )` | Po skončení dávky bez ohľadu na to, či uspela alebo zlyhala |

### Písanie obslužnej triedy spätnej funkcie

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

## Povolenie zlyhaní

Predvolene sa spätná funkcia `then` spustí iba vtedy, keď uspejú všetky úlohy v dávke. Zavolajte `allow_failures()`, ak chcete, aby sa spätná funkcia `then` spustila aj pri zlyhaní niektorých úloh.

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

## Sledovanie priebehu

Objekt hodnoty `Batch` poskytuje vlastnosti a metódy na sledovanie priebehu.

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

| Metóda/vlastnosť | Typ | Opis |
|---|---|---|
| `progress()` | `int` | Percento dokončenia od 0 do 100 |
| `finished()` | `bool` | Informuje, či sa dávka skončila (všetky úlohy boli dokončené alebo zlyhali) |
| `has_failures()` | `bool` | Informuje, či zlyhala niektorá úloha v dávke |
| `cancelled()` | `bool` | Informuje, či bola dávka zrušená |
| `$total_jobs` | `int` | Celkový počet úloh v dávke |
| `$pending_jobs` | `int` | Počet úloh, ktoré ešte čakajú na spracovanie |
| `$failed_jobs` | `int` | Počet neúspešných úloh |
| `$failed_job_ids` | `array` | ID neúspešných úloh |
| `$name` | `string\|null` | Voliteľný názov dávky |
| `$created_at` | `DateTimeImmutable` | Čas vytvorenia dávky |
| `$finished_at` | `DateTimeImmutable\|null` | Čas skončenia dávky |
| `$cancelled_at` | `DateTimeImmutable\|null` | Čas zrušenia dávky |

## Zrušenie

Dávku zrušíte cez `BatchManager`. Zrušením dávky sa nastavia `cancelled_at` a `finished_at` a spustí sa spätná funkcia `finally`.

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

Zrušenie označí dávku ako zrušenú a dokončenú a spustí jej spätnú funkciu `finally`. Úloh sa nedotkne: čakajúce úlohy v zrušenej dávke sa naďalej vykonajú, ale ich výsledky už neaktualizujú počítadlá dávky ani nespúšťajú `then`, `catch` alebo `finally`. Ak sa úlohy nemajú vykonať, odstráňte ich sami.

## Vyhľadanie dávok

Vyhľadajte dávku podľa jej ID:

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

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

## Odstránenie starých dávok

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

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

Odstránia sa iba dávky s časovou pečiatkou `finished_at`, ktorá nie je null. Aktívne dávky sa nikdy neodstraňujú.