# Gruplama

Gruplar, birden fazla işi dağıtıp bunları tek bir birim olarak izlemenizi sağlar. Grup tamamlandığında, herhangi bir iş başarısız olduğunda veya sonuç ne olursa olsun grup sona erdiğinde çalışan geri çağırmalar kaydedebilirsiniz. Queuety ilerlemeyi, hataları ve iptal durumunu otomatik olarak izler.

## Grup oluşturma

Bir `BatchBuilder` başlatmak için `Queuety::create_batch()` kullanın. `Contracts\Job` örneklerinden oluşan bir dizi iletin, ardından grup satırını ve tüm işleri oluşturmak için `dispatch()` çağırın.

```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()`, grup durumunu içeren bir `Batch` değer nesnesi döndürür.

İş örnekleri yerine işleyici ve yük dizileri de iletebilirsiniz:

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

## Geri çağırmalar

Grup yaşam döngüsünün farklı aşamalarında çağrılacak işleyici sınıflarını kaydedin. Her işleyici sınıfında bir `handle( Batch $batch )` yöntemi bulunmalıdır.

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

| Yöntem | Ne zaman çalışır |
|---|---|
| `then( $handler_class )` | Tüm işler başarıyla tamamlandığında (veya `allow_failures()` ayarlandığında) |
| `catch( $handler_class )` | Gruptaki ilk iş başarısız olduğunda |
| `finally( $handler_class )` | Başarılı veya başarısız olmasına bakılmaksızın grup sona erdiğinde |

### Geri çağırma işleyicisi yazma

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

## Hatalara izin verme

Varsayılan olarak `then` geri çağırması yalnızca gruptaki tüm işler başarılı olursa çalışır. Bazı işler başarısız olsa bile `then` geri çağırmasının çalışmasına izin vermek için `allow_failures()` çağırın.

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

## İlerleme takibi

`Batch` değer nesnesi, ilerlemeyi izlemek için özellikler ve yöntemler sağlar.

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

| Yöntem/Özellik | Tür | Açıklama |
|---|---|---|
| `progress()` | `int` | 0 ile 100 arasındaki tamamlanma yüzdesi |
| `finished()` | `bool` | Grubun tamamlanıp tamamlanmadığı (tüm işler tamamlandı veya başarısız oldu) |
| `has_failures()` | `bool` | Gruptaki herhangi bir işin başarısız olup olmadığı |
| `cancelled()` | `bool` | Grubun iptal edilip edilmediği |
| `$total_jobs` | `int` | Gruptaki toplam iş sayısı |
| `$pending_jobs` | `int` | Hâlâ bekleyen iş sayısı |
| `$failed_jobs` | `int` | Başarısız iş sayısı |
| `$failed_job_ids` | `array` | Başarısız işlerin kimlikleri |
| `$name` | `string\|null` | İsteğe bağlı grup adı |
| `$created_at` | `DateTimeImmutable` | Grubun oluşturulduğu zaman |
| `$finished_at` | `DateTimeImmutable\|null` | Grubun tamamlandığı zaman |
| `$cancelled_at` | `DateTimeImmutable\|null` | Grubun iptal edildiği zaman |

## İptal

Bir grubu `BatchManager` üzerinden iptal edin. Grubun iptal edilmesi `cancelled_at` ve `finished_at` değerlerini ayarlar ve `finally` geri çağırmasını çalıştırır.

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

İptal işlemi grubu iptal edilmiş ve tamamlanmış olarak işaretler ve `finally` geri çağırmasını çalıştırır. İşlere dokunmaz: iptal edilmiş bir grupta bekleyen işler çalışmaya devam eder, ancak sonuçları grup sayaçlarını artık güncellemez ve `then`, `catch` veya `finally` tetiklemez. Çalışmamaları gerekiyorsa işleri kendiniz silin.

## Grupları bulma

Bir grubu kimliğiyle arayın:

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

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

## Eski grupları temizleme

Belirtilen gün sayısından daha eski, tamamlanmış grupları kaldırın:

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

Yalnızca boş olmayan bir `finished_at` zaman damgasına sahip gruplar silinir. Etkin gruplar hiçbir zaman temizlenmez.