# Cron Tur Kancaları

https://dev.wisecp.com/tr/cron-tur-kancalari

Kimsenin başında olmadığı işlerin kancaları: tur başlangıcı, görev kaydı, kuyruk, dakikalıktan aylığa periyodik turlar ve işçi yönetimi.

## Genel Bakış

Zamanlanmış görevler bir **tur** hâlinde çalışır: sistem dakikada bir uyanır, kuyruktaki işleri alır, gerekirse **yardımcı işçiler** açar ve biter.

Buradaki kancaların hepsinde ortak bir gerçek vardır: **ekranda kimse yoktur**. Fırlattığınız hata kimseye gösterilmez, yazdığınız çıktı kimseye ulaşmaz; tek izi kayıtlarda kalır.

## Referans

### Kendi zamanlanmış görevinizi kaydetme

registercronjobs

`CronJobQueue` kayıt yan etkiyle

Görev kayıtları toplanırken çalışır. Kendi görevinizi burada **kaydedersiniz**.

Parametreler 0

—Parametre almaz. Kayıt, dönüşle değil `CronJobQueue::register()` çağrısıyla yapılır.

Dönüş 1

voidDönüş yoksayılır; kayıt **yan etkiyle** yapılır.

Dinleyici PHP

```php
Hook::add('register:cronjobs', 10, function () {
    // Kayit DONUSLE degil, cagriyla yapilir.
    CronJobQueue::register('acme.sync', AcmeSyncHandler::class);
});
```

### Turun çalışmasını durdurma

gatecron.worker.run

`cron.php` çalışma ortamı bilgisi

Tur başlamadan önce çalışır. Durdurmak, o turda **hiçbir işin işlenmemesi** demektir.

Parametreler 2

$isCliboolKomut satırından mı çalışıyor. Yanlışsa istek üzerinden tetiklenmiştir.

$sapistringÇalıştıran arayüzün adı. Yalnız belirli bir ortamda çalışmasını istiyorsanız bu değere bakın.

Dönüş 1

stringBoş olmayan bir string turu **engeller**; metin yanıtta gerekçe olarak döner. Hata fırlatılmaz, tur sessizce geçilir.

Dinleyici PHP

```php
Hook::add('gate:cron.worker.run', 10, function ($isCli, $sapi) {
    // Bakim penceresinde hicbir gorev calismasin.
    if (Acme::maintenanceWindow()) return 'bakim penceresi';

    return null;
});
```

### Turun başladığını izleme

actioncron.tick.started

`cron.php` yardımcı olabilir

Tur başladığında çalışır.

Parametreler 3

$workerIdstringBu turun benzersiz işçi kimliği. Aynı anda birden çok tur koşabilir; kayıtlarınızı bu kimlikle ayırın.

$isChildboolBu bir **yardımcı işçi** mi. Doğruysa ana tur değil, yoğunluk nedeniyle açılmış bir yardımcıdır; her ikisi de bu kancayı çalıştırır.

$startTsintTur başlangıç zamanı.

Dönüş 1

voidDönüş yoksayılır.

Dinleyici PHP

```php
Hook::add('action:cron.tick.started', 10, function ($workerId, $isChild, $startTs) {
    // Yardimci isciler de bu kancayi calistirir: ikisini ayirin.
    if ($isChild) return;

    Ops::heartbeat($workerId, $startTs);
});
```

### Turun bittiğini izleme

actioncron.tick.completed

`cron.php` kısmi olabilir

Tur bittikten sonra çalışır.

Parametreler 2

$payloadarrayTur özeti: `status` (`ok` ya da `partial`), işçi kimliği, işlenen iş sayısı, süre, hatalar, zamanlayıcı ve yardımcı bilgisi. `partial` demek turun **işini bitiremediği** demektir.

$isChildboolYardımcı işçi mi.

Dönüş 1

voidDönüş yoksayılır.

Dinleyici PHP

```php
Hook::add('action:cron.tick.completed', 10, function ($payload, $isChild) {
    // partial = tur isini bitiremedi; ust uste gorulurse kapasite sorunudur.
    if (($payload['status'] ?? '') === 'partial')
        Ops::warn('cron-partial', (int) ($payload['processed'] ?? 0));
});
```

### İşlenen işi izleme

actioncron.job.processed

`CronJobQueue` her işte bir kez

Kuyruktaki bir iş işlendikten sonra çalışır.

Parametreler 2

$jobarrayİşlenen kuyruk satırı: kimlik, tür, veri, deneme sayısı. Deneme sayısı birden büyükse iş **daha önce düşmüştür**.

