Zamanlanmış Görevler (Scheduler)

Bu Proje Nedir?

Bir projede zamanlanmış işler çoğalmaya başlar: gece günlük temizliği, 15 dakikada bir sağlık kontrolü, pazar sabahı yedek. Her biri için sunucuya ayrı bir cron satırı yazılır. Sonra şu sorunlar sırayla gelir:

• Hangi görevler var? Cevap crontab -e çıktısındadır; ekipteki çoğu kişi ona erişemez.
• Dün gece çalıştı mı? Cevap yoktur. Cron çıktısı /dev/null'a gidiyorsa hiçbir iz kalmaz.
• Neden iki kez çalıştı? Önceki çalışma bitmeden yenisi başladı; ikisi aynı tabloyu yazdı.
• Bir görevi geçici olarak durdurmak için sunucuya SSH ile bağlanmak gerekir.

Bu proje sorunu tersine çevirir: sunucuya tek bir cron satırı yazılır ve o satır her dakika bin/scheduler.php dosyasını çağırır. Hangi görevin ne zaman çalışacağı artık veritabanındadır, panelden yönetilir; her çalışma süresi, çıktısı ve durumuyla birlikte kaydedilir.

Cron ifadelerini ayrıştıran, ne zaman çalışacağını hesaplayan ve insan diline çeviren CronExpression sınıfı da projenin içindedir — harici bir kütüphane kullanılmaz.

Kimler için uygun?

• Birden fazla zamanlanmış işi olan ve hepsini tek yerden görmek isteyenler
• "Gece raporu çalıştı mı?" sorusunu cevaplamak zorunda kalanlar
• Üst üste binen (overlap) görevlerden dolayı çift kayıt üretenler
• Cron ifadelerinin PHP'de nasıl ayrıştırıldığını öğrenmek isteyenler
• Bootstrap 5 üzerine kurulu, tekrar kullanılabilir bir panel kalıbı arayanlar

Bu proje, Çılgın Yazılım Kütüphanesi altında yayınlanan açıklamalı, üretime hazır örneklerden biridir.

---

Tek cron satırı

Sunucuya yazılacak tek satır budur:

* * * * * cd /var/www/uygulama && php bin/scheduler.php >> /dev/null 2>&1

Her dakika çalışır, veritabanındaki görevlere bakar ve zamanı gelenleri çalıştırır. Yeni bir görev eklediğinizde sunucuya dokunmanız gerekmez; panele bir satır eklemeniz yeter.

Windows'ta Görev Zamanlayıcı'dan her dakika tekrarlanan bir görev tanımlayın:

Elle denemek için:

php bin/scheduler.php --list      # görevler ve sıradaki çalışma zamanları
php bin/scheduler.php             # zamanı gelenleri çalıştır
php bin/scheduler.php --run=3     # 3 numaralı görevi zamanına bakmadan çalıştır
php bin/scheduler.php --quiet     # çıktı verme (cron için)
php bin/scheduler.php --help

---

Kritik Kararlar

1. Üst üste binmeyi kilit engeller — ve kilidin zaman aşımı vardır

Cron her dakika çalışır. Görev 90 saniye sürerse ikinci çalışma, birincisi bitmeden başlar. İkisi aynı tabloyu yazarsa çift kayıt üretirsiniz.

Klasik ve yanlış çözüm:

if ($task['locked_at'] === null) {        // ◄── yarış koşulu
    $db->exec("UPDATE tasks SET locked_at = NOW() WHERE id = {$id}");
    // ...
}

İki süreç if'i aynı anda geçebilir. Doğrusu, kontrolü ve yazmayı tek ifadede yapmaktır:

UPDATE scheduled_tasks
   SET locked_at = NOW()
 WHERE id = :id
   AND (locked_at IS NULL OR locked_at < (NOW() - INTERVAL :timeout SECOND))

if ($lock->rowCount() === 0) {
    return false;   // kilidi başkası aldı, bu çalışmayı atla
}

