# Paketttöötlus

Paketid võimaldavad saata välja töörühma ja jälgida neid ühe tervikuna. Saad registreerida tagasihelistusi, mis käivituvad paketi edukal lõpetamisel, mis tahes töö ebaõnnestumisel või paketi lõppemisel tulemusest olenemata. Queuety jälgib automaatselt edenemist, tõrkeid ja tühistamisolekut.

## Paketi loomine

Kasuta `Queuety::create_batch()`, et alustada `BatchBuilder`. Edasta `Contracts\Job` eksemplaride massiiv ja seejärel loo paketi kirje ning kõik tööd, kutsudes välja `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()` tagastab väärtusobjekti `Batch` koos paketi olekuga.

Tööeksemplaride asemel saad edastada ka töötleja ja kasuliku koorma massiive:

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

## Tagasihelistused

Registreeri töötlejaklassid, mida kutsutakse paketi elutsükli eri etappides. Igal töötlejaklassil peab olema meetod `handle( Batch $batch )`.

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

| Meetod | Käivitamise aeg |
|---|---|
| `then( $handler_class )` | Kõik tööd valmisid edukalt (või määrati `allow_failures()`) |
| `catch( $handler_class )` | Paketi esimene töö ebaõnnestub |
| `finally( $handler_class )` | Pakett lõpeb, olenemata õnnestumisest või ebaõnnestumisest |

### Tagasihelistuse töötleja kirjutamine

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

## Tõrgete lubamine

Vaikimisi käivitub tagasihelistus `then` ainult siis, kui kõik paketi tööd õnnestuvad. Kutsu välja `allow_failures()`, et lubada tagasihelistuse `then` käivitumine ka mõne töö ebaõnnestumisel.

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

## Edenemise jälgimine

Väärtusobjekt `Batch` pakub edenemise jälgimiseks atribuute ja meetodeid.

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

| Meetod/atribuut | Tüüp | Kirjeldus |
|---|---|---|
| `progress()` | `int` | Lõpetatuse protsent vahemikus 0 kuni 100 |
| `finished()` | `bool` | Kas pakett on lõpetatud (kõik tööd on valmis või ebaõnnestunud) |
| `has_failures()` | `bool` | Kas mõni paketi töödest ebaõnnestus |
| `cancelled()` | `bool` | Kas pakett on tühistatud |
| `$total_jobs` | `int` | Paketi tööde koguarv |
| `$pending_jobs` | `int` | Ootel tööde arv |
| `$failed_jobs` | `int` | Ebaõnnestunud tööde arv |
| `$failed_job_ids` | `array` | Ebaõnnestunud tööde ID-d |
| `$name` | `string\|null` | Valikuline paketi nimi |
| `$created_at` | `DateTimeImmutable` | Paketi loomise aeg |
| `$finished_at` | `DateTimeImmutable\|null` | Paketi lõpetamise aeg |
| `$cancelled_at` | `DateTimeImmutable\|null` | Paketi tühistamise aeg |

## Tühistamine

Tühista pakett käsu `BatchManager` kaudu. Paketi tühistamine määrab väärtused `cancelled_at` ja `finished_at` ning käivitab tagasihelistuse `finally`.

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

Tühistamine märgib paketi tühistatuks ja lõpetatuks ning käivitab selle tagasihelistuse `finally`. See ei mõjuta töid: tühistatud paketi ootel tööd käivituvad endiselt, kuid nende tulemused ei uuenda enam paketi loendureid ega käivita `then`, `catch` või `finally`. Kui tööd ei tohi käivituda, kustuta need ise.

## Pakettide leidmine

Otsi paketti selle ID järgi:

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

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

## Vanade pakettide kärpimine

Eemalda lõpetatud paketid, mis on määratud päevade arvust vanemad:

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

Kustutatakse ainult paketid, mille ajatempel `finished_at` pole null. Aktiivseid pakette ei kärbita kunagi.