# Združevanje v pakete

Paketi omogočajo sprožitev skupine opravil in njihovo spremljanje kot ene enote. Registrirate lahko povratne funkcije, ki se sprožijo, ko se paket dokonča, ko katero koli opravilo spodleti ali ko se paket konča ne glede na izid. Queuety samodejno spremlja napredek, napake in stanje preklica.

## Ustvarjanje paketa

Za začetek `BatchBuilder` uporabite `Queuety::create_batch()`. Posredujte polje primerkov `Contracts\Job`, nato pa pokličite `dispatch()`, da ustvarite vrstico paketa in vsa opravila.

```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()` vrne objekt vrednosti `Batch` s stanjem paketa.

Namesto primerkov opravil lahko posredujete tudi polja parov obravnavalnik in koristni tovor:

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

## Povratne funkcije

Registrirajte razrede obravnavalnikov, ki bodo poklicani v različnih trenutkih življenjskega cikla paketa. Vsak razred obravnavalnika mora vsebovati metodo `handle( Batch $batch )`.

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

| Metoda | Kdaj se sproži |
|---|---|
| `then( $handler_class )` | Vsa opravila so uspešno dokončana (ali je nastavljen `allow_failures()`) |
| `catch( $handler_class )` | Prvo opravilo v paketu spodleti |
| `finally( $handler_class )` | Paket se konča, ne glede na to, ali je uspel ali spodletel |

### Pisanje obravnavalnika povratne funkcije

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

## Dovoljevanje napak

Povratna funkcija `then` se privzeto sproži le, če uspejo vsa opravila v paketu. Pokličite `allow_failures()`, da se povratna funkcija `then` sproži tudi, če nekaj opravil spodleti.

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

## Spremljanje napredka

Objekt vrednosti `Batch` ponuja lastnosti in metode za spremljanje napredka.

```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/lastnost | Vrsta | Opis |
|---|---|---|
| `progress()` | `int` | Odstotek dokončanja od 0 do 100 |
| `finished()` | `bool` | Ali je paket končan (vsa opravila so dokončana ali neuspešna) |
| `has_failures()` | `bool` | Ali je katero od opravil v paketu spodletelo |
| `cancelled()` | `bool` | Ali je bil paket preklican |
| `$total_jobs` | `int` | Skupno število opravil v paketu |
| `$pending_jobs` | `int` | Število opravil, ki še čakajo |
| `$failed_jobs` | `int` | Število neuspešnih opravil |
| `$failed_job_ids` | `array` | ID-ji neuspešnih opravil |
| `$name` | `string\|null` | Izbirno ime paketa |
| `$created_at` | `DateTimeImmutable` | Kdaj je bil paket ustvarjen |
| `$finished_at` | `DateTimeImmutable\|null` | Kdaj se je paket končal |
| `$cancelled_at` | `DateTimeImmutable\|null` | Kdaj je bil paket preklican |

## Preklic

Paket prekličite prek `BatchManager`. S preklicem paketa se nastavita `cancelled_at` in `finished_at` ter sproži povratna funkcija `finally`.

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

Preklic označi paket kot preklican in končan ter sproži njegovo povratno funkcijo `finally`. Opravil se ne dotakne: čakajoča opravila v preklicanem paketu se še vedno izvedejo, vendar njihovi rezultati ne posodabljajo več števcev paketa in ne sprožijo `then`, `catch` ali `finally`. Če se opravila ne smejo izvesti, jih izbrišite sami.

## Iskanje paketov

Poiščite paket po njegovem ID-ju:

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

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

## Čiščenje starih paketov

Odstranite končane pakete, starejše od določenega števila dni:

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

Izbrišejo se samo paketi z neničelnim časovnim žigom `finished_at`. Aktivni paketi se nikoli ne čistijo.