|
**Kuyruk çekirdeği**
- `push()` — iş bırak, gecikme verilebilir
- `reserve()` — yarışsız kapma (koşullu `UPDATE`)
- `release()` — üstel geri çekilmeyle iade
- `fail()` — ölü mektup kutusuna taşı
- `recoverStuck()` — çökmüş worker'ın kilidini aç
- Adlandırılmış kuyruklar (`default`, `reports`, …)
- İş başına ayarlanabilir deneme hakkı
**Worker (CLI)**
- `--queue=` belirli kuyruğu dinle
- `--max=N` N iş sonra dur
- `--once` tek iş çalıştır ve çık
- `--sleep=N` boşta bekleme süresi
- `PHP_SAPI` kontrolü — tarayıcıdan çalışmaz
|
**Panel**
- Dört canlı sayaç (bekleyen/çalışan/ertelenmiş/başarısız)
- Kuyruk listesi, dört durumlu rozet
- Başarısız işler sayfası, yeniden dene / unut
- Takılanları kurtar düğmesi
- Panelden iş bırakma (üç örnek iş türü)
- Worker çalışmıyorsa uyarı şeridi
**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
- Kullanıcılar sayfasında canlı filtre (JS kapalıysa da çalışır)
- Sıfır bağımlılık
|
---
### Worker'ı çalıştırmak
İşler ancak bir worker çalışıyorken işlenir. Proje klasöründe **ayrı bir terminal** açın:
```bash
php bin/worker.php
```
Süreç kuyruğu dinlemeye başlar ve iş geldikçe çalıştırır. Durdurmak için `Ctrl+C`.
#### Seçenekler
| Seçenek | Anlamı |
|---|---|
| `--queue=reports` | Yalnızca bu kuyruğu dinle (varsayılan: `default`) |
| `--max=5` | 5 iş çalıştırdıktan sonra çık — denemek için ideal |
| `--once` | Tek iş çalıştır ve çık (cron'dan tetiklemek için) |
| `--sleep=3` | Kuyruk boşken kaç saniye beklesin (varsayılan: 1) |
| `--help` | Seçenekleri yazdır |
#### Canlı sunucuda
Worker bir gün mutlaka ölür: bellek dolar, deploy sırasında kapatılır, sunucu yeniden başlar. Bu yüzden onu **kendiliğinden yeniden başlatan** bir yönetici altında çalıştırın.
**systemd** (`/etc/systemd/system/cy-worker.service`):
```ini
[Unit]
Description=CY Queue Worker
After=network.target mysql.service
[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/uygulama
ExecStart=/usr/bin/php bin/worker.php
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
```
```bash
sudo systemctl enable --now cy-worker
```
**supervisor** veya cPanel kullanıyorsanız: her dakika çalışan bir cron kurun ve `--once` verin.
```
* * * * * cd /var/www/uygulama && php bin/worker.php --once >> /dev/null 2>&1
```
> **Deploy sırasında:** worker'ı önce durdurun, kodu güncelleyin, sonra başlatın. Aksi hâlde çalışan süreç eski kodu, yeni gelen işler yeni şemayı kullanır.
---
### Kendi işinizi yazmak
Bir iş, `Job` sınıfından türeyen ve iki metot uygulayan bir sınıftır.
```php
push(SendSmsJob::class, ['numara' => '5xx…']);
// 10 dakika sonra çalışsın:
(new Queue($pdo))->push(SendSmsJob::class, ['numara' => '5xx…'], Queue::DEFAULT, 600);
// Ayrı bir kuyruğa:
(new Queue($pdo))->push(SendSmsJob::class, [...], 'sms');
```
**İki kural:**
1. **`handle()` yeniden çalıştırılabilir olsun.** İş, ağ koptuğu için tam bittiği anda da başarısız sayılabilir ve tekrar denenir. "Bu işi ikinci kez çalıştırırsam ne olur?" sorusunun cevabı zararsız olmalıdır — sipariş iki kez oluşturulmamalıdır.
2. **Payload'a nesne değil, kimlik koyun.** `['user_id' => 42]` yazın, kullanıcı nesnesinin tamamını değil. İş çalıştığında veri değişmiş olabilir; taze hâlini `handle()` içinde okuyun.
---
### Güvenlik: Neyi, Nasıl Kapattık?
| Açık | Tipik hatalı kod | Bu projede |
|---|---|---|
| **Rastgele sınıf çalıştırma** | `(new $payload['class'])->run()` | Sınıf `Job`'dan türemiyorsa **çalıştırılmaz** (`is_subclass_of`) |
| **Yarış koşulu (çift işleme)** | "Önce SELECT, sonra UPDATE" | Kontrol ve yazma **tek `UPDATE` ifadesinde**; `rowCount()` ile doğrulanır |
| **Yığın izi sızıntısı** | Hata nesnesinin tamamını loglamak | Yalnızca **mesaj** saklanır; dosya yolu ve sınıf yapısı 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; karşılaştırma `hash_equals()` ile |
| **XSS** | `echo $row['payload']` | Sunucuda `e()`; ayrıca CSP `script-src 'self'` |
| **Parola sızıntısı** | `md5($parola)` | `password_hash()` / `password_verify()`; otomatik yeniden özetleme |
| **Kaba kuvvet** | Sınırsız deneme | `login_attempts` tablosuyla 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**; gerçek alan adında kendiliğinden kapanır |
| **Sonsuz büyüyen kuyruk** | Tavansız geri çekilme | Geri çekilme **1 saatte tavanlanır**; deneme hakkı dolan iş ölü mektup kutusuna taşınır |
| **Bozuk UTF-8'de sessiz JSON kaybı** | `json_encode($v)` | `JSON_INVALID_UTF8_SUBSTITUTE` |
---
### 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
**1 · Dosyaları yerleştirin**
```bash
git clone https://github.com/CilginYazilim/queue-worker-system.git
cd queue-worker-system
```
**2 · Veritabanını içe aktarın**
```bash
mysql -u root -p < database.sql
```
Dosya veritabanını **kendisi oluşturur** (`cy_queue_worker`), tabloları kurar ve örnek kuyruk verisini yükler.
**3 · `.env` dosyasını oluşturun**
```bash
cp .env.example .env # Windows: copy .env.example .env
```
**4 · Açın ve worker'ı başlatın**
```
http://localhost/queue-worker-system/
```
Ayrı bir terminalde:
```bash
php bin/worker.php --max=5
```
Giriş: `admin@cilginyazilim.com` / `Admin1234`
---
### Yapılandırma
```env
APP_DEBUG=true # silerseniz: yerelde açık, canlıda kapalı
APP_URL=
APP_PRETTY_URLS=true # false → /index.php?r=queue
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=cy_queue_worker
DB_USER=root
DB_PASS=
••••••••
Kuyruk davranışını belirleyen sabitler koddadır:
| Sabit | Yeri | Varsayılan | Ne yapar |
|---|---|---|---|
| `Queue::DEFAULT` | `app/Core/Queue.php` | `'default'` | Kuyruk adı verilmezse kullanılan |
| `Queue::STUCK_AFTER` | `app/Core/Queue.php` | `300` | Kaç saniye sonra iş "takılmış" sayılır |
| `Job::maxAttempts()` | `app/Jobs/Job.php` | `3` | Deneme hakkı (iş sınıfında değiştirilebilir) |
| geri çekilme | `Queue::release()` | `10 · 2ⁿ`, tavan `3600` | Yeniden deneme aralığı |
> **`STUCK_AFTER`'ı işlerinize göre ayarlayın.** İşleriniz dakikalarca sürüyorsa 300 saniye çok kısadır: hâlâ çalışan bir iş "takılmış" sayılıp ikinci kez kuyruğa girebilir.
---
## Dosya Yapısı
```
queue-worker-system/
│
├── index.php Ön denetleyici — TEK giriş noktası
├── database.sql Şema + örnek kuyruk verisi
├── .env.example
│
├── bin/
│ ├── worker.php
Kuyruk işçisi (CLI)
│ └── .htaccess Web erişimine kapalı
│
├── app/
│ ├── Core/
│ │ ├── Queue.php
push · reserve · release · fail · recoverStuck
│ │ ├── Worker.php
Döngü, sinyal yakalama, sınıf doğrulama
│ │ ├── Auth.php Giriş, "beni hatırla"
│ │ ├── Session.php Sertleştirilmiş oturum
│ │ ├── Csrf.php Jeton + hash_equals
│ │ ├── RateLimiter.php Giriş denemesi sınırı
│ │ ├── Database.php PDO (EMULATE_PREPARES = false)
│ │ ├── Env.php .env okuyucu + isLocalHost()
│ │ └── ...
│ │
│ ├── Jobs/
│ │ ├── Job.php
Soyut taban: handle() · label() · maxAttempts()
│ │ ├── SendEmailJob.php Örnek: e-posta gönderimi
│ │ ├── ReportJob.php Örnek: rapor üretimi (dosyaya yazar)
│ │ └── FlakyJob.php Örnek: %70 hata veren "kararsız" iş
│ │
│ ├── Http/Controllers/ Auth · Dashboard · Queue · User
│ ├── Repositories/ JobRepository · UserRepository · ActivityRepository
│ └── Support/helpers.php
│
├── storage/ Worker çıktıları (web'e kapalı)
├── views/ Düzenler, kuyruk ve başarısız iş sayfaları
├── assets/ css · js · images
├── config/config.php
├── routes/web.php
└── docs/screenshots/
```
---
## Nasıl Çalışıyor?
```
WEB İSTEĞİ AYRI SÜREÇ (worker)
────────── ───────────────────
Kullanıcı "Kaydet"e basar php bin/worker.php
│ │
▼ ▼
Queue::push(SendEmailJob::class, [...]) ┌─► reserve('default', $workerId)
│ │ │
│ INSERT INTO jobs (...) │ │ 1) 5 aday satır SELECT
│ available_at = NOW() + gecikme │ │ WHERE reserved_at IS NULL
│ │ │ AND available_at <= NOW()
▼ │ │
Yanıt DÖNER (milisaniyeler) │ │ 2) her aday için koşullu UPDATE
Kullanıcı beklemez │ │ SET reserved_at = NOW()
│ │ WHERE id=? AND reserved_at IS NULL
│ │
│ │ rowCount() === 1 ?
│ │ hayır → sıradaki adaya geç
│ │ evet → iş benim
│ ▼
│ Job::handle($payload, $db)
│ │
│ ├─ başarılı → Queue::delete()
│ │
│ └─ istisna → deneme < max ?
│ │ │
│ evet │ │ hayır
│ ▼ ▼
│ Queue::release() Queue::fail()
│ available_at = failed_jobs'a
│ NOW() + 10·2ⁿ TAŞINIR
│ │
└─────────────┘
(kuyruğa geri döner)
```
---
## Veritabanı Şeması
### `jobs` — bekleyen ve çalışan işler
| Sütun | Tip | İşi |
|---|---|---|
| `id` | BIGINT UNSIGNED | Birincil anahtar |
| `queue` | VARCHAR(60) | Kuyruk adı; farklı önceliklere ayrı worker atanabilir |
| `job_class` | VARCHAR(190) | Çalıştırılacak sınıf (`App\Jobs\SendEmailJob`) |
| `payload` | TEXT | İşin verisi (JSON) |
| `attempts` / `max_attempts` | SMALLINT | Kaç kez denendi / en fazla kaç kez |
| `available_at` | DATETIME | "Bu zamandan önce çalıştırma" — gecikme **ve** geri çekilme |
| `reserved_at` / `reserved_by` | DATETIME / VARCHAR | Kapan worker ve kapma anı; `NULL` = boşta |
| `last_error` | VARCHAR(1000) | Son hata; iş hâlâ kuyrukta ama sorunlu |
| `created_at` | DATETIME | Bırakılma anı |
**Tek indeks, en sıcak sorgu için:**
```sql
KEY idx_jobs_reserve (queue, reserved_at, available_at)
```
Worker saniyede birkaç kez şunu sorar:
```sql
WHERE queue = ? AND reserved_at IS NULL AND available_at <= NOW() ORDER BY id
```
Bu indeks olmadan her sorgu **tüm tabloyu tarar**; kuyruk büyüdükçe sistem yavaşlar. Sütun sırası rastgele değildir: önce eşitlik (`queue`), sonra `NULL` kontrolü, en sonda aralık karşılaştırması.
### `failed_jobs` — ölü mektup kutusu
| Sütun | Tip | İşi |
|---|---|---|
| `id` | BIGINT UNSIGNED | Birincil anahtar |
| `queue` · `job_class` · `payload` | — | `jobs`'tan taşınan alanlar |
| `attempts` | SMALLINT | Kaç kez denendi |
| `error` | VARCHAR(2000) | **Yalnızca mesaj** — yığın izi saklanmaz |
| `failed_at` | DATETIME | Pes edilen an |
| Karar | Neden |
|---|---|
| Ayrı tablo | `jobs`, worker'ın en sıcak sorgusudur; ölü satırlarla şişmemeli |
| Yığın izi yok | Dosya yolu ve sınıf yapısı veritabanına yazılmamalı |
| `payload` korunur | "Yeniden dene" işi aynı veriyle geri gönderebilsin diye |
---
## SSS
## İş Kuyruğu ve Worker Sistemi
#### PHP 8 · PDO · MySQL · Oturum Girişli Panel · Yeniden Deneme · Ölü Mektup Kutusu · Çılgın Yazılım Tasarım Kalıbı
**Kullanıcıyı bekletmeyin: işi kuyruğa bırakın, arka planda bir worker çalıştırsın.**
[](https://php.net)
[](https://mysql.com)
[](https://getbootstrap.com)
[](#neden-redis-yok)
[](LICENSE)
**🇹🇷 Türkçe** · [🇬🇧 English](README.en.md)
[**▶ Canlı Demo**](https://cilginyazilim.com/kutuphane/uygulama/queue-worker-system/) · [Kaynak Kütüphanesi](https://cilginyazilim.com/kutuphane/php-queue-worker) · [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
---
### Bir işin hayatı
```
push() reserve() handle()
│ │ │
▼ ▼ ▼
┌────────┐ zamanı geldi ┌──────────┐ başarılı ┌─────────┐
│BEKLİYOR│ ──────────────► │ ÇALIŞIYOR│ ───────────► │ SİLİN │
└────────┘ └──────────┘ └─────────┘
▲ │
│ │ hata
│ ▼
│ deneme < max ?
│ │ │
│ 10 sn → 20 sn → 40sn │ evet │ hayır
└───────────────────────┘ ▼
(üstel geri çekilme) ┌──────────────┐
│ BAŞARISIZ │ ölü mektup kutusu
│ failed_jobs │ → "Yeniden dene" ile geri döner
└──────────────┘
Worker çöktüyse: ÇALIŞIYOR durumunda 5 dakikadan uzun kalan iş
TAKILMIŞ sayılır → recoverStuck() onu BEKLİYOR'a döndürür
```
Dört durum, iki sütundan okunur:
| Durum | Nasıl anlaşılır |
|---|---|
| **Bekliyor** | `reserved_at IS NULL` **ve** `available_at <= NOW()` |
| **Ertelenmiş** | `reserved_at IS NULL` **ve** `available_at > NOW()` |
| **Çalışıyor** | `reserved_at` dolu ve 5 dakikadan yeni |
| **Takılmış** | `reserved_at` dolu ve 5 dakikadan eski |
---
### Kritik Kararlar
#### 1. Aynı işi iki worker alamaz — kilit kullanmadan
En sık yapılan hata şudur:
```php
// YANLIŞ: iki worker aynı satırı görebilir
$job = $db->query('SELECT * FROM jobs WHERE reserved_at IS NULL LIMIT 1')->fetch();
$db->exec("UPDATE jobs SET reserved_at = NOW() WHERE id = {$job['id']}");
```
İki worker `SELECT`'i aynı anda çalıştırırsa ikisi de aynı satırı alır ve e-posta **iki kez** gider. "Önce bak, sonra yaz" her zaman bir yarış koşuludur.
Doğrusu, kontrolü ve yazmayı **tek ifadeye** koymaktır:
```sql
UPDATE jobs
SET reserved_at = NOW(), reserved_by = :worker, attempts = attempts + 1
WHERE id = :id
AND reserved_at IS NULL -- ◄── kritik satır
```
`reserved_at IS NULL` koşulu `UPDATE`'in içindedir; veritabanı satırı yazarken zaten kilitler. İki worker aynı satırı denerse **yalnızca birinin** `rowCount()` değeri 1 olur:
```php
if ($claim->rowCount() === 0) {
continue; // başka bir worker önce davrandı, sıradakine geç
}
```
Uygulama önce 5 aday satır okur, sonra bunları sırayla kapmayı dener. Böylece iki worker çakışsa bile boş dönmez, listedeki bir sonrakine geçer.
#### 2. `SELECT ... FOR UPDATE SKIP LOCKED` neden kullanılmadı?
Kullanılabilirdi ve MySQL 8.0'da daha zarif olurdu. Ama `SKIP LOCKED`, **MySQL 5.7 ve MariaDB 10.5'ten önceki sürümlerde yoktur** — paylaşımlı hosting'lerin büyük kısmı hâlâ orada.
Koşullu `UPDATE` yöntemi her sürümde çalışır, ek bir işlem (transaction) yönetimi gerektirmez ve aynı güvenceyi verir. Taşınabilirlik, buradaki zarafetten daha değerli görüldü.
#### 3. Yeniden deneme **üstel geri çekilmeyle** yapılır
Hata alan işi hemen tekrar denemek, çoğu zaman zarar verir: düşmüş bir SMTP sunucusuna saniyede üç istek göndermek onu daha da boğar.
```php
// app/Core/Queue.php — release()
$delay = min(3600, 10 * (2 ** ($attempts - 1)));
```
Bekleme süresi her denemede ikiye katlanır: **10 sn → 20 sn → 40 sn → …** ve bir saatte tavanlanır. Tavan olmasaydı 20. deneme 60 gün sonraya düşerdi.
#### 4. Deneme hakkı dolan iş silinmez, **taşınır**
Üç kez denenip başaramayan bir işi silmek, veriyi kaybetmektir. Bu iş `failed_jobs` tablosuna taşınır ve orada sizi bekler.
Neden ayrı tablo? Çünkü `jobs` tablosu worker'ın **en sıcak** sorgusudur; saniyede birkaç kez taranır. Başarısız işleri orada tutmak, o tabloyu asla temizlenmeyen ölü satırlarla şişirirdi.
Servisi düzelttiğinizde "Yeniden dene" düğmesi işi geri gönderir — kaybolmuş bir e-posta yerine, gönderilmeyi bekleyen bir e-postanız olur.
#### 5. Hata metni saklanır, **yığın izi saklanmaz**
```php
'error' VARCHAR(2000) NOT NULL DEFAULT ''
```
Yığın izi dosya yollarınızı, klasör yapınızı ve sınıf adlarınızı içerir. Veritabanı bir gün sızarsa saldırgana hazır bir harita vermiş olursunuz. Hata **mesajı** sorunu anlamaya yeter.
#### 6. Takılmış iş ile çalışan iş ayrı gösterilir
Worker çökerse (sunucu yeniden başladı, bellek doldu, deploy sırasında kapatıldı) `reserved_at` dolu kalır ve iş sonsuza kadar "çalışıyor" görünür — oysa onu çalıştıran kimse yoktur.
Bu yüzden 5 dakikadan eski rezervasyonlar arayüzde ayrı bir **Takılmış** rozetiyle gösterilir. Eşik `Queue::STUCK_AFTER` sabitindedir ve **hem rozet hem kurtarma sorgusu** onu kullanır. İkisi ayrışsaydı, ekranda takılmış görünen bir işi kurtarma düğmesi bulamazdı.
#### 7. Payload JSON, iş sınıfı ise tam sınıf adı
```
job_class: App\Jobs\SendEmailJob
payload: {"to":"...","subject":"..."}
```
İşin **ne olduğu** ile **neyle çalışacağı** ayrılır. Worker sınıfı yükler, `Job` sınıfından türediğini doğrular ve `handle($payload, $db)` çağırır:
```php
if (!class_exists($class) || !is_subclass_of($class, Job::class)) {
// tanınmayan sınıf çalıştırılmaz
}
```
Bu kontrol güvenliğin parçasıdır: `job_class` alanına elle bir değer yazılsa bile rastgele bir sınıf örneklenip çalıştırılamaz.
#### 8. Neden Redis yok?
Redis kuyruk için mükemmeldir ama **bir bağımlılıktır**: kurulacak, izlenecek, yedeklenecek ve paylaşımlı hosting'de çoğu zaman bulunmayan bir servistir.
Günde on binlerce işe kadar MySQL fazlasıyla yeter — özellikle `idx_jobs_reserve` bileşik indeksi varken. Üstelik işleriniz veritabanı yedeğinizin içinde durur; ayrıca yedeklemeniz gereken ikinci bir depo olmaz.
Milyonlarca işe çıktığınızda Redis'e geçin. O gün gelene kadar kurmayın.
---
### Neler Var?