Zaman aşımı olmazsa ne olur? Süreç çökerse locked_at sonsuza kadar dolu kalır ve görev bir daha hiç çalışmaz — üstelik sessizce. Bu yüzden kilit her zaman "şu kadar saniyeden eskiyse geçersiz say" kuralıyla birlikte kurulur. Süre her görev için ayrı ayarlanabilir (lock_timeout); yedekleme görevine 3600, sağlık kontrolüne 300 saniye verilmiştir.

2. Cron ifadesi PHP'de ayrıştırılır, kütüphane kullanılmaz

CronExpression sınıfı beş alanı ayrıştırır ve üç soruya cevap verir:

nextRun() sayesinde panel "Sıradaki: 04.09.2026 03:00" yazabilir. Bu, cron'un normalde vermediği bir bilgidir ve bir görevin yanlış kurulduğunu anında gösterir: beklediğiniz tarih değilse ifade hatalıdır.

describe() ise */15 * * * * ifadesini "Her 15 dakikada bir" diye yazar. Cron sözdizimi, günde bir kez bakan biri için hiçbir zaman sezgisel olmaz.

Ayrıştırma ayrıntısı: alanlar explode(' ') ile değil preg_split('/\s+/') ile ayrılır. Kullanıcı 0 3 * * * gibi çift boşluk yazarsa explode boş parçalar üretir ve ifade geçersiz sayılırdı.

3. Görev tanımı veritabanında, görev kodu dosyada

scheduled_tasks.task_class   →  App\Tasks\PruneLogsTask
scheduled_tasks.payload      →  {"days":90}

Ne zaman çalışacağı ve hangi parametreyle çalışacağı veritabanındadır — bunlar sık değişir ve panelden yönetilmelidir. Ne yapacağı ise koddadır; sürüm kontrolünde durur, kod incelemesinden geçer.

Worker sınıfı yüklerken Task sınıfından türediğini doğrular; task_class alanına elle bir değer yazılsa bile rastgele bir sınıf çalıştırılamaz.

4. Başarısız görev durdurulmaz

Bir görev hata verdiğinde fail_count artar, last_status failed olur ve çalışma geçmişine hata mesajıyla bir satır düşer. Ama görev pasife alınmaz.

Sebep: geçici bir hata (disk doldu, veritabanı bir saniye yanıt vermedi) yüzünden görevi kalıcı olarak durdurmak, bir sonraki gerçek çalışmayı da engellerdi. Bir kez patlayan görev, bir daha hiç çalışmayan görevden iyidir. Sayaçlar zaten sorunu görünür kılar.

5. Her çalışma kaydedilir — süresi ve çıktısıyla

task_runs tablosu her çalışma için bir satır tutar: durum, milisaniye cinsinden süre ve çıktı.

Süre en çok işe yarayan alandır: normalde 40 ms süren sağlık kontrolü bir gün 5 saniye sürüyorsa, henüz hata vermeden önce bir şeyin bozulduğunu anlarsınız.

6. "Şimdi çalıştır" düğmesi zamanı yok sayar, kilidi yok saymaz

Panelden elle tetiklenen görev, isDue() kontrolünden geçmez — zaten amaç zamanına bakmadan çalıştırmaktır. Ama kilidi alır: cron o sırada aynı görevi çalıştırıyorsa düğme onu ikinci kez başlatmaz.

---

Neler Var?

Zamanlayıcı çekirdeği

• CronExpression — ayrıştırma, doğrulama, sonraki çalışma, açıklama
• *, */n, a-b, a,b,c, a-b/n desteği
• Atomik kilit + görev başına zaman aşımı
• Çalışma geçmişi: durum, süre (ms), çıktı
• Çalışma ve hata sayaçları
• Görev başına etkin/pasif anahtarı

CLI

• --list görevler ve sıradaki zamanlar
• --run=<id> tek görevi şimdi çalıştır
• --quiet sessiz mod (cron için)
• PHP_SAPI kontrolü — tarayıcıdan çalışmaz

Panel

