# Batchbearbetning

Med batchar kan du skicka iväg en grupp jobb och följa dem som en enda enhet. Du kan registrera återanrop som körs när batchen slutförs, när något jobb misslyckas eller när batchen är klar oavsett utfall. Queuety följer automatiskt förlopp, fel och avbrytningsstatus.

## Skapa en batch

Använd `Queuety::create_batch()` för att starta en `BatchBuilder`. Skicka med en array med instanser av `Contracts\Job` och anropa sedan `dispatch()` för att skapa batchraden och alla jobb.

```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()` returnerar ett `Batch`-värdeobjekt med batchens tillstånd.

Du kan också skicka med arrayer med hanterare och nyttolaster i stället för jobbinstanser:

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

## Återanrop

Registrera hanterarklasser som ska anropas vid olika punkter i batchens livscykel. Varje hanterarklass måste ha en metod för `handle( Batch $batch )`.

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

| Metod | När den anropas |
|---|---|
| `then( $handler_class )` | Alla jobb har slutförts utan fel (eller `allow_failures()` är inställt) |
| `catch( $handler_class )` | Det första jobbet i batchen misslyckas |
| `finally( $handler_class )` | Batchen slutförs, oavsett om den lyckas eller misslyckas |

### Skriva en återanropshanterare

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

## Tillåta fel

Som standard anropas återanropet `then` bara om alla jobb i batchen lyckas. Anropa `allow_failures()` för att låta återanropet `then` köras även när vissa jobb misslyckas.

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

## Förloppsspårning

Värdeobjektet `Batch` tillhandahåller egenskaper och metoder för att spåra förloppet.

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

| Metod/egenskap | Typ | Beskrivning |
|---|---|---|
| `progress()` | `int` | Slutförandegrad från 0 till 100 |
| `finished()` | `bool` | Om batchen har slutförts (alla jobb är klara eller har misslyckats) |
| `has_failures()` | `bool` | Om några jobb i batchen har misslyckats |
| `cancelled()` | `bool` | Om batchen har avbrutits |
| `$total_jobs` | `int` | Totalt antal jobb i batchen |
| `$pending_jobs` | `int` | Antal jobb som fortfarande väntar |
| `$failed_jobs` | `int` | Antal jobb som har misslyckats |
| `$failed_job_ids` | `array` | ID:n för jobben som misslyckades |
| `$name` | `string\|null` | Valfritt batchnamn |
| `$created_at` | `DateTimeImmutable` | När batchen skapades |
| `$finished_at` | `DateTimeImmutable\|null` | När batchen slutfördes |
| `$cancelled_at` | `DateTimeImmutable\|null` | När batchen avbröts |

## Avbrytning

Avbryt en batch via `BatchManager`. När en batch avbryts ställs `cancelled_at` och `finished_at` in, och återanropet `finally` körs.

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

När en batch avbryts markeras den som avbruten och slutförd, och dess återanrop `finally` körs. Jobben påverkas inte: väntande jobb i en avbruten batch körs fortfarande, men deras resultat uppdaterar inte längre batchens räknare och utlöser inte `then`, `catch` eller `finally`. Ta bort jobben själv om de inte ska köras.

## Hitta batchar

Hitta en batch med dess ID:

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

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

## Rensa gamla batchar

Ta bort slutförda batchar som är äldre än ett angivet antal dagar:

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

Endast batchar med en tidsstämpel för `finished_at` som inte är null tas bort. Aktiva batchar rensas aldrig.