# Batchbehandling

Med batches kan du sende en gruppe jobs af sted og følge dem som én samlet enhed. Du kan registrere callbacks, der udløses, når batchen er færdig, når et job fejler, eller når batchen afsluttes uanset udfaldet. Queuety følger automatisk status, fejl og annullering.

## Opret en batch

Brug `Queuety::create_batch()` til at starte en `BatchBuilder`. Videregiv et array af `Contracts\Job`-instanser, og kald derefter `dispatch()` for at oprette batchrækken og alle jobs.

```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()` returnerer et `Batch`-værdiobjekt med batchens tilstand.

Du kan også videregive arrays med handler og payload i stedet for jobinstanser:

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

## Callbacks

Registrér handlerklasser, der skal kaldes på forskellige tidspunkter i batchens livscyklus. Hver handlerklasse skal have en `handle( Batch $batch )`-metode.

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

| Metode | Hvornår den udløses |
|---|---|
| `then( $handler_class )` | Alle jobs er fuldført (eller `allow_failures()` er angivet) |
| `catch( $handler_class )` | Det første job i batchen fejler |
| `finally( $handler_class )` | Batchen afsluttes, uanset om den lykkedes eller fejlede |

### Skriv en callback-handler

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

## Tillad fejl

Som standard udløses `then`-callbacken kun, hvis alle jobs i batchen lykkes. Kald `allow_failures()` for at lade `then`-callbacken blive udløst, selv når nogle jobs fejler.

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

## Statusovervågning

Værdielementet `Batch` indeholder egenskaber og metoder til at følge fremdriften.

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

| Metode/egenskab | Type | Beskrivelse |
|---|---|---|
| `progress()` | `int` | Fuldførelsesprocent fra 0 til 100 |
| `finished()` | `bool` | Om batchen er afsluttet (alle jobs er fuldført eller mislykkedes) |
| `has_failures()` | `bool` | Om nogen jobs i batchen mislykkedes |
| `cancelled()` | `bool` | Om batchen er blevet annulleret |
| `$total_jobs` | `int` | Samlet antal jobs i batchen |
| `$pending_jobs` | `int` | Antal jobs, der stadig venter |
| `$failed_jobs` | `int` | Antal mislykkede jobs |
| `$failed_job_ids` | `array` | ID'er på de jobs, der mislykkedes |
| `$name` | `string\|null` | Valgfrit batchnavn |
| `$created_at` | `DateTimeImmutable` | Tidspunktet, hvor batchen blev oprettet |
| `$finished_at` | `DateTimeImmutable\|null` | Tidspunktet, hvor batchen blev afsluttet |
| `$cancelled_at` | `DateTimeImmutable\|null` | Tidspunktet, hvor batchen blev annulleret |

## Annullering

Annuller en batch via `BatchManager`. Når en batch annulleres, sættes `cancelled_at` og `finished_at`, og callbacken `finally` udløses.

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

En annullering markerer batchen som annulleret og afsluttet og udløser dens callback `finally`. Den påvirker ikke jobbene: ventende jobs i en annulleret batch kører stadig, men deres resultater opdaterer ikke længere batchens tællere og udløser ikke `then`, `catch` eller `finally`. Slet selv jobbene, hvis de ikke må køre.

## Find batches

Slå en batch op efter dens ID:

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

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

## Ryd op i gamle batches

Fjern afsluttede batches, der er ældre end et angivet antal dage:

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

Kun batches med et tidsstempel for `finished_at`, der ikke er null, slettes. Aktive batches ryddes aldrig op.