• Görev listesi, satır içinde ifade düzenleme
• "Sıradaki" sütunu — hesaplanmış gerçek tarih
• İnsan dilinde açıklama (Her 15 dakikada bir)
• Şimdi çalıştır / Durdur / Başlat
• Çalışma geçmişi, başarılı ve hatalı ayrımı
• Cron sözdizimi başvuru kartı

Ortak altyapı

• Oturum girişi, "beni hatırla", hız sınırı, CSRF
• CSP (script-src 'self'), X-Frame-Options: DENY
• Açık / koyu tema, hesaba kayıtlı
• Mobilde alt navigasyon, yatay kaydırma yok

---

Cron sözdizimi

┌───────────── dakika        (0-59)
│ ┌─────────── saat          (0-23)
│ │ ┌───────── ayın günü     (1-31)
│ │ │ ┌─────── ay            (1-12)
│ │ │ │ ┌───── haftanın günü (0-6, 0 = Pazar)
│ │ │ │ │
* * * * *

Dört operatör desteklenir:

---

Kendi görevinizi yazmak

Bir görev, Task sınıfından türeyen ve üç metot uygulayan bir sınıftır.

<?php
namespace App\Tasks;

use PDO;

final class ExpireCouponsTask extends Task
{
    public static function label(): string
    {
        return 'Süresi dolan kuponlar';
    }

    public static function description(): string
    {
        return 'Geçerlilik süresi dolmuş kuponları pasife alır.';
    }

    /**
     * Görevin kendisi.
     *
     * EKRANA YAZDIĞINIZ HER ŞEY geçmişe kaydedilir. Scheduler,
     * handle() çağrısını ob_start() / ob_get_clean() arasına alır ve
     * yakaladığı metni task_runs.output sütununa yazar. Yani ayrı bir
     * "günlüğe yaz" API'si öğrenmenize gerek yok: echo yeter.
     *
     * Ne olduğunu SÖYLEYEN bir cümle yazın. "Tamamlandı" yerine
     * "14 kupon pasife alındı" yazmak, altı ay sonra size çok şey anlatır.
     *
     * İstisna fırlatırsa çalışma BAŞARISIZ sayılır: hata mesajı çıktının
     * sonuna "HATA: ..." olarak eklenir ve fail_count artar.
     */
    public function handle(array $payload, PDO $db): void
    {
        $gun = (int) ($payload['days'] ?? 0);

        $stmt = $db->prepare(
            'UPDATE kuponlar SET aktif = 0
              WHERE aktif = 1 AND bitis_tarihi < (NOW() - INTERVAL :gun DAY)'
        );
        $stmt->execute([':gun' => $gun]);

        printf('%d kupon pasife alındı.' . PHP_EOL, $stmt->rowCount());
    }
}

Sonra panelden ya da doğrudan veritabanından kaydını ekleyin:

INSERT INTO scheduled_tasks
    (name, description, task_class, payload, expression, is_active, lock_timeout, created_at)
VALUES
    ('Süresi dolan kuponlar',
     'Geçerlilik süresi dolmuş kuponları pasife alır.',
     'App\\Tasks\\ExpireCouponsTask',
     '{"days":0}',
     '0 4 * * *',
     1, 300, NOW());

Üç kural:

1. Görev kısa sürsün. Uzun süren işi burada değil, iş kuyruğunda çalıştırın; zamanlanmış görev yalnızca kuyruğa iş bıraksın. Cron zamanı belirler, kuyruk dayanıklılığı sağlar.
2. lock_timeout'u işin süresinden büyük seçin. Aksi hâlde hâlâ çalışan bir görev "takılmış" sayılıp ikinci kez başlatılır.
3. Çıktıyı anlamlı yazın. echo/printf ile yazdığınız her şey geçmişe düşer. Altı ay sonra geçmişe baktığınızda "Tamamlandı" hiçbir şey anlatmaz; "2.318 kayıt silindi" anlatır.

---

Güvenlik: Neyi, Nasıl Kapattık?

---

Yapılandırma