$workerIdstringİşi işleyen işçinin kimliği.

Dönüş 1

voidDönüş yoksayılır.

Dinleyici PHP

```php
Hook::add('action:cron.job.processed', 10, function ($job, $workerId) {
    // Deneme sayisi > 1 ise bu is daha once dusmus demektir.
    if ((int) ($job['attempts'] ?? 0) > 1)
        Ops::note('cron-retry', $job['type'] ?? '', (int) $job['attempts']);
});
```

### Günlük işe katılma

actioncron.day.run

`cronjobs/Daily` dönüşünüz kaydedilir

Günlük görev turunda çalışır. Diğer kancaların aksine **dönüşünüz kaydedilir**.

Parametreler 0

—Parametre almaz.

Dönüş 1

bool|arrayDönüşünüzü **toplar ve panelde gösterir**: başarı, süre ve hata olarak. Yanlış dönüş akışı kesmez, yalnız kaydınız kötü görünür.

Dinleyici PHP

```php
Hook::add('action:cron.day.run', 10, function () {
    // Donusunuz panelde gorunur: basarili ise true, degilse aciklama dondurun.
    $done = Acme::nightlyReport();

    return $done ? true : ['status' => false, 'message' => 'rapor uretilemedi'];
});
```

### Saatlik işe katılma

actioncron.hour.run

`cronjobs/HourlyExecute` dönüşünüz kaydedilir

Saatte bir çalışır. Kendi görev dosyanızı açmak yerine saatlik işi buraya bağlarsınız: önbellek temizliği, saatlik özet, dış sistemle eşitleme.

Parametreler 0

—Parametre almaz.

Dönüş 1

bool|arrayDönüşünüzü **toplar ve panelde gösterir**: başarı, süre ve hata olarak. Yanlış dönüş akışı kesmez, yalnız kaydınız kötü görünür.

Dinleyici PHP

```php
Hook::add('action:cron.hour.run', 10, function () {
    $n = Acme::syncPartnerCatalog();

    return ['status' => true, 'message' => $n . ' kayit esitlendi'];
});
```

### Dakikalık işe katılma

actioncron.minute.run

`cronjobs/PerMinuteExecute` dönüşünüz kaydedilir

Her dakika çalışır, turların en sıkışığı. Kuyruk boşaltma, dış sorgulama ve sağlık kontrolü için kullanın.

Parametreler 0

—Parametre almaz.

Dönüş 1

bool|arrayDönüşünüzü toplar ve panelde gösterir. Burada geçirdiğiniz süre her dakika tekrar ödenir: işiniz uzunsa kuyruğa bırakın, burada bitirmeyin.

Dinleyici PHP

```php
Hook::add('action:cron.minute.run', 10, function () {
    // Kisa tutun: bu blok her dakika calisir.
    $sent = Acme::drainOutbox(50);

    return ['status' => true, 'message' => $sent . ' mesaj gonderildi'];
});
```

### Aylık işe katılma

actioncron.month.run

`cronjobs/MonthlyExecute` dönüşünüz kaydedilir

Ayda bir çalışır: ay sonu özetleri, mutabakat, arşivleme.

Parametreler 0

—Parametre almaz.

Dönüş 1

bool|arrayDönüşünüzü toplar ve panelde gösterir. Ayda bir çalıştığı için bir hatayı fark etmeniz bir ay sürebilir; dönüşe açıklayıcı bir ileti koyun.

Dinleyici PHP

```php
Hook::add('action:cron.month.run', 10, function () {
    $rows = Acme::archiveLastMonth();

    return ['status' => true, 'message' => $rows . ' satir arsivlendi'];
});
```

### Yardımcı işçi sayısını değiştirme

filtercron.spawn.count

`cron.php` sunucu yükü

Yoğunluk nedeniyle kaç yardımcı işçi açılacağına karar verildikten sonra çalışır.

Parametreler 1

$decisionarrayrefKarar: `count` (açılacak sayı), bekleyen iş, etkin işçi, eşik, üst sınır, gerekçe. Etkili olan alan **`count`**; diğerleri kararı anlamanız içindir.

Dönüş 1

voidDeğer **referansla** değişir; dönüş kullanılmaz.

Dinleyici PHP

```php
Hook::add('filter:cron.spawn.count', 10, function (&$decision) {
    // Yalniz count etkilidir; sunucu yuku yuksekken yardimci acmayin.
    if (Acme::loadHigh()) $decision['count'] = 0;
});
```

### Pano grafiği görev listesini değiştirme

filtercron.dashboard_chart_tasks

