# Eräkäsittely

Erien avulla voit lähettää ryhmän töitä ja seurata niitä yhtenä kokonaisuutena. Voit rekisteröidä takaisinkutsuja, jotka suoritetaan, kun erän käsittely valmistuu, jokin työ epäonnistuu tai erä päättyy tuloksesta riippumatta. Queuety seuraa edistymistä, virheitä ja peruutustilaa automaattisesti.

## Erän luominen

Käynnistä `BatchBuilder` käyttämällä `Queuety::create_batch()`. Välitä taulukko, joka sisältää `Contracts\Job`-instansseja, ja luo sitten erärivi sekä kaikki työt kutsumalla `dispatch()`.

```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()` palauttaa `Batch`-arvo-olion, joka sisältää erän tilan.

Voit välittää työinstanssien sijaan myös käsittelijä- ja hyötykuormataulukoita:

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

## Takaisinkutsut

Rekisteröi käsittelijäluokat, joita kutsutaan erän elinkaaren eri vaiheissa. Jokaisessa käsittelijäluokassa on oltava `handle( Batch $batch )`-metodi.

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

| Metodi | Suoritusajankohta |
|---|---|
| `then( $handler_class )` | Kaikki työt ovat valmistuneet onnistuneesti (tai `allow_failures()` on asetettu) |
| `catch( $handler_class )` | Erän ensimmäinen työ epäonnistuu |
| `finally( $handler_class )` | Erä päättyy onnistumisesta tai epäonnistumisesta riippumatta |

### Takaisinkutsun käsittelijän kirjoittaminen

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

## Virheiden salliminen

Oletusarvoisesti `then`-takaisinkutsu suoritetaan vain, jos kaikki erän työt onnistuvat. Kutsu `allow_failures()`, jotta `then`-takaisinkutsu suoritetaan myös silloin, kun osa töistä epäonnistuu.

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

## Edistymisen seuranta

`Batch`-arvo-olio sisältää ominaisuuksia ja metodeja edistymisen seuraamiseen.

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

| Metodi/ominaisuus | Tyyppi | Kuvaus |
|---|---|---|
| `progress()` | `int` | Valmistumisprosentti välillä 0–100 |
| `finished()` | `bool` | Onko erä päättynyt (kaikki työt valmistuneet tai epäonnistuneet) |
| `has_failures()` | `bool` | Epäonnistuiko jokin erän töistä |
| `cancelled()` | `bool` | Onko erä peruutettu |
| `$total_jobs` | `int` | Töiden kokonaismäärä erässä |
| `$pending_jobs` | `int` | Vielä odottavien töiden määrä |
| `$failed_jobs` | `int` | Epäonnistuneiden töiden määrä |
| `$failed_job_ids` | `array` | Epäonnistuneiden töiden tunnukset |
| `$name` | `string\|null` | Valinnainen erän nimi |
| `$created_at` | `DateTimeImmutable` | Erän luontiajankohta |
| `$finished_at` | `DateTimeImmutable\|null` | Erän päättymisajankohta |
| `$cancelled_at` | `DateTimeImmutable\|null` | Erän peruutusajankohta |

## Peruuttaminen

Peruuta erä `BatchManager`n kautta. Erän peruuttaminen asettaa `cancelled_at`- ja `finished_at`-arvot ja suorittaa `finally`-takaisinkutsun.

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

Peruutus merkitsee erän peruutetuksi ja päättyneeksi ja suorittaa sen `finally`-takaisinkutsun. Se ei vaikuta töihin: peruutetun erän odottavat työt suoritetaan silti, mutta niiden tulokset eivät enää päivitä erän laskureita tai käynnistä toimintoja `then`, `catch` tai `finally`. Poista työt itse, jos niitä ei saa suorittaa.

## Erien etsiminen

Hae erä sen tunnuksella:

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

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

## Vanhojen erien siivoaminen

Poista päättyneet erät, jotka ovat vanhempia kuin määritetty päivien määrä:

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

Vain erät, joiden `finished_at`-aikaleima ei ole null, poistetaan. Aktiivisia eriä ei koskaan siivota.