# PHP API

Queuety içindeki her şeye `Queuety\Queuety` statik sınıfı üzerinden erişilebilir. İşleri dağıtmak, iş akışları oluşturmak, durum makinelerini çalıştırmak, kuyrukları yönetmek ve dahili alt sistemlere erişmek için tek giriş noktasıdır.

```php
use Queuety\Queuety;
```

## Bağımsız çekirdek erişimi

Queuety tarafından desteklenen çalışma zamanı, WordPress dışında başlatılabilir.

Bu bağımsız yol, orkestrasyon çekirdeği içindir:

- işler ve çalışanlar (çalışan havuzları ayrıca `DB_HOST`, `DB_NAME`, `DB_USER` ve `DB_PASSWORD` sabitlerini gerektirir; aşağıya bakın)
- iş akışları ve sinyaller
- durum makineleri ve olaylar
- yapıtlar, günlükler, ölçümler ve zamanlamalar

WordPress bağdaştırıcısının yerine geçmez. `Queuety::on_action()`,
`replace_wp_cron()`, eklenti önyüklemesi ve gerçek `wp queuety ...`
kayıt yolu hâlâ WordPress gerektirir.

### `Queuety::init( Connection $conn )`

Queuety öğesini doğrudan DB bağlantısıyla başlatın.

```php
use Queuety\Connection;
use Queuety\Queuety;

$conn = new Connection(
    host: '127.0.0.1:3306',
    dbname: 'wordpress',
    user: 'root',
    password: 'secret',
    prefix: 'wp_',
);

Queuety::init( $conn );
```

İsteğe bağlı `table_prefix` bağımsız değişkeni, bağlantı başına çalışma zamanı tablo adlarının Queuety bölümünü değiştirir:

```php
$conn = new Connection(
    host: '127.0.0.1:3306',
    dbname: 'wordpress',
    user: 'root',
    password: 'secret',
    prefix: 'wp_',
    table_prefix: 'themequeue_',
);
```

Böylece `queuety_jobs` gibi tablolar `wp_themequeue_jobs` olarak çözümlenir.

### `Queuety::ensure_schema()`

Etkin bağlantı için Queuety çalışma zamanı tablolarının bulunduğundan emin olun.

```php
Queuety::init( $conn );
Queuety::ensure_schema();
```