`automation/dashboard` bağla geçer

Otomasyon panosundaki etkinlik grafiğinin görev seçicisi hazırlanırken çalışır. Kendi görev tipinizi listeye ekleyebilir, dahili olanları gizleyebilirsiniz.

Parametreler 1

$optionsarraybağlaSeçici içeriği: anahtar görev adı, değer ekranda görünen başlık. Bağla geçer: değişikliği **döndürerek değil**, dizinin üzerine yazarak yaparsınız.

Dönüş 1

voidDönüş yoksayılır. Sıralama sizden önce yapılır; eklediğiniz öğe listenin sonunda kalır.

Dinleyici PHP

```php
Hook::add('filter:cron.dashboard_chart_tasks', 10, function (&$options) {
    // Kendi gorevinizi listeye ekleyin.
    $options['acme-sync'] = 'Acme esitleme';

    // Dahili olani gizleyin.
    unset($options['queue-cleanup']);
});
```

### Elle çalıştırmayı durdurma

gatecron.task_run_now

`AdminAutomation` operatör tetikliyor

Operatör bir görevi elle çalıştırmadan önce çalışır.

Parametreler 2

$taskstringÇalıştırılacak görevin anahtarı.

$user_idintİşlemi yapan personelin kimliği.

Dönüş 1

stringBoş olmayan bir string çalıştırmayı **durdurur**; metin operatöre hata olarak gösterilir. Bu kanca panelde tetiklendiği için mesajınızı **gerçekten okuyan biri** vardır.

Dinleyici PHP

```php
Hook::add('gate:cron.task_run_now', 10, function ($task, $user_id) {
    // Panelden tetiklenir: mesajinizi okuyan bir insan var.
    if ($task === 'invoice.generate' && Acme::billingFrozen())
        return 'Faturalama donduruldu; bu gorev simdi calistirilamaz.';

    return null;
});
```

### Acil durdurmayı izleme

actioncron.kill_switch_toggled

`AdminAutomation` her şey durur

Zamanlanmış görevlerin tamamı açılıp kapatıldığında çalışır.

Parametreler 2

$enabledboolYeni durum. Kapalıyken **hiçbir görev çalışmaz**: faturalar kesilmez, hizmetler askıya alınmaz, yenilemeler olmaz.

$user_idintİşlemi yapan personel.

Dönüş 1

voidDönüş yoksayılır.

Dinleyici PHP

```php
Hook::add('action:cron.kill_switch_toggled', 10, function ($enabled, $user_id) {
    // Kapatmak butun otomasyonu durdurur: unutulursa fatura bile kesilmez.
    if (!$enabled) Ops::alert('cron-disabled', (int) $user_id);
});
```

## Tuzaklar

> **Burada hata fırlatmak kimseye ulaşmaz**
> 
> Zamanlanmış görev kancalarında **ekranda kimse yoktur**. Fırlattığınız hata müşteriye de operatöre de gösterilmez; yalnız kayıtlara düşer. Bir şeyin yanlış gittiğini duyurmak istiyorsanız bunu **kendiniz** yapın: bildirim, kayıt ya da uyarı.

> **Yardımcı işçiler aynı kancaları çalıştırır**
> 
> Yoğunluk arttığında sistem yardımcı işçiler açar ve **her biri** tur kancalarını çalıştırır. "Tur başladı" kancasına bildirim yazarsanız yoğun bir dakikada **onlarca** bildirim gider. İkinci parametredeki yardımcı işaretini okuyun.

> **Aynı iş birden çok kez işlenebilir**
> 
> Düşen bir iş **yeniden denenir** ve işlendi kancası her denemede çalışır. Deneme sayısını okumadan tepki veren bir dinleyici, tek bir iş için art arda kayıt ya da bildirim üretir. Sayacı **ilk satırda** kontrol edin.

> **Günlük iş kancasında dönüşünüz kaydedilir**
> 
> Periyodik iş kancaları, diğer olay kancalarının aksine **dönüşünüzü toplar** ve panelde başarı, süre, hata olarak gösterir. Hiçbir şey döndürmemek kaydınızı "belirsiz" bırakır. Başarıda doğru, başarısızlıkta **açıklamalı bir dizi** dönün.

## İlgili Makaleler

- Zamanlanmış Görev Kancaları
- [Hizmet Durum Kancaları](https://dev.wisecp.com/tr/hizmet-durum-kancalari)
- [Fatura Yaşam Döngüsü Kancaları](https://dev.wisecp.com/tr/fatura-yasam-dongusu-kancalari)