|
**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=` 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)
│ │ │ │ │
* * * * *
```
| İfade | Anlamı |
|---|---|
| `* * * * *` | Her dakika |
| `*/15 * * * *` | Her 15 dakikada bir |
| `0 * * * *` | Her saat başı |
| `0 3 * * *` | Her gün saat 03:00 |
| `30 2 * * 0` | Her Pazar 02:30 |
| `0 9 * * 1` | Her Pazartesi 09:00 |
| `0 0 1 * *` | Her ayın 1'i gece yarısı |
| `30 9-17/2 * * 1-5` | Hafta içi 09:30, 11:30, 13:30, 15:30, 17:30 |
Dört operatör desteklenir:
| Operatör | Örnek | Anlamı |
|---|---|---|
| `*` | `*` | Her değer |
| `,` | `1,15` | Listedeki değerler |
| `-` | `9-17` | Aralık |
| `/` | `*/15`, `9-17/2` | Adım (aralıkla birlikte de kullanılabilir) |
---
### Kendi görevinizi yazmak
Bir görev, `Task` sınıfından türeyen ve üç metot uygulayan bir sınıftır.
```php
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:
```sql
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](https://cilginyazilim.com/kutuphane/php-queue-worker) ç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?
| Açık | Tipik hatalı kod | Bu projede |
|---|---|---|
| **Rastgele sınıf çalıştırma** | `(new $row['class'])->run()` | Sınıf `Task`'tan türemiyorsa **çalıştırılmaz** |
| **Yarış koşulu (üst üste binme)** | "Önce bak, sonra kilitle" | Kontrol ve yazma **tek `UPDATE` ifadesinde**; `rowCount()` ile doğrulanır |
| **Sonsuza kadar kilitli görev** | Zaman aşımsız kilit | Kilit `lock_timeout` saniyeden eskiyse **geçersiz** sayılır |
| **Geçersiz cron ifadesi** | Doğrulamadan kaydetmek | `CronExpression::isValid()` — geçersiz ifade veritabanına yazılmaz |
| **SQL enjeksiyonu** | `"... WHERE id = $id"` | Tüm sorgular hazır ifade; `ATTR_EMULATE_PREPARES = false` |
| **CLI betiğine web'den erişim** | `bin/` klasörü açık | `bin/.htaccess` ile kapalı **ve** betikte `PHP_SAPI === 'cli'` kontrolü |
| **CSRF** | Gizli alan yok | Her POST'ta jeton; `hash_equals()` |
| **XSS** | `echo $run['output']` | Sunucuda `e()`; ayrıca CSP `script-src 'self'` |
| **Parola sızıntısı** | `md5($parola)` | `password_hash()` / `password_verify()` |
| **Kaba kuvvet** | Sınırsız deneme | `login_attempts` ile e-posta + IP başına hız sınırı |
| **Hata sızıntısı** | Canlıda `display_errors=On` | `APP_DEBUG` **ortamdan türetilir** |
| **Sınırsız büyüyen geçmiş** | Temizlenmeyen log tablosu | `task_runs` için indeksli tarih sütunu; örnek temizlik görevi projede hazır |
---
### Kurulum
#### Gereksinimler
| | |
|---|---|
| PHP | 8.0 veya üzeri (CLI erişimi gerekir) |
| MySQL / MariaDB | 5.7+ / 10.3+ |
| Web sunucusu | Apache (`mod_rewrite`) veya Nginx |
| PHP eklentileri | `pdo_mysql`, `mbstring` |
#### Adımlar
```bash
git clone https://github.com/CilginYazilim/scheduler-system.git
cd scheduler-system
mysql -u root -p < database.sql
cp .env.example .env # Windows: copy .env.example .env
```
Açın: `http://localhost/scheduler-system/` · Giriş: `admin@cilginyazilim.com` / `Admin1234`
Sonra tek cron satırını kurun → [Tek cron satırı](#tek-cron-satırı)
---
### Yapılandırma
```env
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ı
| Sütun | Tip | İşi |
|---|---|---|
| `id` | INT UNSIGNED | Birincil anahtar |
| `name` · `description` | VARCHAR | Panelde görünen ad ve açıklama |
| `task_class` | VARCHAR(190) | Çalıştırılacak sınıf (`App\Tasks\PruneLogsTask`) |
| `payload` | TEXT | Görevin parametreleri (JSON) |
| `expression` | VARCHAR(100) | Cron ifadesi (`0 3 * * *`) |
| `is_active` | TINYINT(1) | Pasifse zamanı gelse bile çalışmaz |
| `locked_at` | DATETIME | Çalışıyorsa dolu; `NULL` = boşta |
| `lock_timeout` | INT UNSIGNED | Kilit kaç saniye sonra geçersiz sayılsın |
| `last_run_at` · `last_status` | DATETIME · ENUM | Son çalışma anı ve sonucu |
| `run_count` · `fail_count` | INT UNSIGNED | Toplam çalışma ve hata sayısı |
### `task_runs` — çalışma geçmişi
| Sütun | Tip | İşi |
|---|---|---|
| `id` | BIGINT UNSIGNED | Birincil anahtar |
| `task_id` | INT UNSIGNED | Hangi göreve ait (`ON DELETE CASCADE`) |
| `status` | ENUM('success','failed') | Sonuç |
| `duration_ms` | INT UNSIGNED | Süre — **erken uyarı sinyali** |
| `output` | TEXT | Görevin ekrana yazdığı metin (çıktı tamponundan yakalanır) ve varsa hata mesajı |
| `ran_at` | DATETIME | Çalışma anı (indeksli) |
| Karar | Neden |
|---|---|
| Geçmiş **ayrı tabloda** | `scheduled_tasks` her dakika okunur; geçmiş satırlarıyla şişmemeli |
| Süre **milisaniye** olarak | 40 ms → 5.000 ms değişimi, hata oluşmadan önce bozulmayı gösterir |
| `locked_at` görev satırında, ayrı tabloda değil | Kilidi almak ve görevi güncellemek **tek `UPDATE`** olsun diye; ayrı tablo ikinci bir yarış koşulu açardı |
| `last_status` özet olarak tutuluyor | Liste sayfası her satır için geçmiş tablosuna sorgu atmasın (N+1) |
| Sayaçlar (`run_count`) satırda | Aynı sebep: `COUNT(*)` yerine hazır sayı |
---
## SSS
## Zamanlanmış Görevler (Scheduler)
#### PHP 8 · PDO · MySQL · Oturum Girişli Panel · Cron Ayrıştırıcı · Kilit · Çalışma Geçmişi · Çılgın Yazılım Tasarım Kalıbı
**Sunucuya tek bir cron satırı yazın; görevleri panelden yönetin.**
[](https://php.net)
[](https://mysql.com)
[](https://getbootstrap.com)
[](#kurulum)
[](LICENSE)
**🇹🇷 Türkçe** · [🇬🇧 English](README.en.md)
[**▶ Canlı Demo**](https://cilginyazilim.com/kutuphane/uygulama/scheduler-system/) · [Kaynak Kütüphanesi](https://cilginyazilim.com/kutuphane/php-scheduler-cron) · [cilginyazilim.com](https://cilginyazilim.com)
---
### Canlı Demo
**Kurulum yok, kayıt yok, indirme yok — tarayıcınızdan 3 saniyede deneyin.**
▲ Görsele tıklayarak demoyu açabilirsiniz
---
### Tek cron satırı
Sunucuya yazılacak **tek** satır budur:
```cron
* * * * * 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:
| Alan | Değer |
|---|---|
| Program | `C:\xampp\php\php.exe` |
| Bağımsız değişken | `C:\xampp\htdocs\scheduler-system\bin\scheduler.php` |
| Tekrarlama | Her 1 dakikada bir |
**Elle denemek için:**
```bash
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:
```php
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:
```sql
UPDATE scheduled_tasks
SET locked_at = NOW()
WHERE id = :id
AND (locked_at IS NULL OR locked_at < (NOW() - INTERVAL :timeout SECOND))
```
```php
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:
| Metot | Cevabı |
|---|---|
| `isValid()` | Bu ifade geçerli mi? (kullanıcı girdisini süzmek için) |
| `isDue()` | Şu an çalışmalı mı? |
| `nextRun()` | Bir sonraki çalışma ne zaman? |
| `describe()` | İnsan diliyle ne demek? |
`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?