APP_DEBUG=true          # silerseniz: yerelde açık, canlıda kapalı
APP_URL=
APP_PRETTY_URLS=true

DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=cy_scheduler
DB_USER=root
DB_PASS=
••••••••

> **Zaman dilimi önemlidir.** `config/config.php` içindeki `app.timezone` (`Europe/Istanbul`) ile MySQL sunucusunun zaman dilimi aynı olmalıdır. Farklıysa "gece 03:00" dediğiniz görev başka bir saatte çalışır. Kontrol için: `SELECT NOW();` çıktısı ile `date('Y-m-d H:i:s')` çıktısını karşılaştırın.

---

## Dosya Yapısı

scheduler-system/
│
├── index.php Ön denetleyici — TEK giriş noktası
├── database.sql Şema + 5 görev + 21 çalışma kaydı
├── .env.example
│
├── bin/
│ ├── scheduler.php ★ Cron'un çağırdığı tek dosya
│ └── .htaccess Web erişimine kapalı
│
├── app/
│ ├── Core/
│ │ ├── CronExpression.php ★ Ayrıştırma · isDue · nextRun · describe
│ │ ├── Scheduler.php ★ Kilit alma, çalıştırma, geçmişe yazma
│ │ ├── Auth.php · Session.php · Csrf.php · RateLimiter.php
│ │ ├── Database.php PDO (EMULATE_PREPARES = false)
│ │ ├── Env.php .env okuyucu + isLocalHost()
│ │ └── ...
│ │
│ ├── Tasks/
│ │ ├── Task.php ★ Soyut taban: handle() · label() · description()
│ │ ├── PruneLogsTask.php Örnek: eski günlük kayıtlarını sil
│ │ ├── HealthCheckTask.php Örnek: veritabanı/disk/izin denetimi
│ │ └── BackupTask.php Örnek: CSV yedeği al, en yeni 5'i sakla
│ │
│ ├── Http/Controllers/ Auth · Dashboard · Schedule · User
│ ├── Repositories/ ScheduleRepository · UserRepository · ActivityRepository
│ └── Support/helpers.php
│
├── storage/ Yedek ve rapor çıktıları (web'e kapalı)
├── views/ Düzenler, görev ve geçmiş sayfaları
├── assets/ css · js · images
├── config/config.php
├── routes/web.php
└── docs/screenshots/

---

## Nasıl Çalışıyor?

crontab: * php bin/scheduler.php
│
▼ (her dakika)
Scheduler::runDue()
│
▼
SELECT * FROM scheduled_tasks WHERE is_active = 1
│
▼ her görev için
┌───────────────────────────────────┐
│ CronExpression($task['expression'])│
│ ->isDue(now) │
└───────────────────────────────────┘
│ │
hayır │ │ evet
▼ ▼
ATLA ┌──────────────────────────────────┐
│ ATOMİK KİLİT │
│ UPDATE scheduled_tasks │
│ SET locked_at = NOW() │
│ WHERE id = ? │
│ AND (locked_at IS NULL │
│ OR locked_at < NOW() │
│ - INTERVAL timeout SEC) │
└──────────────────────────────────┘
│
rowCount() === 0 ?
│ │
evet │ │ hayır (kilit bizde)
▼ ▼
ATLA (başkası Task::handle($payload, $db)
çalıştırıyor) │
├─ başarılı → last_status='success'
│ run_count++
│
└─ istisna → last_status='failed'
fail_count++
│
▼
task_runs tablosuna satır
(durum · süre(ms) · çıktı)
│
▼
locked_at = NULL ◄── kilit bırakılır
```

---

Veritabanı Şeması

scheduled_tasks — görev tanımları

task_runs — çalışma geçmişi

---

SSS

Sunucumda cron yok, ne yapabilirim?

Üç seçenek:

1. cPanel / Plesk: panelde "Cron Jobs" bölümü vardır; komutu oraya yazın.
2. Windows: Görev Zamanlayıcı'dan her dakika tekrarlanan bir görev tanımlayın.
3. Harici tetikleyici: bin/scheduler.php yerine korumalı bir web adresi açıp cron-job.org gibi bir servisle her dakika çağırın. Bu durumda adrese mutlaka bir gizli anahtar koyun; herkese açık bir adres, görevlerinizi isteyen herkesin tetikleyebilmesi demektir.

Görev her dakika çalışıyor, oysa 0 3 * * * yazdım

Neredeyse her zaman zaman dilimi farkıdır. PHP Europe/Istanbul, MySQL UTC ise NOW() üç saat geride olur ve hesaplar tutmaz.

SELECT NOW(); çıktısı ile php -r "echo date('Y-m-d H:i:s');" çıktısını karşılaştırın. Farklıysa MySQL'in time_zone ayarını düzeltin veya config/config.php içindeki app.timezone değerini sunucuya uydurun.

Görev iki kez çalıştı, kilit çalışmıyor mu?

Kilit çalışıyordur; muhtemelen lock_timeout görevin süresinden kısadır.

Görev 400 saniye sürüyor ama lock_timeout 300 ise, 300. saniyede kilit "eski" sayılır ve ikinci çalışma başlar. Süreyi çalışma geçmişindeki duration_ms değerine bakarak ayarlayın; en uzun çalışmanın en az iki katı iyi bir başlangıçtır.

Uzun süren bir işi buradan çalıştırabilir miyim?

Çalıştırabilirsiniz ama önerilmez. Zamanlanmış görev zamanı belirler; dayanıklılık (yeniden deneme, geri çekilme, başarısız iş kutusu) sağlamaz. Cron'un içinde patlayan iş kaybolur.

Doğru kalıp: zamanlanmış görev kuyruğa bir iş bırakır, işi worker çalıştırır. Kuyruk örneği için İş Kuyruğu ve Worker Sistemi'ne bakın.

Çalışma geçmişi çok büyüdü

Beklenen bir durumdur: 15 dakikada bir çalışan bir görev yılda ~35.000 satır üretir.

Projedeki PruneLogsTask tam da bunun içindir; task_runs için de benzer bir temizlik görevi ekleyin ve gece çalıştırın. ran_at sütunu indekslidir, silme sorgusu hızlı çalışır.

Saniyede bir çalışan görev tanımlayabilir miyim?

Hayır — cron'un en küçük birimi dakikadır ve bu zamanlayıcı da dakika çözünürlüğünde çalışır.

Daha sık çalışması gereken bir iş varsa o bir "zamanlanmış görev" değil, sürekli çalışan bir süreçtir. Kuyruk worker'ı bu iş için doğru araçtır.

---

Canlı Ortama Alırken

• [ ] .env içinde APP_DEBUG=false (veya satırı tümüyle silin)
• [ ] Tek cron satırını kurun ve --quiet ekleyin
• [ ] PHP ile MySQL'in zaman dilimi aynı mı, doğrulayın
• [ ] Her görevin lock_timeout değerini en uzun çalışmasının üstünde seçin
• [ ] bin/ ve storage/ klasörlerinin web'den erişilemediğini doğrulayın (403)
• [ ] task_runs için bir temizlik görevi ekleyin
• [ ] Veritabanı için root olmayan bir kullanıcı açın
• [ ] HTTPS zorunlu olsun
• [ ] Demo hesaplarının parolalarını değiştirin veya hesapları silin

---

Sorun Giderme

---

Yol Haritası

• [ ] Görev başarısız olunca e-posta / webhook bildirimi
• [ ] Panelden yeni görev ekleme formu (şu an SQL ile ekleniyor)
• [ ] Çalışma süresi grafiği (son 24 saat)
• [ ] @daily, @hourly gibi kısayol ifadeleri
• [ ] Görev bağımlılığı (A bitmeden B çalışmasın)

---

Katkı

Hata bildirimi ve öneriler için issue açabilirsiniz.

Lisans

MIT — ticari projelerinizde de özgürce kullanabilirsiniz.

---