# Kötegelt feldolgozás

A kötegek lehetővé teszik feladatcsoportok indítását és egyetlen egységként való nyomon követését. Regisztrálhatsz visszahívásokat, amelyek a köteg befejezésekor, bármelyik feladat sikertelenségekor vagy a köteg az eredménytől független lezárulásakor futnak le. A Queuety automatikusan nyomon követi az előrehaladást, a hibákat és a megszakítás állapotát.

## Köteg létrehozása

A `Queuety::create_batch()` segítségével indítson el egy `BatchBuilder`-t. Adjon át `Contracts\Job`-példányokból álló tömböt, majd hívja meg a `dispatch()` függvényt a kötegsor és az összes feladat létrehozásához.

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

A `dispatch()` egy `Batch` típusú értékobjektumot ad vissza, amely a köteg állapotát tartalmazza.

Feladatpéldányok helyett kezelő- és adatcsomagtömböket is átadhatsz:

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

## Visszahívások

Regisztrálj kezelőosztályokat, amelyeket a köteg életciklusának különböző pontjain kell meghívni. Minden kezelőosztálynak rendelkeznie kell egy `handle( Batch $batch )` metódussal.

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

| Metódus | Mikor fut le |
|---|---|
| `then( $handler_class )` | Minden feladat sikeresen befejeződött (vagy a `allow_failures()` be van állítva) |
| `catch( $handler_class )` | A köteg első feladata sikertelen |
| `finally( $handler_class )` | A köteg lezárul, függetlenül attól, hogy sikeres vagy sikertelen volt |

### Visszahíváskezelő írása

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

## Hibák engedélyezése

Alapértelmezés szerint a `then` visszahívás csak akkor fut le, ha a köteg összes feladata sikerül. A `allow_failures()` meghívásával engedélyezheted, hogy a `then` visszahívás akkor is lefusson, ha egyes feladatok sikertelenek.

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

## Az előrehaladás nyomon követése

A `Batch` értékobjektum előrehaladás-követő tulajdonságokat és metódusokat biztosít.

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

| Metódus/tulajdonság | Típus | Leírás |
|---|---|---|
| `progress()` | `int` | Befejezettségi százalék 0 és 100 között |
| `finished()` | `bool` | Jelzi, hogy a köteg befejeződött-e (minden feladat kész vagy sikertelen) |
| `has_failures()` | `bool` | Jelzi, hogy sikertelen volt-e valamelyik kötegbeli feladat |
| `cancelled()` | `bool` | Jelzi, hogy a köteget megszakították-e |
| `$total_jobs` | `int` | A köteg feladatainak száma összesen |
| `$pending_jobs` | `int` | A még függő feladatok száma |
| `$failed_jobs` | `int` | A sikertelen feladatok száma |
| `$failed_job_ids` | `array` | A sikertelen feladatok azonosítói |
| `$name` | `string\|null` | Opcionális kötegnév |
| `$created_at` | `DateTimeImmutable` | A köteg létrehozásának időpontja |
| `$finished_at` | `DateTimeImmutable\|null` | A köteg befejezésének időpontja |
| `$cancelled_at` | `DateTimeImmutable\|null` | A köteg megszakításának időpontja |

## Megszakítás

A köteget a `BatchManager` segítségével szakíthatod meg. A megszakítás beállítja a `cancelled_at` és a `finished_at` értékét, majd meghívja a `finally` visszahívást.

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

A megszakítás a köteget megszakítottként és befejezettként jelöli meg, majd meghívja a `finally` visszahívást. A feladatokat nem érinti: a megszakított köteg függő feladatai továbbra is lefutnak, de az eredményeik már nem módosítják a kötegszámlálókat, és nem váltják ki a `then`, `catch` vagy `finally` visszahívást. Ha meg kell akadályozni a futásukat, töröld a feladatokat.

## Kötegek keresése

Köteg keresése azonosító alapján:

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

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

## Régi kötegek törlése

Adott számú napnál régebben befejeződött kötegek eltávolítása:

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

Csak a nem null értékű `finished_at` időbélyeggel rendelkező kötegek törlődnek. Az aktív kötegek soha nem kerülnek törlésre.