# Przetwarzanie wsadowe

Partie umożliwiają wysłanie grupy zadań i śledzenie ich jako jednej całości. Możesz zarejestrować wywołania zwrotne uruchamiane po ukończeniu partii, niepowodzeniu dowolnego zadania lub zakończeniu partii niezależnie od wyniku. Queuety automatycznie śledzi postęp, błędy i stan anulowania.

## Tworzenie partii

Użyj `Queuety::create_batch()`, aby rozpocząć `BatchBuilder`. Przekaż tablicę instancji `Contracts\Job`, a następnie wywołaj `dispatch()`, aby utworzyć rekord partii i wszystkie zadania.

```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()` zwraca obiekt wartości `Batch` ze stanem partii.

Możesz też przekazać tablice handler+ładunek zamiast instancji zadań:

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

## Wywołania zwrotne

Zarejestruj klasy handlerów wywoływane na różnych etapach cyklu życia partii. Każda klasa handlera musi mieć metodę `handle( Batch $batch )`.

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

| Metoda | Kiedy jest wywoływana |
|---|---|
| `then( $handler_class )` | Wszystkie zadania zakończyły się powodzeniem (lub ustawiono `allow_failures()`) |
| `catch( $handler_class )` | Pierwsze zadanie w partii zakończyło się niepowodzeniem |
| `finally( $handler_class )` | Partia została zakończona, niezależnie od powodzenia lub błędu |

### Tworzenie handlera wywołania zwrotnego

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

## Zezwalanie na błędy

Domyślnie wywołanie zwrotne `then` jest uruchamiane tylko wtedy, gdy wszystkie zadania w partii zakończą się powodzeniem. Wywołaj `allow_failures()`, aby uruchamiać wywołanie zwrotne `then` także wtedy, gdy niektóre zadania zakończą się niepowodzeniem.

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

## Śledzenie postępów

Obiekt wartości `Batch` udostępnia właściwości i metody do śledzenia postępów.

```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/właściwość | Typ | Opis |
|---|---|---|
| `progress()` | `int` | Procent ukończenia od 0 do 100 |
| `finished()` | `bool` | Czy partia została zakończona (wszystkie zadania ukończone lub zakończone błędem) |
| `has_failures()` | `bool` | Czy jakiekolwiek zadania w partii zakończyły się błędem |
| `cancelled()` | `bool` | Czy partia została anulowana |
| `$total_jobs` | `int` | Łączna liczba zadań w partii |
| `$pending_jobs` | `int` | Liczba zadań oczekujących |
| `$failed_jobs` | `int` | Liczba zadań zakończonych błędem |
| `$failed_job_ids` | `array` | Identyfikatory zadań, które zakończyły się błędem |
| `$name` | `string\|null` | Opcjonalna nazwa partii |
| `$created_at` | `DateTimeImmutable` | Czas utworzenia partii |
| `$finished_at` | `DateTimeImmutable\|null` | Czas zakończenia partii |
| `$cancelled_at` | `DateTimeImmutable\|null` | Czas anulowania partii |

## Anulowanie

Anuluj partię za pomocą `BatchManager`. Anulowanie partii ustawia `cancelled_at` i `finished_at` oraz uruchamia wywołanie zwrotne `finally`.

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

Anulowanie oznacza partię jako anulowaną i zakończoną oraz uruchamia jej wywołanie zwrotne `finally`. Nie wpływa na zadania: oczekujące zadania w anulowanej partii nadal zostaną wykonane, ale ich wyniki nie będą już aktualizować liczników partii ani uruchamiać `then`, `catch` lub `finally`. Jeśli zadania nie powinny być wykonane, usuń je samodzielnie.

## Wyszukiwanie partii

Wyszukaj partię według jej identyfikatora:

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

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

## Usuwanie starych partii

Usuń zakończone partie starsze niż określona liczba dni:

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

Usuwane są tylko partie z niepustym znacznikiem czasu `finished_at`. Aktywne partie nigdy nie są usuwane.