Tam model ve WordPress sınırı hakkında bilgi için [Bağımsız Kullanım](https://queuety.inline0.dev/tr/docs/features/standalone-use) bölümüne bakın.

## İşler

### `Queuety::dispatch( $handler, $payload )`

Bir iş dağıtın. Bir işleyici adı dizgesi veya `Contracts\Job` örneği kabul eder. Seçenekleri zincirleme ayarlamak için bir `PendingJob` oluşturucu döndürür.

```php
// Handler name + payload (original API)
Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] );

// Contracts\Job instance (v0.6.0+)
Queuety::dispatch( new SendEmailJob( to: 'user@example.com' ) );

// With options
Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] )
    ->on_queue( 'emails' )
    ->with_priority( Priority::High )
    ->delay( 300 )
    ->max_attempts( 5 )
    ->rate_limit( 10, 60 )
    ->unique()
    ->after( $other_job_id );

// Get the job ID
$job_id = Queuety::dispatch( 'send_email', $payload )->id();
```

Bir `Contracts\Job` örneği iletildiğinde serileştirici, işleyici adı olarak FQCN'yi ve yük olarak herkese açık özellikleri çıkarır. `$handler` bir `Job` örneğiyse `$payload` parametresi yok sayılır.

### `PendingJob` yöntemleri

| Yöntem | Açıklama |
|---|---|
| `on_queue( string $queue )` | Hedef kuyruğu ayarlar |
| `with_priority( Priority $priority )` | Öncelik düzeyini ayarlar |
| `delay( int $seconds )` | İşin kullanılabilir olmasından önceki gecikme |
| `max_attempts( int $max )` | En fazla yeniden deneme sayısı |
| `rate_limit( int $max, int $window )` | Hız sınırı: pencere saniyesi başına en fazla yürütme sayısı |
| `unique()` | Yinelenen dağıtımları önler |
| `after( int $job_id )` | Önce başka bir işin tamamlanmasını bekler |
| `concurrency_group( string $group, int $limit )` | İşi paylaşılan bir çalışan kabul grubuna ekler |
| `cost_units( int $units )` | Dağıtıma göreli yürütme maliyeti üst verisi ekler |
| `id()` | Dağıtımı zorlar ve iş kimliğini döndürür |

`concurrency_group()` ve `cost_units()`, daha geniş [Kaynak Yönetimi](https://queuety.inline0.dev/tr/docs/features/resource-management) modelini besler; böylece aynı dağıtım, sayıya dayalı eşzamanlılık sınırlarına, ağırlıklı kuyruk veya sağlayıcı bütçelerine ve çalışan kabul sezgisellerine katılabilir.

### `Queuety::dispatch_sync( $handler, $payload )`

Kuyruğa eklemeden bir işi geçerli süreçte eşzamanlı olarak yürütün.

```php
// With a Job instance
Queuety::dispatch_sync( new SendEmailJob( to: 'user@example.com', subject: 'Hi', body: 'Hello' ) );

// With a handler name and payload
Queuety::dispatch_sync( 'send_email', [ 'to' => 'user@example.com' ] );
```

İşin `handle()` yöntemi doğrudan çağrılır. Veritabanı satırı oluşturulmaz, çalışan kullanılmaz ve ara katman uygulanmaz.

### `Queuety::batch( $jobs )`

Birden çok işi tek bir çok satırlı INSERT içinde dağıtın.

```php
$job_ids = Queuety::batch( [
    [ 'handler' => 'send_email', 'payload' => [ 'to' => 'a@example.com' ], 'queue' => 'emails' ],
    [ 'handler' => 'send_email', 'payload' => [ 'to' => 'b@example.com' ], 'priority' => 2 ],
] );
```

### `Queuety::create_batch( $jobs )`

Geri çağırımlarla ve ilerleme takibiyle bir grup işi dağıtmak için `BatchBuilder` oluşturun. Ayrıntılar için [Gruplu İşleme](https://queuety.inline0.dev/tr/docs/features/batching) bölümüne bakın.

```php
$batch = Queuety::create_batch( [
    new ImportUsersJob( $chunk_1 ),
    new ImportUsersJob( $chunk_2 ),
] )
    ->name( 'Import users' )
    ->then( ImportCompleteHandler::class )
    ->catch( ImportFailedHandler::class )
    ->finally( ImportCleanupHandler::class )
    ->allow_failures()
    ->on_queue( 'imports' )
    ->dispatch();
```

### `BatchBuilder` yöntemleri

| Yöntem | Döndürülen | Açıklama |
|---|---|---|
| `name( string $name )` | `self` | Grup için ad belirler |
| `on_queue( string $queue )` | `self` | Gruptaki tüm işler için kuyruğu belirler |
| `then( string $handler_class )` | `self` | Grup başarıyla tamamlandığında çağrılan işleyici |
| `catch( string $handler_class )` | `self` | Gruptaki ilk iş başarısız olduğunda çağrılan işleyici |
| `finally( string $handler_class )` | `self` | Grup tamamlandığında (başarıyla veya başarısızlıkla) çağrılan işleyici |
| `allow_failures()` | `self` | Hatalar olsa bile `then` geri çağırımının çalışmasına izin verir |
| `dispatch()` | `Batch` | Grup satırını ve tüm işleri oluşturur, `Batch` değer nesnesini döndürür |

### `Queuety::find_batch( $id )`

Kimliğe göre grup bulur. Bir `Batch` değer nesnesi veya `null` döndürür.

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

if ( null !== $batch ) {
    echo $batch->progress() . '% complete';
}
```

## Çalışan denetimi

### `Queuety::run_worker( $queue = 'default', $once = false )`

Bir çalışan döngüsünü doğrudan çalıştırın.

```php
Queuety::run_worker( 'default' );
Queuety::run_worker( 'critical,default', true );
```

### `Queuety::run_worker_pool( $workers, $queue = 'default' )`

Sabit boyutlu bir çalışan havuzunu doğrudan çalıştırın. `pcntl` ve `posix` uzantılarını gerektirir. Havuz, alt bağlantıları için WordPress `DB_HOST`, `DB_NAME`, `DB_USER` ve `DB_PASSWORD` sabitlerini okur (yalnızca tablo önekleri başlatılan bağlantıdan gelir); bu nedenle havuzu WordPress dışında çalıştırırken bunları tanımlayın ([#5](https://github.com/inline0/queuety/issues/5)).

```php
Queuety::run_worker_pool( 4, 'providers' );
```

### `Queuety::run_auto_scaling_worker_pool( $min_workers, $max_workers, $queue = 'default' )`

Uyarlanabilir bir çalışan havuzunu doğrudan çalıştırın. Gereksinimler `run_worker_pool()` ile aynıdır.

```php
Queuety::run_auto_scaling_worker_pool( 2, 6, 'providers' );
```

### `Batch` değer nesnesi

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

### `Queuety::chain( $jobs )`

Sıralı iş yürütme için bir `ChainBuilder` oluşturun. Her işin başarıyla tamamlanması, kendisinden sonraki işin başlaması için gereklidir.

```php
$first_job_id = Queuety::chain( [
    new FetchDataJob( $url ),
    new ProcessDataJob(),
    new NotifyCompleteJob(),
] )
    ->on_queue( 'pipeline' )
    ->catch( ChainFailedHandler::class )
    ->dispatch();
```

### `ChainBuilder` yöntemleri

| Yöntem | Döndürülen | Açıklama |
|---|---|---|
| `on_queue( string $queue )` | `self` | Zincirdeki tüm işler için kuyruğu belirler |
| `catch( string $handler_class )` | `self` | Zincirdeki herhangi bir iş kalıcı olarak gömüldüğünde çağrılan işleyici |
| `dispatch()` | `int` | Sıralı bağımlılıklarla tüm işleri oluşturur ve ilk işin kimliğini döndürür |

### `Queuety::retry( $job_id )`

Belirli bir işi yeniden deneyin. Durumunu `pending` olarak sıfırlar.

```php
Queuety::retry( 42 );
```

### `Queuety::retry_buried()`

Gömülmüş tüm işleri yeniden deneyin. Yeniden denenen işlerin sayısını döndürür.

```php
$count = Queuety::retry_buried();
```

### `Queuety::purge( $older_than_days )`

Tamamlanmış işleri temizler. Temizlenen işlerin sayısını döndürür.

```php
$count = Queuety::purge();     // uses QUEUETY_RETENTION_DAYS
$count = Queuety::purge( 30 ); // purge jobs older than 30 days
```

## Kuyruklar

### `Queuety::stats( $queue )`

İş sayılarını duruma göre gruplandırarak alın.

```php
$stats = Queuety::stats();          // all queues
$stats = Queuety::stats( 'emails' ); // specific queue
// ['pending' => 12, 'processing' => 3, 'completed' => 150, 'failed' => 2, 'buried' => 1]
```

### `Queuety::buried( $queue )`

Gömülmüş tüm işleri alın.

```php
$jobs = Queuety::buried();
$jobs = Queuety::buried( 'emails' );
```

### `Queuety::pause( $queue )`

Çalışanların atlaması için bir kuyruğu duraklatın.

```php
Queuety::pause( 'emails' );
```

### `Queuety::resume( $queue )`

Duraklatılmış bir kuyruğu sürdürün.

```php
Queuety::resume( 'emails' );
```

### `Queuety::is_paused( $queue )`

Bir kuyruğun duraklatılmış olup olmadığını kontrol edin.

```php
if ( Queuety::is_paused( 'emails' ) ) {
    // Queue is paused
}
```

## İş akışları

### `Queuety::workflow( $name )`

Bir iş akışı oluşturmaya başlayın. Bir `WorkflowBuilder` döndürür.

```php
$workflow_id = Queuety::workflow( 'generate_report' )
    ->then( FetchDataHandler::class )
    ->then( CallLLMHandler::class )
    ->then( FormatOutputHandler::class )
    ->dispatch( [ 'user_id' => 42 ] );
```

### `WorkflowBuilder` yöntemleri

| Yöntem | Açıklama |
|---|---|
| `then( string $handler_class, ?string $name = null )` | Sıralı bir adım ekler. Koşullu dallanma için isteğe bağlı ad. |
| `parallel( array $handler_classes )` | Paralel adım grubu ekler. |
| `for_each( string $items_key, string $handler_class, ?string $result_key = null, ForEachMode $mode = ForEachMode::All, ?int $quorum = null, ?string $reducer_class = null, ?string $name = null )` | İş akışı durumundaki her öğe için bir dal işi oluşturan dinamik for-each adımı ekler. |
| `repeat_while( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )` | Herkese açık bir durum anahtarı veya `RepeatCondition` sınıfı eşleşene kadar önceki adlandırılmış bir adıma döner. |
| `repeat_until( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )` | Herkese açık bir durum anahtarı veya `RepeatCondition` sınıfı eşleşene kadar önceki adlandırılmış bir adıma döner. |
| `run_workflow( string $workflow_name, WorkflowBuilder $sub_builder )` | İş akışı çalıştırma adımı ekler. |
| `delay( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )` | Kalıcı gecikme adımı ekler. Tüm süreler toplanır. |
| `wait_for_signal( string $name, ?string $result_key = null, ?string $step_name = null, array $match_payload = [], ?string $correlation_key = null )` | Sinyal bekleme adımı ekler. İlgisiz olayları yok saymak için isteğe bağlı `match_payload` ve `correlation_key` kullanılabilir. |
| `wait_for_signals( array $signal_names, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | İsteğe bağlı yük eşleştirme ve korelasyonla birkaç sinyalin tümünü veya herhangi birini bekler. |
| `wait_for_approval( string $signal_name = 'approval', ?string $result_key = 'approval', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | İnsan onayı sinyalini bekler. |
| `wait_for_decision( string $approve_signal = 'approved', string $reject_signal = 'rejected', ?string $result_key = 'decision', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | Onay veya ret sinyalini bekler ve yapılandırılmış karar yükünü kaydeder. |
| `wait_for_input( string $signal_name = 'input', ?string $result_key = 'input', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | İnsan girdisi sinyalini bekler. |
| `wait_for_workflow( int\|string $workflow, ?string $result_key = null, ?string $name = null )` | Tek bir iş akışı kimliğinin veya herkese açık durumda kayıtlı bir iş akışı kimliğinin tamamlanmasını bekler. |
| `wait_for_workflows( array\|string $workflows, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, ?int $quorum = null )` | Birkaç iş akışının tümünün, herhangi birinin veya yeterli sayıda iş akışının tamamlanmasını bekler. |
| `wait_for_workflow_group( string $group_key, WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = null, ?string $name = null )` | Daha önce başlatılmış bir iş akışı grubunu dahili grup anahtarına göre bekler. |
| `start_workflows( string $items_key, WorkflowBuilder $workflow_builder, string $result_key = 'started_workflow_ids', string $payload_key = 'item', bool $inherit_state = true, ?string $name = null, ?string $group_key = null )` | İsteğe bağlı olarak başlatılan kümeye kalıcı grup anahtarı ekleyerek, çalışma zamanı öğesi başına bir üst düzey iş akışı dağıtır. |
| `start_agents( string $items_key, WorkflowBuilder $workflow_builder, string $result_key = 'agent_workflow_ids', string $payload_key = 'agent_task', bool $inherit_state = true, ?string $name = null, ?string $group_key = null )` | `start_workflows()` için aracı odaklı takma ad. |
| `wait_for_agents( array\|string $workflows = 'agent_workflow_ids', WaitMode $mode = WaitMode::All, ?string $result_key = 'agent_results', ?string $name = null, ?int $quorum = null )` | `wait_for_workflows()` için aracı odaklı takma ad. |
| `wait_for_agent_group( string $group_key = 'agents', WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = 'agent_results', ?string $name = null )` | `wait_for_workflow_group()` için aracı odaklı takma ad. |
| `version( string $version )` | İş akışı tanımına inceleme ve dışa aktarma için uygulama düzeyinde sürüm ekler. |
| `idempotency_key( string $key )` | İş akışı dağıtımını çağıranın sağladığı bir anahtar için kalıcı kılar. Aynı anahtarla yeniden dağıtım, özgün iş akışı kimliğini döndürür. |
| `max_transitions( int $max )` | `$max` adımdan fazla geçiş tamamlanırsa iş akışını başarısız kılar. |
| `max_for_each_items( int $max )` | Bir `for_each()` adımı `$max` öğeden fazlasını genişletmeye çalışırsa iş akışını başarısız kılar. |
| `max_state_bytes( int $bytes )` | Herkese açık durum `$bytes` sınırını aşarsa iş akışını başarısız kılar. |
| `max_cost_units( int $max )` | Tamamlanan adımlar `$max` maliyet biriminden fazlasını tüketirse iş akışını başarısız kılar. |
| `max_started_workflows( int $max )` | `$max` alt iş akışından fazlasını dağıtmadan önce iş akışını başarısız kılar. |
| `compensate_with( string $handler_class )` | En son eklenen adıma telafi işleyicisi ekler. |
| `compensate_on_failure()` | İş akışı başarısız olduğunda tamamlanmış adımların telafilerini otomatik olarak çalıştırır. |
| `on_queue( string $queue )` | Tüm adımlar için kuyruğu belirler. |
| `with_priority( Priority $priority )` | Tüm adımlar için önceliği belirler. |
| `max_attempts( int $max )` | Adım başına en fazla yeniden deneme sayısını belirler. |
| `on_cancel( string $handler_class )` | İptal için temizleme işleyicisi sınıfı kaydeder. [İptal](https://queuety.inline0.dev/tr/docs/workflows/cancellation) bölümüne bakın. |
| `prune_state_after( int $steps = 2 )` | Otomatik durum budamayı etkinleştirir. Eşikten eski adım çıktılarını kaldırır. [Durum Budama](https://queuety.inline0.dev/tr/docs/features/state-pruning) bölümüne bakın. |
| `must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )` | İş akışı için son tarih belirler. Tüm süreler toplanır. [Son Tarihler](https://queuety.inline0.dev/tr/docs/workflows/deadlines) bölümüne bakın. |
| `on_deadline( string $handler_class )` | İş akışının son tarihi aşıldığında çağrılan işleyiciyi kaydeder. [Son Tarihler](https://queuety.inline0.dev/tr/docs/workflows/deadlines) bölümüne bakın. |
| `dispatch( array $initial_payload = [] )` | İş akışını dağıtır. İş akışı kimliğini döndürür. |

### `Queuety::workflow_status( $workflow_id )`

İş akışı durumunu alın. Bir `WorkflowState` nesnesi veya `null` döndürür.

```php
$state = Queuety::workflow_status( $workflow_id );
echo $state->name;          // 'generate_report'
echo $state->status->value; // 'running'
echo $state->current_step;  // 1
echo $state->total_steps;   // 3
print_r( $state->state );   // accumulated public state array
echo $state->wait_type;     // 'signal' or 'workflow' while blocked
echo $state->wait_mode;     // 'all', 'any', or 'quorum'
echo $state->definition_version; // 'research.v2'
echo $state->definition_hash;    // '4c7a...'
echo $state->idempotency_key;    // 'brief:42:research'
echo $state->artifact_count;     // 2
print_r( $state->budget );       // configured workflow budget + current usage
print_r( $state->wait_details ); // matched/remaining blockers, result key, correlation info
print_r( $state->artifact_keys ); // ['draft', 'citations']
```

`WorkflowState` ayrıca şunları sunar:

- `waiting_for`: çalıştırmayı şu anda engelleyen sinyal adları veya iş akışı kimlikleri
- `current_step_name`: varsa, geçerli adım için yapılandırılmış ad
- `wait_mode`: engellenme sırasında geçerli bekleme modu (`all`, `any` veya `quorum`)
- `wait_details`: eşleşen ve kalan engelleyiciler gibi ek inceleme verileri
- `definition_version`: varsa, `version()` tarafından ayarlanan değer
- `definition_hash`: iş akışı tanımının deterministik özeti
- `idempotency_key`: varsa, kalıcı dağıtım anahtarı
- `budget`: koruma kuralları etkinse yapılandırılmış sınırlar ve geçerli kullanım
- `artifact_count`: iş akışı için saklanan yapıt sayısı
- `artifact_keys`: hızlı inceleme için saklanan yapıt anahtarları

### `Queuety::retry_workflow( $workflow_id )`

Başarısız olmuş bir iş akışını, başarısız olduğu adımdan yeniden deneyin.

```php
Queuety::retry_workflow( $workflow_id );
```

İş akışı, bir başarısızlıktan sonra telafi edilmişse `RuntimeException` fırlatır.

### `Queuety::pause_workflow( $workflow_id )`

Çalışan bir iş akışını duraklatın. Geçerli adım için kuyruğa alınmış işler yine de tamamlanabilir, ancak iş akışını sürdürünceye kadar sonraki adımlar kuyruğa alınmaz.

```php
Queuety::pause_workflow( $workflow_id );
```

### `Queuety::resume_workflow( $workflow_id )`

Duraklatılmış bir iş akışını sürdürün.

```php
Queuety::resume_workflow( $workflow_id );
```

### `Queuety::cancel_workflow( $workflow_id )`

Bir iş akışını iptal edin ve kayıtlı tüm temizleme işleyicilerini çalıştırın. Durumu `cancelled` olarak ayarlar ve iş akışının bekleyen ve işlenen tüm işlerini gömer.

```php
Queuety::cancel_workflow( $workflow_id );
```

İş akışı zaten `completed` veya `cancelled` ise `RuntimeException` fırlatır. Ayrıntılar için [İptal etme](https://queuety.inline0.dev/tr/docs/workflows/cancellation) bölümüne bakın.

### `Queuety::rewind_workflow( $workflow_id, $to_step )`

Bir iş akışını önceki bir adıma geri sarıp o adımdan yeniden çalıştırın. Durum, belirtilen adım için etkinlik günlüğü `state_after` üzerinden geri yüklenir ve sonraki adım kuyruğa alınır.

```php
Queuety::rewind_workflow( $workflow_id, to_step: 1 );
```

Hedef adım için kaydedilmiş durum yoksa `RuntimeException` fırlatır. [İş Akışı Etkinlik Günlüğü](https://queuety.inline0.dev/tr/docs/workflows/event-log) gerekir. Ayrıntılar için [Zamanda Yolculuk](https://queuety.inline0.dev/tr/docs/workflows/time-travel) bölümüne bakın.

### `Queuety::fork_workflow( $workflow_id )`

Çalışan bir iş akışının geçerli durumunda bağımsız bir kopyasını oluşturun. Yeni iş akışı kimliğini döndürür.

```php
$forked_id = Queuety::fork_workflow( $workflow_id );
```

Çatallanan iş akışı kendi kimliğini alır ve orijinalinden bağımsız çalışır. Ayrıntılar için [Dallandırma](https://queuety.inline0.dev/tr/docs/workflows/forking) bölümüne bakın.

### `Queuety::export_workflow( $workflow_id )`

Bir iş akışının tüm yürütme geçmişini JSON serileştirilebilir bir dizi olarak dışa aktarın. İş akışı satırını, tüm işleri, iş akışı etkinliklerini ve günlük girdilerini içerir.

```php
$data = Queuety::export_workflow( $workflow_id );
```

[Dışa Aktarma ve Yeniden Oynatma](https://queuety.inline0.dev/tr/docs/workflows/export-replay) bölümünde JSON yapısı ve kullanım alanları açıklanır.

### `Queuety::replay_workflow( $data )`

Dışa aktarılmış bir iş akışını geçerli ortamda yeniden oynatın. Dışa aktarma verilerinden yeni bir iş akışı oluşturur ve yeni iş akışı kimliğini döndürür.

```php
$new_id = Queuety::replay_workflow( $data );
```

Ayrıntılar için [Dışa Aktarma ve Yeniden Oynatma](https://queuety.inline0.dev/tr/docs/workflows/export-replay) bölümüne bakın.

### `Queuety::replace_wp_cron()`

Yerleşik WordPress cron sistemini Queuety zamanlayıcısıyla değiştirin. `wp_schedule_event()`, `wp_unschedule_event()` ve `wp_get_scheduled_event()` öğelerini yakalar ve yinelenen etkinlikleri Queuety çalışanına yönlendirir.

```php
Queuety::replace_wp_cron();
```

Yalnızca WordPress yüklüyse çalışır. Ayrıntılar için [WP-Cron Değişimi](https://queuety.inline0.dev/tr/docs/features/wp-cron) bölümüne bakın.

### `Queuety::restore_wp_cron()`

Queuety cron köprü kancalarını kaldırarak WordPress varsayılan cron davranışını geri yükleyin.

```php
Queuety::restore_wp_cron();
```

Sınırlamalar için [WP-Cron Değişimi](https://queuety.inline0.dev/tr/docs/features/wp-cron) bölümüne bakın.

### `Queuety::signal( $workflow_id, $name, $data )`

Bir iş akışına sinyal gönderin. İş akışı şu anda bu sinyali bekliyorsa hemen devam eder. Aksi durumda sinyal saklanır ve iş akışı ilgili `wait_for_signal` adımına ulaştığında alınır.

```php
Queuety::signal( $workflow_id, 'approved' );

// With data merged into workflow state
Queuety::signal( $workflow_id, 'approved', [
    'approved_by' => 'admin@example.com',
] );
```

Ayrıntılar için [İş Akışı Sinyalleri](https://queuety.inline0.dev/tr/docs/workflows/signals) bölümüne bakın.

### `Queuety::approve_workflow( $workflow_id, $data = [], $signal_name = 'approval' )`

Onay akışları için `signal()` çevresinde anlamsal sarmalayıcı.

```php
Queuety::approve_workflow( $workflow_id, [
    'reviewer' => 'editor@example.com',
] );
```

### `Queuety::reject_workflow( $workflow_id, $data = [], $signal_name = 'rejected' )`

Reddetme akışları için `signal()` çevresinde anlamsal sarmalayıcı.

```php
Queuety::reject_workflow( $workflow_id, [
    'reason' => 'needs citations',
] );
```

### `Queuety::submit_workflow_input( $workflow_id, $data = [], $signal_name = 'input' )`

Yapılandırılmış insan girdisi için `signal()` çevresinde anlamsal sarmalayıcı.

```php
Queuety::submit_workflow_input( $workflow_id, [
    'notes' => 'Ship after legal review',
] );
```

### `Queuety::put_artifact( $workflow_id, $artifact_key, $content, $kind = 'json', $step_index = null, $metadata = [] )`

Bir iş akışı için kalıcı bir yapıt saklayın.

```php
Queuety::put_artifact(
    $workflow_id,
    'research_brief',
    [ 'summary' => 'done' ],
    'json',
    metadata: [ 'source' => 'agent' ],
);
```

### `Queuety::put_current_artifact( $artifact_key, $content, $kind = 'json', $metadata = [] )`

Şu anda yürütülen iş akışı adımı için bir yapıt saklayın.

```php
Queuety::put_current_artifact(
    'draft',
    [ 'status' => 'ready' ],
    'json',
);
```

### `Queuety::workflow_artifact( $workflow_id, $artifact_key )`

Bir iş akışı için saklanan bir yapıtı alın.

```php
$artifact = Queuety::workflow_artifact( $workflow_id, 'draft' );
```

### `Queuety::workflow_artifacts( $workflow_id, $include_content = false )`

Bir iş akışının yapıtlarını listeleyin.

```php
$artifacts = Queuety::workflow_artifacts( $workflow_id );
```

### `Queuety::delete_workflow_artifact( $workflow_id, $artifact_key )`

Bir iş akışı için saklanan bir yapıtı silin.

```php
Queuety::delete_workflow_artifact( $workflow_id, 'draft' );
```

## Durum Makineleri

### `Queuety::machine( $name )`

Bir durum makinesi oluşturmaya başlayın. Bir `StateMachineBuilder` döndürür.

```php
use Queuety\Enums\StateMachineStatus;

$machine_id = Queuety::machine( 'agent_session' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'completed' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );
```

### `StateMachineBuilder` yöntemleri

| Yöntem | Açıklama |
|---|---|
| `initial( string $state_name )` | İlk durumu açıkça ayarlar. |
| `state( string $state_name, ?StateMachineStatus $terminal_status = null )` | Bir durumun yapılandırmasını başlatır. |
| `action( string\|array $action_class )` | Geçerli durum için kuyruğa alınmış bir giriş eylemi kaydeder. Bir sınıf adı veya `class`, `payload` ve `config` içeren yapılandırılmış bir tanım iletin; `payload`, `StateAction::handle()`'ye `$payload` olarak ulaşır. |
| `on( string $event, string $target, string\|array\|null $guard_class = null, ?string $name = null )` | Geçerli durumdan bir etkinlik geçişi kaydeder. Koruma, `action()` ile aynı yapılandırılmış biçimi kabul eder. |
| `on_queue( string $queue )` | Kuyruğa alınmış durum eylemleri için kullanılan kuyruğu ayarlar. |
| `with_priority( Priority $priority )` | Kuyruğa alınmış durum eylemlerinin önceliğini ayarlar. |
| `max_attempts( int $max_attempts )` | Kuyruğa alınmış durum eylemlerinin yeniden deneme sınırını ayarlar. |
| `version( string $version )` | Makine tanımını uygulama düzeyinde bir sürümle etiketler. |
| `idempotency_key( string $key )` | Çağıranın sağladığı bir anahtar için dağıtımı kalıcı hale getirir. Aynı anahtarla yeniden dağıtım, özgün makine kimliğini döndürür. |
| `dispatch( array $initial_state = [] )` | Makineyi dağıtır ve makine kimliğini döndürür. |

Durum giriş eylemi sınıfları, iş akışı adımlarının desteklediği kaynak ilkesi anahtarlarıyla aynı olan isteğe bağlı bir `config()` yöntemi de sunabilir: `concurrency_group`, `concurrency_limit` ve `cost_units`.

### `Queuety::dispatch_state_machine_definition( $definition, $initial_state = [], $options = [] )`

Serileştirilmiş bir durum makinesi tanım paketini dağıtın. Çoğu uygulama kodu `machine()->dispatch()` yöntemini tercih etmelidir. Bu daha alt düzey yöntem, bağdaştırıcıların doğrudan oluşturucuya bağımlı olmadan makine başlatabilmesi için sunulur.

```php
$machine_id = Queuety::dispatch_state_machine_definition(
    $definition,
    [ 'thread_id' => 42 ],
    [ 'idempotency_key' => 'thread:42' ],
);
```

### `Queuety::machine_status( $machine_id )`

Geçerli makine durumunu alın. Bir `StateMachineState` nesnesi veya `null` döndürür.

```php
$status = Queuety::machine_status( $machine_id );

echo $status->name;               // 'agent_session'
echo $status->status->value;      // 'waiting_event'
echo $status->current_state;      // 'awaiting_review'
print_r( $status->state );        // public machine state
print_r( $status->available_events ); // valid incoming events in the current state
```

`StateMachineState` ayrıca şunları sunar:

- `definition_version`
- `definition_hash`
- `idempotency_key`
- `error_message`
- `current_action`
- `terminal_status`

### `Queuety::machine_event( $machine_id, $event_name, $payload = [] )`

Bekleyen bir makineye harici bir etkinlik gönderin.

```php
Queuety::machine_event(
    $machine_id,
    'approve',
    [
        'approved' => true,
        'reviewer' => 'editor@example.com',
    ]
);
```

Yük, geçiş korumalarına sunulur ve etkinlik kabul edildiğinde genel makine durumuyla birleştirilir.

### `Queuety::list_machines( $limit = 50, $status = null )`

İnceleme için kalıcı makine satırlarını listeleyin.

```php
$machines = Queuety::list_machines();
$waiting  = Queuety::list_machines( status: 'waiting_event' );
```

Her satır makine kimliğini, adını, durumunu, geçerli durumunu, tanım sürümünü, tanım özetini, idempotensi anahtarını ve yaşam döngüsü zaman damgalarını içerir.

### `Queuety::machine_timeline( $machine_id, $limit = 100, $offset = 0 )`

Bir makinenin kalıcı etkinlik zaman çizelgesini alın.

```php
$timeline = Queuety::machine_timeline( $machine_id );
$page_two = Queuety::machine_timeline( $machine_id, 100, 100 );
```

Her etkinlik satırı şunları içerir: `id`, `machine_id`, `job_id`, `state_name`, `handler`, `event`, `event_name`, `transition_name`, `queue`, `attempt`, `input`, `output`, `state_before`, `state_after`, `context`, `artifacts`, `chunks`, `error`, `duration_ms` ve `created_at`.

### `Queuety::machine_trace( $machine_id )`

Bir durum makinesi hata ayıklayıcısı UI için normalleştirilmiş iz paketi alın.

```php
$trace = Queuety::machine_trace( $machine_id );
```

İz; `machine`, gruplandırılmış `states`, ham `events`, ilişkili eylem `jobs`, `logs`, `artifacts` ve `chunks` öğelerini içerir.

### `Queuety::machine_state_at( $machine_id, $event_id )`

Belirli bir makine iz etkinliğinden sonraki genel durumu alın; bulunamazsa `null` döndürür.

```php
$state = Queuety::machine_state_at( $machine_id, $event_id );
```

Yaşam döngüsü modeli ve kullanım örüntüleri için [Durum Makineleri](https://queuety.inline0.dev/tr/docs/state-machines) bölümüne bakın.

## İş akışı şablonları

### `Queuety::define_workflow( $name )`

Şablon olarak kullanmak üzere bir iş akışı oluşturucusu oluşturun.

```php
$builder = Queuety::define_workflow( 'onboarding' )
    ->then( CreateAccountHandler::class )
    ->then( SendWelcomeEmailHandler::class );
```

### `Queuety::register_workflow_template( $builder )`

Bir iş akışı şablonunu kaydedin.

```php
Queuety::register_workflow_template( $builder );
```

### `Queuety::run_workflow( $name, $payload, $options = [] )`

Kayıtlı bir iş akışı şablonunu adıyla dağıtın. İş akışı kimliğini döndürür.

```php
$workflow_id = Queuety::run_workflow( 'onboarding', [ 'email' => 'user@example.com' ] );

$workflow_id = Queuety::run_workflow(
    'onboarding',
    [ 'email' => 'user@example.com' ],
    [ 'idempotency_key' => 'onboarding:user@example.com' ],
);
```

Şablon kayıtlı değilse `RuntimeException` fırlatır.

### `Queuety::dispatch_workflow_definition( $definition, $payload, $options = [] )`

Çalışma zamanı tanım paketinden bir iş akışı dağıtın.

Çoğu uygulama kodu `run_workflow()` veya `workflow()->dispatch()` yöntemini tercih etmelidir. Bu daha alt düzey yöntem, yeniden kullanılabilir bağdaştırıcıların iç iş akışı yöneticisi yöntemlerine bağımlı olmadan serileştirilmiş bir iş akışı tanımını dağıtabilmesini sağlar.

```php
$workflow_id = Queuety::dispatch_workflow_definition(
    $definition,
    [ 'email' => 'user@example.com' ],
    [ 'idempotency_key' => 'onboarding:user@example.com' ],
);
```

### `Queuety::on_action( $hook, $workflow, $map = null, $when = null, $idempotency_key = null, $priority = 10, $accepted_args = null )`

İş akışı dağıtan bir WordPress eylemi kaydedin.

```php
Queuety::on_action(
    'save_post',
    workflow: 'content_review',
    map: static fn ( int $post_id, object $post, bool $update ): array => [
        'post_id' => $post_id,
        'post_type' => $post->post_type,
        'update' => $update,
    ],
    when: static fn ( int $post_id, object $post ): bool => 'post' === $post->post_type,
    idempotency_key: static fn ( int $post_id ): string => "save_post:{$post_id}",
);
```

`$workflow` şu değerlerden biri olabilir:

- kayıtlı bir iş akışı şablonu adı
- satır içi bir `WorkflowBuilder`

`map`, `when` ve `idempotency_key` geçerli WordPress isteğinin içinde eşzamanlı olarak çalışır. Dağıtımdan sonra yalnızca iş akışı adımları eşzamansız çalışır.

Kılavuzun tamamı için [Eylem Tetikleyicileri](https://queuety.inline0.dev/tr/docs/features/action-triggers) bölümüne bakın.

### `Queuety::workflow_templates()`

İş akışı şablonu kayıt defterini alın.

```php
$registry = Queuety::workflow_templates();
$template = $registry->get( 'onboarding' ); // WorkflowTemplate or null
```

### `Queuety::load_workflows( $directory, $recursive )`

Bir dizindeki tüm iş akışı dosyalarını yükleyip kaydedin. Her `.php` dosyasının bir `WorkflowBuilder` döndürmesi gerekir. Kaydedilen iş akışlarının sayısını döndürür.

```php
$count = Queuety::load_workflows( __DIR__ . '/workflows/' );
$count = Queuety::load_workflows( __DIR__ . '/workflows/', recursive: true );
```

### `Queuety::load_workflow_file( $file_path )`

Tek bir iş akışı dosyasını yükleyip kaydedin. Dosya bir oluşturucu döndürmezse `WorkflowTemplate` veya `null` döndürür.

```php
$template = Queuety::load_workflow_file( __DIR__ . '/workflows/onboard-user.php' );
```

## Zamanlama

### `Queuety::schedule( $handler, $payload )`

Yinelenen bir zamanlama oluşturun. Bir `PendingSchedule` oluşturucusu döndürür.

```php
Queuety::schedule( 'cleanup_handler' )
    ->every( '1 hour' )
    ->on_queue( 'maintenance' );

Queuety::schedule( 'nightly_report' )
    ->cron( '0 3 * * *' )
    ->on_queue( 'reports' );
```

### `PendingSchedule` yöntemleri

| Yöntem | Açıklama |
|---|---|
| `every( string $interval )` | Bir aralık ifadesi ayarlar (e.g. `1 hour`, `30 minutes`) |
| `cron( string $expression )` | 5 alanlı bir cron ifadesi ayarlar |
| `overlap( OverlapPolicy $policy )` | Çakışma ilkesini ayarlar (varsayılan: `Allow`). [Zamanlama](https://queuety.inline0.dev/tr/docs/features/scheduling) bölümüne bakın. |
| `on_queue( string $queue )` | Hedef kuyruğu ayarlar (varsayılan: `default`) |
| `id()` | Dağıtımı zorlayıp zamanlama kimliğini döndürür |

### `Queuety::scheduler()`

Dahili `Scheduler` örneğini alın.

```php
$scheduler = Queuety::scheduler();
$schedules = $scheduler->list();
$scheduler->remove( 'handler_name' );
$count = $scheduler->tick(); // manually trigger
```

## İşleyici kaydı

### `Queuety::register( $name, $class )`

Bir işleyici sınıfını bir adla kaydedin.

```php
Queuety::register( 'send_email', SendEmailHandler::class );
```

### `Queuety::discover_handlers( $directory, $namespace )`

Bir dizindeki işleyici sınıflarını otomatik olarak bulup kaydedin. Kaydedilen işleyici sayısını döndürür.

```php
$count = Queuety::discover_handlers( __DIR__ . '/handlers', 'MyPlugin\\Handlers' );
```

### `Queuety::registry()`

İşleyici kayıt defterini alın.

```php
$registry = Queuety::registry();
```

## Gözlemlenebilirlik

### `Queuety::logger()`

Günlük girdilerini sorgulamak için `Logger` örneğini alın.

```php
$logger = Queuety::logger();
$logs   = $logger->for_job( 42 );
$logs   = $logger->for_workflow( 7 );
$logs   = $logger->for_handler( 'send_email', 50 );
$logs   = $logger->for_event( LogEvent::Failed, 50 );
$logs   = $logger->since( new \DateTimeImmutable( '-1 hour' ), 100 );
$count  = $logger->purge( 30 );
```

### `Queuety::metrics()`

`Metrics` örneğini alın.

```php
$stats = Queuety::metrics()->handler_stats( 60 ); // last 60 minutes
```

### `Queuety::webhook_notifier()`

`WebhookNotifier` örneğini alın.

```php
$notifier = Queuety::webhook_notifier();
$id       = $notifier->register( 'job.buried', 'https://hooks.slack.com/...' );
$webhooks = $notifier->list();
$notifier->remove( $id );
```

### `Queuety::rate_limiter()`

`RateLimiter` örneğini alın.

```php
$limiter = Queuety::rate_limiter();
$limiter->register( 'call_openai', 60, 60 );
```

## Önbellek

### `Queuety::cache()`

Etkin önbellek arka ucunun örneğini alın.

```php
$cache = Queuety::cache();
$cache->set( 'my_key', 'my_value', 60 );
$value = $cache->get( 'my_key' );
```

### `Queuety::set_cache( $cache )`

Önbellek arka ucunu geçersiz kılın. Özel bir uygulama kullanmak için bu çağrıyı `Queuety::init()` öncesinde yapın.

```php
Queuety::set_cache( new RedisCache() );
Queuety::init( $connection );
```

### `QUEUETY_CACHE_TTL`

Varsayılan önbellek TTL değeri saniye cinsindendir (varsayılan: `5`). Dahili önbellek işlemlerinde kullanılan varsayılan TTL değerini değiştirmek için bu sabiti `wp-config.php` içinde ayarlayın.

```php
define( 'QUEUETY_CACHE_TTL', 10 );
```

Arka uçlar ve otomatik algılama hakkında ayrıntılar için [Önbelleğe Alma](https://queuety.inline0.dev/tr/docs/features/caching) bölümüne bakın.

## Durum makinesi etkinlik günlüğü

### `Queuety::machine_events()`

`StateMachineEventLog` örneğini alın.

```php
$log = Queuety::machine_events();
```

## İş akışı etkinlik günlüğü

### `Queuety::workflow_events()`

`WorkflowEventLog` örneğini alın.

```php
$log = Queuety::workflow_events();
```

### `Queuety::workflow_timeline( $workflow_id, $limit = 100, $offset = 0 )`

Bir iş akışının tüm etkinlik zaman çizelgesini alın. Kimliğe göre sıralanmış etkinlik satırlarından oluşan bir dizi döndürür.

```php
$events = Queuety::workflow_timeline( $workflow_id );
$next   = Queuety::workflow_timeline( $workflow_id, 100, 100 );
```

Her etkinlik satırı şunları içerir: `id`, `workflow_id`, `job_id`, `parent_event_id`, `step_index`, `step_name`, `step_type`, `handler`, `event`, `queue`, `attempt`, `input`, `output`, `state_before`, `state_after`, `context`, `artifacts`, `chunks`, `error`, `error_message` (`error.message` kaynağından kopyalanır), `duration_ms` ve `created_at`.

### `Queuety::workflow_trace( $workflow_id )`

Bir iş akışı hata ayıklayıcısı UI için normalleştirilmiş iz paketi alın.

```php
$trace = Queuety::workflow_trace( $workflow_id );
```

İz; `workflow`, gruplandırılmış `steps`, ham `events`, `jobs`, `logs`, `artifacts`, `chunks`, `signals` ve `wait_dependencies` öğelerini içerir.

### `Queuety::trace_input( $input )`

Şu anda yürütülen iş akışı adımına uygulama düzeyinde girdi ayarlayın.

### `Queuety::trace_output( $output )`

Şu anda yürütülen iş akışı adımı için uygulama düzeyinde çıktı ayarlayın.

### `Queuety::trace_context( array $context )`

Uygulama düzeyindeki bağlamı şu anda yürütülen iş akışı adımıyla birleştirin.

### `Queuety::workflow_state_at( $workflow_id, $step_index )`

Belirli bir iş akışı adımı tamamlandıktan veya sürdürüldükten sonraki genel durumu alın; bulunamazsa `null` döndürür.

```php
$state = Queuety::workflow_state_at( $workflow_id, 2 );
```

Kullanım alanları ve CLI komutları için [İş Akışı Etkinlik Günlüğü](https://queuety.inline0.dev/tr/docs/workflows/event-log) bölümüne bakın.

## Dahili örnekler

Bu yöntemler, ileri düzey kullanım senaryoları için dahili örnekler döndürür.

| Yöntem | Döndürülen | Açıklama |
|---|---|---|
| `Queuety::queue()` | `Queue` | Kuyruk işlemleri (alma, bırakma, gömme) |
| `Queuety::worker()` | `Worker` | Çalışan süreci denetimi |
| `Queuety::workflow_manager()` | `Workflow` | İş akışı düzenleme |
| `Queuety::machines()` | `StateMachine` | Durum makinesi yaşam döngüsü yönetimi |
| `Queuety::connection()` | `Connection` | Veritabanı bağlantısı |
| `Queuety::batch_manager()` | `BatchManager` | Toplu işlem yaşam döngüsü yönetimi (iptal etme, budama) |
| `Queuety::chunk_store()` | `ChunkStore` | Akış adımları için parçaların kalıcı olarak saklanması |
| `Queuety::machine_events()` | `StateMachineEventLog` | Durum makinesi iz etkinlikleri ve normalleştirilmiş iz paketleri |
| `Queuety::workflow_events()` | `WorkflowEventLog` | İş akışı iz etkinlikleri ve normalleştirilmiş iz paketleri |
| `Queuety::resource_manager()` | `ResourceManager` | Çalışan kabul profilleri, ağırlıklı bütçeler ve sistem belleği incelemesi |
| `Queuety::cache()` | `Cache` | Önbellek arka uç örneği |

## Test

### `Queuety::fake()`

Test için kuyruğu bellek içi bir sahteyle değiştirin. Veritabanına dokunmadan dağıtılan işleri kaydeden bir `QueueFake` örneği döndürür. `create_batch()` ayrıca sahte toplu işlem meta verilerini de kaydeder; zincirler, dağıttıkları ayrı ayrı gönderilmiş işler üzerinden doğrulanır.

```php
$fake = Queuety::fake();
SendEmailJob::dispatch( 'user@example.com', 'Hello', 'Hi!' );
$fake->assert_pushed( SendEmailJob::class );
```

### `Queuety::reset()`

Kuyruk sahtesi dahil tüm dahili durumu sıfırlayın. `tearDown()` içinde çağırın.

```php
Queuety::reset();
```

### `QueueFake` yöntemleri

| Yöntem | Açıklama |
|---|---|
| `assert_pushed( string $class, ?Closure $callback )` | Bir iş sınıfının kuyruğa eklendiğini doğrular. İsteğe bağlı geri çağırım, iş verilerine göre filtreleme yapar. |
| `assert_pushed_times( string $class, int $count )` | Bir işin tam N kez kuyruğa eklendiğini doğrular. |
| `assert_not_pushed( string $class )` | Bir işin hiç kuyruğa eklenmediğini doğrular. |
| `assert_nothing_pushed()` | Hiçbir işin kuyruğa eklenmediğini doğrular. |
| `assert_batched( ?Closure $callback )` | Bir toplu işlemin dağıtıldığını doğrular. İsteğe bağlı geri çağırım, toplu işlem verilerine göre filtreleme yapar. |
| `pushed( string $class )` | Bir sınıf için kaydedilmiş tüm dağıtımları alır. Bir dizi döndürür. |
| `batches()` | Kaydedilmiş tüm toplu işlemleri alır. Bir dizi döndürür. |
| `reset()` | Kaydedilmiş tüm işleri ve toplu işlemleri temizler. |

Tam örnekler için [Test](https://queuety.inline0.dev/tr/docs/features/testing) bölümüne bakın.

## Arayüzler

### `Handler`

Basit iş işleyicileri için arayüz.

```php
interface Handler {
    public function handle( array $payload ): void;
    public function config(): array;
}
```

`config()`, `queue`, `max_attempts`, `backoff`, `rate_limit`, `concurrency_group`, `concurrency_limit` ve `cost_units` döndürebilir.

### `Step`

İş akışı adımı işleyicileri için arayüz.

```php
interface Step {
    public function handle( array $state ): array;
    public function config(): array;
}
```

`config()`, `max_attempts`, `backoff`, `concurrency_group`, `concurrency_limit` ve `cost_units` döndürebilir.

### `Contracts\ForEachHandler`

Dinamik for-each dalı işleyicileri için arayüz.

```php
namespace Queuety\Contracts;

interface ForEachHandler {
    public function handle_item( array $state, mixed $item, int $index ): array;
    public function config(): array;
}
```

`config()`, `max_attempts`, `backoff`, `rate_limit`, `concurrency_group`, `concurrency_limit` ve `cost_units` döndürebilir.

### `Contracts\ForEachReducer`

for-each sonuçları için isteğe bağlı bir indirgeyici.

```php
namespace Queuety\Contracts;

interface ForEachReducer {
    public function reduce( array $state, array $for_each ): array;
}
```

### `Contracts\Compensation`

Adım telafi işleyicileri için arayüz.

```php
namespace Queuety\Contracts;

interface Compensation {
    public function handle( array $state ): void;
}
```

### `Contracts\RepeatCondition`

Durum anahtarı karşılaştırmasının yetersiz kaldığı durumlarda `repeat_until()` ve `repeat_while()` tarafından kullanılan döngü koşulları için arayüz.

```php
namespace Queuety\Contracts;

interface RepeatCondition {
    public function matches( array $state ): bool;
}
```

### `Contracts\StateAction`

Kuyruğa alınmış durum girişi eylemleri için arayüz.

```php
namespace Queuety\Contracts;

interface StateAction {
    public function handle( array $state, ?string $event = null, array $event_payload = [], array $payload = [] ): array|string;
}
```

`$payload`, varsa makine tanımındaki yapılandırılmış `payload` bilgisini taşır. Genel durum güncellemelerini döndürün. Eylemin hemen geçiş yapması gerekiyorsa `_event` ve isteğe bağlı olarak `_event_payload` ekleyin.

Durum eylemleri isteğe bağlı bir `config()` yöntemi de tanımlayabilir. Giriş eylemi kuyruğa alındığında Queuety bu yöntemden `concurrency_group`, `concurrency_limit` ve `cost_units` değerlerini okur.

### `Contracts\StateGuard`

Durum makinesi geçiş korumaları için arayüz.

```php
namespace Queuety\Contracts;

interface StateGuard {
    public function allows( array $state, array $event_payload, string $event, array $payload = [] ): bool;
}
```

### `Contracts\Job`

Kendi başına çalışabilen dağıtılabilir iş sınıfları için arayüz. İş sınıfları yüklerini genel özellikler, yürütme mantığını ise `handle()` içinde kapsüller.

```php
namespace Queuety\Contracts;

interface Job {
    public function handle(): void;
}
```

İş sınıfları isteğe bağlı olarak `middleware()` metodunu tanımlayıp `Contracts\Middleware` örneklerinden oluşan bir dizi döndürebilir.

### `Contracts\Cache`

Önbellek arka uçları için arayüz. Yerleşik uygulamalar ve özel arka uçlar için [Önbelleğe Alma](https://queuety.inline0.dev/tr/docs/features/caching) bölümüne bakın.

```php
namespace Queuety\Contracts;

interface Cache {
    public function get( string $key ): mixed;
    public function set( string $key, mixed $value, int $ttl = 0 ): void;
    public function delete( string $key ): void;
    public function has( string $key ): bool;
    public function add( string $key, mixed $value, int $ttl = 0 ): bool;
    public function flush(): void;
}
```

| Yöntem | Döndürülen | Açıklama |
|---|---|---|
| `get( $key )` | `mixed` | Bir değeri alır. Bulunamaz veya süresi dolmuşsa `null` döndürür. |
| `set( $key, $value, $ttl )` | `void` | Bir değeri saklar. TTL değerinin 0 olması, sürenin dolmayacağı anlamına gelir. |
| `delete( $key )` | `void` | Bir değeri kaldırır. |
| `has( $key )` | `bool` | Bir anahtarın mevcut olup olmadığını ve süresinin dolup dolmadığını denetler. |
| `add( $key, $value, $ttl )` | `bool` | Atomik olarak yalnızca mevcut değilse ayarlar. Değer ayarlanırsa `true` döndürür. |
| `flush()` | `void` | Önbellekteki tüm öğeleri kaldırır. |

### `WorkflowEventLog`

İş akışı adımı geçişlerini tam iz bağlamıyla kaydeder. Erişim: `Queuety::workflow_events()`.

| Yöntem | Döndürülen | Açıklama |
|---|---|---|
| `record_event( array $event )` | `void` | Ham bir iz etkinliğini kaydeder |
| `record_step_started( ... )` | `void` | Yürütme öncesindeki girdi ve durumla birlikte bir step_started etkinliği kaydeder |
| `record_step_completed( ... )` | `void` | Girdi, çıktı, önceki durum ve sonraki durumla birlikte bir step_completed etkinliği kaydeder |
| `record_step_failed( ... )` | `void` | İz bağlamı ve yapılandırılmış hata ayrıntılarıyla bir step_failed etkinliği kaydeder |
| `get_timeline( int $workflow_id, ?int $limit = 100, int $offset = 0 )` | `array` | İsteğe bağlı sayfalama ile iş akışı iz etkinliklerini sırayla alır |
| `get_trace( int $workflow_id )` | `array` | Normalleştirilmiş bir iz paketi alır |
| `get_state_at_step( int $workflow_id, int $step_index )` | `array\|null` | Belirli bir adım tamamlandıktan veya sürdürüldükten sonraki genel durumu alır |
| `prune( int $older_than_days )` | `int` | Belirtilen gün sayısından eski etkinlikleri siler. Silinen satır sayısını döndürür. |

### `StateMachineEventLog`

Durum makinesi yaşam döngüsü, eylem, geçiş ve koruma etkinliklerini, iş akışı etkinlikleriyle aynı iz alanlarıyla kaydeder.

| Yöntem | Döndürdüğü | Açıklama |
|---|---|---|
| `record_event( array $event )` | `void` | Ham makine izi olayını kaydeder |
| `get_timeline( int $machine_id, ?int $limit = 100, int $offset = 0 )` | `array` | Makine izi olaylarını sırayla, isteğe bağlı sayfalama ile alır |
| `get_trace( int $machine_id )` | `array` | Normalleştirilmiş makine izi paketi alır |
| `get_state_at_event( int $machine_id, int $event_id )` | `array\|null` | Belirli bir makine izi olayından sonraki herkese açık durumu alır |
| `prune( int $older_than_days )` | `int` | Belirtilen günden daha eski olayları siler. Silinen satırları döndürür. |

### `Contracts\StreamingStep`

Parça akışı üreten iş akışı adımı işleyicileri için arayüz. Üretilen her değer anında veritabanına kaydedilir. Bkz. [Akış Adımları](https://queuety.inline0.dev/tr/docs/workflows/streaming).

```php
namespace Queuety\Contracts;

interface StreamingStep {
    public function stream( array $state, array $existing_chunks = [] ): \Generator;
    public function on_complete( array $chunks, array $state ): array;
    public function config(): array;
}
```

| Yöntem | Açıklama |
|---|---|
| `stream( $state, $existing_chunks )` | Dize parçaları üreten üreteç. Her üretim anında bir DB yazma işlemini tetikler. Yeniden denemede `$existing_chunks` daha önce kaydedilmiş parçaları içerir. |
| `on_complete( $chunks, $state )` | Akış tamamlandıktan sonra çağrılır. İş akışı durumuyla birleştirilecek verileri döndürür. |
| `config()` | İsteğe bağlı yapılandırma. `max_attempts`, `backoff`, `concurrency_group`, `concurrency_limit` ve `cost_units` desteklenir. |

### `ChunkStore`

Akış adımları için parçaların kalıcılığını yönetir. `Queuety::chunk_store()` üzerinden erişin.

| Yöntem | Döndürdüğü | Açıklama |
|---|---|---|
| `get_chunks( int $job_id )` | `string[]` | Bir işin tüm parçalarını parça dizinine göre sıralı olarak getirir |
| `append_chunk( int $job_id, int $chunk_index, string $content, ?int $workflow_id, ?int $step_index )` | `void` | Tek bir parça ekler |
| `clear_chunks( int $job_id )` | `void` | Bir işe ait tüm parçaları siler |
| `chunk_count( int $job_id )` | `int` | Bir işin parçalarını sayar |
| `get_accumulated( int $job_id )` | `string` | Tüm parçaları tek bir dizede birleştirir |

### `Heartbeat`

Adım işleyicilerinin ve akış adımlarının içinden etkinlik sinyalleri göndermeye yarayan statik yardımcı. Bkz. [Sinyal Atımları](https://queuety.inline0.dev/tr/docs/features/heartbeats).

| Yöntem | Açıklama |
|---|---|
| `Heartbeat::init( int $job_id, Connection $conn )` | İş bağlamını ayarlar. Çalışan tarafından otomatik çağrılır. |
| `Heartbeat::beat( array $progress = [] )` | Sinyal atımı gönderir. `reserved_at` değerini günceller ve isteğe bağlı olarak ilerleme verilerini `heartbeat_data` içinde saklar. |
| `Heartbeat::clear()` | İş bağlamını temizler. Çalışan tarafından otomatik çağrılır. |
| `Heartbeat::current_job_id()` | Geçerli iş kimliğini alır (test için). |

### `Contracts\Middleware`

İş ara katman yazılımı için arayüz. Ara katman yazılımı, iş yürütmesini soğan tarzı bir işlem hattıyla sarar.

```php
namespace Queuety\Contracts;

interface Middleware {
    public function handle( object $job, \Closure $next ): void;
}
```

## Özellikler

### `Dispatchable`

`Contracts\Job` uygulayan iş sınıflarına statik dağıtım yöntemleri sağlar. Kurucu bağımsız değişkenleri iş örneğini oluşturmak için aktarılır.

```php
use Queuety\Contracts\Job;
use Queuety\Dispatchable;

class SendEmailJob implements Job {
    use Dispatchable;
    // ...
}

// Dispatches a new SendEmailJob instance
SendEmailJob::dispatch( 'user@example.com', 'Subject', 'Body' );
```

| Yöntem | Döndürdüğü | Açıklama |
|---|---|---|
| `dispatch( ...$args )` | `PendingJob` | Bir örnek oluşturur ve dağıtır |
| `dispatch_if( bool $condition, ...$args )` | `PendingJob\|null` | Yalnızca `$condition` doğruysa dağıtır |
| `dispatch_unless( bool $condition, ...$args )` | `PendingJob\|null` | Yalnızca `$condition` yanlışsa dağıtır |
| `with_chain( array $jobs )` | `ChainBuilder` | Bu iş sınıfından bir zincir başlatır |

```php
// Conditional dispatch
SendEmailJob::dispatch_if( $user->wants_email, $user->email, 'Hello', 'Hi!' );
SendEmailJob::dispatch_unless( $maintenance_mode, $user->email, 'Hello', 'Hi!' );

// Chain from a job class
FetchDataJob::with_chain( [
    new ProcessDataJob(),
    new NotifyCompleteJob(),
] )->dispatch();
```

### İş özellikleri

İş sınıfları, çalışanın yeniden deneme ve zaman aşımı davranışını geçersiz kılmak için yansıma yoluyla okuduğu herkese açık özellikler bildirebilir.

| Özellik | Tür | Açıklama |
|---|---|---|
| `$tries` | `int` | İş gömülmeden önceki en yüksek deneme sayısı |
| `$timeout` | `int` | Saniye cinsinden en yüksek yürütme süresi (`pcntl` gerektirir) |
| `$backoff` | `array` | Her yeniden deneme için saniye cinsinden artan gecikme değerleri |

```php
class ImportProductsJob implements Job {
    use Dispatchable;

    public int $tries = 5;
    public int $timeout = 120;
    public array $backoff = [ 10, 30, 60, 120 ];

    // ...
}
```

### `failed()` kancası

Tüm yeniden denemeler tükendikten sonra bir iş gömüldüğünde, tanımlıysa çalışan iş örneğinde bir `failed()` yöntemi çağırır.

```php
public function failed( \Throwable $exception ): void {
    error_log( "Job failed: {$exception->getMessage()}" );
}
```

## Yerleşik ara katman yazılımları

Tüm ara katman yazılımı sınıfları `Contracts\Middleware` arayüzünü uygular ve `Queuety\Middleware` ad alanında bulunur.

| Sınıf | Açıklama |
|---|---|
| `RateLimited( int $max, int $window )` | `$window` saniyede `$max` yürütme sınırı uygular |
| `Timeout( int $seconds )` | `$seconds` saniye sonra işi sonlandırır (`pcntl` gerektirir) |
| `UniqueJob( ?string $key )` | Veritabanı kilidi aracılığıyla eşzamanlı yürütmeyi önler |
| `WithoutOverlapping( string $key, int $release_after )` | Kilidin otomatik sona ermesiyle çakışan yürütmeleri önler |
| `ThrottlesExceptions( int $max_attempts, int $decay_minutes )` | Harici hizmet devre dışıyken iş fırtınalarını önlemek için istisnaları sınırlar |

Kullanım ayrıntıları ve örnekler için bkz. [Ara Katman Yazılımı](https://queuety.inline0.dev/tr/docs/features/middleware).

## Enum'lar

### `Priority`

```php
enum Priority: int {
    case Low    = 0;
    case Normal = 1;
    case High   = 2;
    case Urgent = 3;
}
```

### `JobStatus`

```php
enum JobStatus: string {
    case Pending    = 'pending';
    case Processing = 'processing';
    case Completed  = 'completed';
    case Failed     = 'failed';
    case Buried     = 'buried';
}
```

### `WorkflowStatus`

```php
enum WorkflowStatus: string {
    case Running        = 'running';
    case Completed      = 'completed';
    case Failed         = 'failed';
    case Paused         = 'paused';
    case WaitingForSignal  = 'waiting_for_signal';
    case WaitingForWorkflows = 'waiting_for_workflows';
    case Cancelled      = 'cancelled';
}
```

### `StateMachineStatus`

```php
enum StateMachineStatus: string {
    case Running = 'running';
    case WaitingEvent = 'waiting_event';
    case Completed = 'completed';
    case Failed = 'failed';
    case Paused = 'paused';
    case Cancelled = 'cancelled';
}
```

### `BackoffStrategy`

```php
enum BackoffStrategy: string {
    case Fixed       = 'fixed';
    case Linear      = 'linear';
    case Exponential = 'exponential';
}
```

### `ForEachMode`

```php
enum ForEachMode: string {
    case All = 'all';
    case FirstSuccess = 'first_success';
    case Quorum = 'quorum';
}
```

### `WaitMode`

```php
enum WaitMode: string {
    case All    = 'all';
    case Any    = 'any';
    case Quorum = 'quorum';
}
```

### `LogEvent`

```php
enum LogEvent: string {
    case Started                  = 'started';
    case Completed                = 'completed';
    case Failed                   = 'failed';
    case Buried                   = 'buried';
    case Retried                  = 'retried';
    case WorkflowStarted          = 'workflow_started';
    case WorkflowCompleted        = 'workflow_completed';
    case WorkflowFailed           = 'workflow_failed';
    case WorkflowPaused           = 'workflow_paused';
    case WorkflowResumed          = 'workflow_resumed';
    case WorkflowCancelled        = 'workflow_cancelled';
    case WorkflowRewound          = 'workflow_rewound';
    case WorkflowForked           = 'workflow_forked';
    case WorkflowDeadlineExceeded = 'workflow_deadline_exceeded';
    case Debug                    = 'debug';
}
```

### `OverlapPolicy`

```php
enum OverlapPolicy: string {
    case Allow  = 'allow';
    case Skip   = 'skip';
    case Buffer = 'buffer';
}
```

Her politikanın nasıl çalıştığıyla ilgili ayrıntılar için bkz. [Zamanlama](https://queuety.inline0.dev/tr/docs/features/scheduling).

## Öznitelikler

### `#[QueuetyHandler]`

Otomatik kayıt için PHP 8 özniteliği. Bkz. [PHP Öznitelikleri](https://queuety.inline0.dev/tr/docs/features/attributes).

```php
use Queuety\Attributes\QueuetyHandler;

#[QueuetyHandler( name: 'send_email', queue: 'emails', max_attempts: 5 )]
class SendEmailHandler implements Handler {
    // ...
}
```

## CLI köprüsü

### `Queuety::cli_command()`

Yayımlanan WP-CLI kök komut adını döndürür.

Varsayılan kök komut `queuety` şeklindedir. Komut farklı bir ad altında yayımlanacaksa, Queuety başlatılmadan önce `QUEUETY_CLI_COMMAND` tanımlayın.

### `Queuety::cli_command_map()`

WP-CLI sınıflarını taramadan, gönderilen komut arayüzünü anlaması gereken test düzenekleri için serileştirilebilir Queuety CLI kataloğunu döndürür.

Her girdi şunları içerir:
- kararlı bir işlem kimliği
- göreli CLI yolu
- WP-CLI işleyici sınıfı ve yöntemi
- olası yürütme hedefleri
- ham CLI bağımsız değişkenlerini bir yürütme planına normalleştiren bağdaştırıcı

### `Queuety::resolve_cli_command( $path, $args, $assoc_args )`

Ayrıştırılmış bir CLI çağrısını, test düzeneğinin çalıştırması gereken yürütme planına dönüştürür.

```php
$plan = Queuety::resolve_cli_command(
    [ 'workflow', 'export' ],
    [ '42' ],
    [ 'output' => '/tmp/workflow.json' ]
);

echo $plan['callable']; // Queuety\Queuety::export_workflow_to_file
print_r( $plan['arguments'] );
```

Yürütme planları, aktarım yöntemini dikkate alacak şekilde tasarlanmıştır:
- komutlar, normalleştirilmiş bağımsız değişkenlerle herkese açık PHP çağrılabilirlerine çözümlenir
- katalog tüm olası yürütme hedeflerini önceden listelerken, `callable` ve `transport` ayrıştırılan girdi için seçilen dalı belirtir

Bu, aracı test düzeneklerinin kullandığı standart Queuety yöntemidir: kararlı işlem kimliği, herkese açık API hedefi ve kuyruk varsayılanları, JSON yükü çözümleme, çalışan havuzu dallandırma ve iş akışı dışa aktarma dosyalarını işleme gibi yalnızca CLI ile ilgili konular için bağdaştırıcıya ait normalleştirme.