PHP Başlangıç Şablonu (CY PHP Starter)

Bu şablon nedir?

CY PHP Starter, Çılgın Yazılım'ın açık kaynaklı **PHP başlangıç
şablonudur** (starter kit, boilerplate). Her yeni PHP projesinde baştan
yazdığınız teknik altyapıyı — kurulum sihirbazı, giriş ve rol-yetki
sistemi, yönetim paneli, migration, kuyruk, REST API, PWA — hazır ve test
edilmiş olarak sunar.

Belirli bir iş uygulaması değildir; ERP, CRM, CMS, blog, SaaS, REST
API ya da şirket içi uygulama — hepsinin altına aynı sağlam temeli koyar.

Composer yok, framework yok, CDN yok. Saf PHP 8.1+ ve PDO/MySQL ile
yazılmıştır; paylaşımlı hostingde bile komut satırı olmadan kurulur.
İndirin, kurulum/ adresini açın, birkaç adımda çalışan bir site ve
yönetim paneli elde edin.

Tek cümlelik felsefe

Core, uygulamanın ne iş yaptığını bilmez. Yalnızca **nasıl
çalıştığını** sağlar.

// YANLIŞ — çekirdek iş mantığını biliyor
UserService::register($data);
ErpPersonel::olustur($user);

// DOĞRU — çekirdek duyurur, modül dinler
Events::dispatch(new UserRegistered($user));

Framework mü, bu şablon mu?

Laravel ya da Symfony gibi tam bir framework çoğu proje için doğru
seçimdir. Bu şablon, şu durumlar için yazıldı:

---

Neler hazır?

---

Demo hesaplar

Örnek veriyle kurulumda (ve canlı demoda)
şu hesaplar gelir. Ortak parola yalnızca demo modunda ya da geliştirme
ortamında giriş ekranında görünür; satıra tıklamak yeterlidir.

Ana sayfadaki "Rolleri deneyin" kartları (/giris?demo=elif.editor)
giriş ekranında o hesabı vurgular; rol adı da olur (/giris?demo=editor,
admin, uye). Parola adreste asla taşınmaz. Gerçek bir
sitede örnek veriyi Panel → Sistem → Örnek veriyi kaldır ile tek
tıkla silin.

Rol ve yetki matrisi

Bu tablo kodda da yazılıdır: tests/rol-matrisi.php
96 rotanın her biri için kimin erişebildiğini tutar; bir rotanın yetkisi
değişirse birim testi kırılır. Duman testi aynı matrisi demo hesaplarla,
demo modu açık ve kapalı olarak gerçek HTTP isteğiyle sınar. Demo
kilidi yetkiden SONRA çalışır: yetkisi olmayan "yetkiniz yok" görür.

---

Klasör yapısı

├── index.php               Web giriş noktası
├── cy                      Konsol giriş noktası (php cy …)
├── sw.js                   Servis çalışanı (PWA)
│
├── app/
│   ├── bootstrap.php       Web + CLI ortak önyükleme
│   ├── Core/               ÇEKİRDEK (iş mantığı içermez)
│   │   ├── Api/ Cache/ Console/ Database/ Events/ Exceptions/
│   │   ├── Log/ Mail/ Modules/ Queue/ Schedule/ Storage/
│   │   └── Auth Config Csrf Database Env ErrorHandler Flash
│   │       Middleware RateLimiter Request Response Router
│   │       Session Setting Uploader Url Validator View
│   ├── Events/ Listeners/ Jobs/
│   ├── Models/             Entity'ler (ORM DEĞİL) + Role
│   ├── Repositories/       SQL yalnızca burada
│   ├── Http/Controllers/   Panel · Api · Site
│   └── Support/            helpers.php · gelistirme-sunucusu.php (php cy serve)
│
├── config/                 app db session log cache queue api storage
│                           upload security validation events
├── routes/                 web.php · events.php · schedule.php
├── database/               migrations/ · seeders/ · ornek-veritabani.sql
├── modules/                Eklenebilir modüller (Ornek/ = çalışan örnek)
├── views/                  layouts · partials · emails · errors · sayfalar
├── assets/                 css · js · images (CDN yok)
├── storage/                logs · cache · files · mail (web'e kapalı)
├── upload/                 Yüklenen görseller (PHP çalıştırma kapalı)
├── docs/                   MOBIL-API.md · ekran görüntüleri (yalnızca GitHub'da; ZIP'te yok)
├── tests/                  unit · smoke · kurulum · sema · rol-matrisi · ornek-sql (web'e kapalı)
└── kurulum/                Sihirbaz + database.sql (sonra SİLİN)

İsteğin yolculuğu

Tarayıcı → .htaccess → index.php → bootstrap → Session/Güvenlik
   → Ayarlar → Modüller → Router → Middleware → Controller
   → Repository → View / JSON

---

Konsol

php cy                      # tüm komutlar
php cy yardim migrate       # ayrıntılı yardım

# Şema
php cy make:migration "urunlere aciklama ekle"
php cy migrate                     php cy migrate --pretend
php cy migrate:status              php cy migrate:rollback --step=3
php cy migrate:fresh --seed

# Üreteçler
php cy make:module Stok            # çalışır durumda CRUD modülü
php cy make:controller Urun --api
php cy make:model Urun --repository
php cy make:seeder Urun

# Modüller
php cy module                      php cy module --enable=Stok

# Örnek veri ve demo
php cy db:seed                     php cy demo:reset    php cy demo:temizle

# XAMPP'siz geliştirme sunucusu → http://127.0.0.1:8000
php cy serve                       php cy serve --port=8080

# Bakım
php cy cache:clear --expired       php cy config:cache
php cy log:purge --list            php cy queue:work --max=30
php cy schedule:run --list         php cy mail:test [email protected]

# API anahtarı (süre verilmezse 90 gün; süresiz için açıkça --suresiz)
php cy api:token admin "Mobil uygulama" --gun=90
php cy api:token admin --liste     php cy api:token admin --iptal=3

Çekirdek migration'lar geri alınamaz. Şablonla gelen her migration
(sihirbazın kurdukları ve güncellemelerle gelenler) "temel parti" (0)
olarak işaretlenir; migrate:rollback ve migrate:fresh yalnızca
SİZİN eklediğiniz ve modüllerden gelen migration'ları etkiler.
php cy migrate:status bunları 0 (kurulum) diye gösterir.
SSH yoksa: bekleyen migration'lar Panel → Sistem Bilgisi
sayfasındaki düğmeyle çalıştırılır; panel her sayfada uyarır.

Cron — tek satır yeter:

* * * * * cd /yol/site && php cy schedule:run >> /dev/null 2>&1

---

REST API

Dış istemciler (mobil uygulama, başka bir sunucu) /api/v1/… uçlarına
Bearer anahtarıyla bağlanır. Anahtar **Panel → Hesabım → API
Anahtarları** ekranından ya da php cy api:token ile üretilir; açık hali
yalnızca bir kez gösterilir, veritabanında yalnızca SHA-256 özeti durur.

curl -H "Authorization: Bearer cy_…" https://siteniz.com/api/v1/ben

Mobil uygulama için oturum

Mobil uygulama anahtarı elle almaz; kullanıcı adı ve parolayla giriş yapar,
dönen token'ı güvenli depoda saklar:

curl -X POST https://siteniz.com/api/v1/oturum \
     -H "Content-Type: application/json" \
     -d '{"kullanici":"mehmet.uye","parola":"…","cihaz":"Pixel 8"}'
# → { "success": true, "data": { "token": "••••••••", "son_gecerlilik": "…", "kullanici": { … } } }

curl -H "Authorization: Bearer cy_…" https://siteniz.com/api/v1/dosyalar
curl -X DELETE -H "Authorization: Bearer cy_…" https://siteniz.com/api/v1/oturum

Giriş, panel girişiyle aynı kaba kuvvet korumasından geçer. Token
30 gün geçerlidir (API_SESSION_DAYS); kullanıcı açık cihazlarını
Panel → Hesabım → Bağlı cihazlar'da görür ve tek tek kapatır.
Akış, hata kodları, JavaScript ve Flutter örnekleri:
Mobil API rehberi.

Anahtarlar

• Anahtarla gelen istekler durumsuzdur: oturum açılmaz, çerez dönmez.

Anahtar iptal edildiği an erişim biter.

• Anahtar, sahibinin yetkilerinden fazlasına erişemez; sahibi pasife

alınırsa anahtarı da çalışmaz.

• Panelden anahtar üretmek mevcut parolayı ister; süre 30/90/180/365

gün, kapsam yalnız okuma (varsayılan) ya da okuma + yazma seçilir.
Yalnız okuma anahtarı GET dışında 403 kapsam_yetersiz alır. Parola değişince kullanıcının **bütün anahtarları iptal
edilir**; "Diğer cihazlardan çıkış" da isteğe bağlı olarak iptal eder.

• Tarihler ISO 8601 biçimindedir (2026-10-06T14:05:00+03:00).
• Bakım modunda API de 503 döner (bakımı aşma yetkisi olanın anahtarı hariç).
• Kendi uçlarınız için örnek: app/Http/Controllers/Api/V1Controller.php

ve routes/web.php içindeki api/v1 grubu.

---

Testler

php tests/unit.php                                   # veritabanı gerektirmez
php tests/smoke.php http://localhost/proje           # kurulu siteye HTTP denetimi
php tests/smoke.php http://localhost/proje --kullanici=admin --parola=…
php tests/kurulum.php http://127.0.0.1:8000 --db-adi=bos_db --ornek-veri --demo   # sihirbazı uçtan uca
php tests/sema.php --eski=eski-database.sql          # yükseltilen şema = yeni kurulum mu?
php tests/ornek-sql.php --db-adi=ornek_db             # örnek veritabanı SQL dosyasını üretir

unit.php 339 testi veritabanı olmadan çalıştırır; aralarında **rol
matrisi** (96 rotanın her biri için kimin erişebildiği), 18 XSS vektörü,
Örnek Modül politikası ve kurulum şeması tutarlılığı vardır. smoke.php
siteyi değiştirmez: kurulum kilidi, gizli dosyalar (.env, .git/), açık
yönlendirme, kaba kuvvet kilidi, kullanıcı tespiti, oturum çerezi, mobil
API akışı ve — örnek veriyle kurulmuş sitede — demo hesaplarla **rol
matrisini** (GET ve CSRF'li POST) dışarıdan sınar. Kısa sürede arka arkaya
çalıştırırsanız IP kilidi devreye girer; ilgili testler "atlandı" görünür
(koruma çalışıyor demektir).

GitHub Actions her itmede iki iş çalıştırır (.github/workflows/ci.yml):
PHP 8.1–8.4'te sözdizimi + birim testleri; ardından **MySQL 8 ile gerçek
kurulum** — depo yerleşik PHP sunucusunda açılır, sihirbaz HTTP üzerinden
örnek veriyle çalıştırılır, duman testi demo modu açık ve kapalı iki
kez koşar ve v1.2.0'dan bu yana her sürümden yükseltilen şemanın yeni
kurulumla birebir aynı olduğu denetlenir.

---

Modül eklemek

php cy make:module Stok
php cy module --enable=Stok
php cy migrate

Panelde /panel/stok hazır: listeleme, ekleme, silme. Modül kendi
rotalarını, tablolarını, görünümlerini ve menü girdisini taşır.

SSH erişimi yoksa modülü panelden açın: Sistem Bilgisi → Modüller
bölümündeki düğme modülü açar ve tablolarını kurar. Kapatmak hiçbir
veriyi silmez; menüsü, sayfaları ve yetkileri devreden çıkar.

Kapalı modül hiç yüklenmez — rotaları tanımlanmaz, sınıfları
yüklenmez, olayları dinlenmez.

Modül yetkilerini kendisi dağıtır — çekirdeğin Role.php'sine
dokunulmaz:

"yetkiler": { "editor": ["stok.view", "stok.create"], "uye": ["stok.view"] }

Örnek Modül: kopyalanacak şablon

modules/Ornek kendi modülünüzü yazarken örnek alacağınız, kurulumda
açık gelen eksiksiz bir modüldür: liste, ekleme, düzenleme, silme ve
onay akışı (üye yazar, editör onaylar, sonra yayına çıkar).

Rol yetkisi module.json'da, kayıt düzeyi kural OrnekPolicy'dedir.
Görünüm ve denetleyici aynı sınıfa sorar; elle gönderilen yetkisiz
istek 403, görülemeyen kayda istek 404 alır. Adım adım rehber:
modules/Ornek/README.md.

module.json içinde "kurulumda_acik": true yazan her modül
sihirbazda işaretli gelir.

---

Sık kullanılanlar

// Adres ve varlık (hepsi köke göreli)
url('panel/ayarlar');            asset('css/site.css');

// Ayarlar
config('db.host');               // config/ dosyaları (geliştirici)
setting('site_adi');             // ayarlar tablosu (yönetici, panelden)

// Yetki
can('users.delete');

// Marka rengi (Ayarlar → Sistem → Tema Rengi)
Theme::brand();                  // '#7c3aed' — doğrulanmış
Theme::styleTag();               // düzenlere basılan <style> bloğu

// Günlük
Logger::info('…', ['id' => 3], 'auth');
Logger::security('Şüpheli istek', ['ip' => $ip]);

// Önbellek
Cache::remember('rapor', 900, fn () => $agirHesap());

// Olay
Events::dispatch(new UserRegistered($user));

// Kuyruk
Queue::push(new RaporUret(3));

// Dosya
Uploader::store($request->file('belge'), ['disk' => 'private', 'group' => 'belge']);

// API yanıtı
ApiResponse::paginated($items, $total, $page, $perPage);

---

Örnek kodlar ve belgeler

Şablonun her parçası için çalışan örnek kod, açıklamalı anlatım ve
kopyalanabilir parçacıklar Çılgın Yazılım Kod Kütüphanesi'nde:

Bu bağlantılar sitenin alt bilgisinde de sabit durur (Örnek Kodlar
sütunu); kurduğunuz projede gezinirken bir tık uzaktadır.

---

Mobil

Ön yüz ve panel ayrı ayrı mobil için tasarlanmıştır — masaüstü
düzeninin küçültülmüş hâli değildir.

Kırılma noktaları iki yüzde de aynıdır: 992px (tablet) ve 768px
(telefon); 360px altı için ayrıca sadeleştirme vardır.

---

Güvenlik

Şablon iki ayrı güvenlik incelemesinden (1.3.0 ve 1.4.0) ve bağımsız bir
rol/yetki test raporundan (1.6.0) geçti. Her bulgu yerel bir kurulumda
yeniden üretildi, düzeltildi ve testle sınandı.

Panel → Sistem Bilgisi sayfası bunların canlı denetimini yapar ve
her sorunun nasıl çözüleceğini yazar.

---

Canlıya çıkış

# .env
APP_ENV=production
APP_DEBUG=false
LOG_LEVEL=info
APP_KEY=<64 onaltılık karakter, kuruluma özel>
# Cloudflare / yük dengeleyici / nginx ters vekil arkasındaysa:
TRUSTED_PROXIES=<vekil adresleri>

php cy config:cache && php cy migrate

• [ ] kurulum/ klasörü silindi
• [ ] Demo sitesi değilse APP_DEMO=false ve örnek veri kaldırıldı

(Panel → Sistem → Örnek veriyi kaldır ya da php cy demo:temizle)

• [ ] E-posta ayarları yapıldı (kayıt formu ve "Parolamı unuttum" ancak o zaman açılır)
• [ ] Ayarlar → Sistem → KVKK sayfası ve IP saklama süresi kontrol edildi
• [ ] Panelin üstünde kırmızı/turuncu uyarı yok (debug, bekleyen migration, APP_KEY, örnek hesaplar)
• [ ] HTTPS aktif
• [ ] storage/ ve upload/ yazılabilir
• [ ] php cy mail:test başarılı
• [ ] Cron kuruldu
• [ ] Sistem Bilgisi sayfasındaki tüm denetimler yeşil
• [ ] Apache'de mod_deflate + mod_filter (sıkıştırma), mod_expires

ve mod_headers (tarayıcı önbelleği) açık

Sıkıştırma ve önbellek. .htaccess CSS, JS, JSON ve SVG'yi
sıkıştırır; sürümlü dosyalara (?v=…) bir yıllık immutable önbellek
verir. Bunun için sunucuda mod_deflate, mod_filter ve mod_headers
açık olmalıdır (mod_expires varsa sürümsüz görseller de önbelleğe
girer). Paylaşımlı hostinglerin çoğunda açıktır. XAMPP'ta
apache/conf/httpd.conf içinde mod_deflate, mod_filter ve
mod_expires satırlarının başındaki # silinip Apache yeniden
başlatılır. Modül kapalıysa site yine çalışır, yalnızca dosyalar
sıkıştırılmadan gider.
"Hata ayıklama açık" uyarısı yalnızca yerel olmayan adreste
görünür: localhost'ta APP_DEBUG=true bilinçli bir geliştirme
ayarıdır. Canlı sunucuda bu uyarıyı görürseniz .env → APP_DEBUG=false.

Nginx kullanıyorsanız

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

# Nokta ile başlayan her şey (.env, .git/, .github/ …) — .well-known hariç
location ~ /\.(?!well-known) { deny all; }

location ~ ^/(app|config|storage|views|database|modules|routes|tests|docs|kurulum)/ { deny all; }
location ~ ^/cy$   { deny all; }

location ~* ^/upload/.*\.(php\d?|phtml|phar|pl|py|cgi|sh)$ { deny all; }
location ^~ /upload/ {
    add_header X-Content-Type-Options nosniff;
    add_header Content-Security-Policy "default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; sandbox";
}

# API'nin Bearer anahtarı PHP-FPM'e iletilsin
fastcgi_param HTTP_AUTHORIZATION $http_authorization;

Kurulum bittiyse kurulum klasörünü silin; Nginx'te yukarıdaki kural
zaten kapatır, sihirbazı açmak için kuralı geçici olarak kaldırmanız gerekir.

---

Yeni projeye başlarken

git clone https://github.com/CilginYazilim/cy-php-starter yeni-proje
cd yeni-proje && rm -rf .git

# kurulum/ adresini aç, sihirbazı tamamla
# ("Örnek veriyle kur" ve "Demo modu" kapalı,
#  Modüller bölümünde "Örnek Modül" işaretsiz)

rm -rf modules/Ornek app/Jobs/OrnekIs.php

php cy make:module KendiModulun

Ardından Panel → Site Ayarları'ndan site adını, marka adını, logoyu
ve tema rengini, Ana Sayfa grubundan da ana sayfanın bölümlerini ve
metinlerini kendinize göre ayarlayın; arayüz anında yeni renginizi alır.

---

Sürüm

Güncel kararlı sürüm 1.6.2 (7 Ekim 2026). Sürüm numarası kodda, tek yerde
durur:

// config/app.php
'version' => '1.6.2',

Panel → Sistem Bilgisi sayfası bu değeri okur. Şablonu güncellediğinizde
numara kendiliğinden gelir; veritabanında ayrıca tutulmaz.

Sürüm geçmişi

Her sürümün ayrıntısı:
CHANGELOG.md.

Güncelleme (1.6.1 → 1.6.2)

1. Kodu çekin, php cy migrate çalıştırın (SSH yoksa panelde "Şimdi çalıştır").

Bir migration: parola bağlantılarının türü (parola_sifirlama.tur).
Değerlerinize dokunmaz.

1. .htaccess değişti (JS sıkıştırma, sürümlü dosyalara uzun önbellek).

Kendi .htaccess'inizi düzenlediyseniz "4) İstemci önbelleği" ve
"5) Sıkıştırma" bölümlerini aktarın.

1. Duyurudan çıkma bağlantısı artık önce onay sayfası açar; tercih

"Duyuruları kapat" düğmesiyle (POST) değişir.

Güncelleme (1.6.0 → 1.6.1)

1. Kodu çekin, php cy migrate çalıştırın (SSH yoksa panelde "Şimdi çalıştır").

İki migration: ayar açıklamaları ve bildirimler ("Yeni Üye Bildirimi"
ayarı, kullanicilar.bildirim_tercihleri sütunu). Değerlerinize dokunmaz.

1. Geliştirme modunda (APP_DEBUG=true) giriş ekranı artık demo parolalarını

listelemez; hızlı giriş yalnızca APP_DEMO=true iken görünür.

1. "Örnek veriyi kaldır" artık örnek marka ayarlarını da (slogan, sosyal

hesaplar…) nötre döndürür; sizin değiştirdiklerinize dokunmaz.

Güncelleme (1.5.x → 1.6.0)

1. Yedek alın (veritabanı + .env), kodu çekin.
2. php cy migrate — SSH yoksa panelde çıkan "Şimdi çalıştır". Tek

migration: yeni ayarlar (Ana Sayfa grubu, KVKK, parola sıfırlama, hesap
silme), parola sıfırlama tablosu, API anahtarı kapsam sütunları ve
"Gizlilik ve KVKK" sayfası. Var olan ayarlarınıza dokunmaz.

1. Ana sayfanız eskisi gibi kalır; yeni bölümleri **Panel → Ayarlar → Ana

Sayfa**'dan açın. Örnek vitrini görmek isterseniz: php cy db:seed.

1. Var olan API anahtarları "okuma + yazma" kapsamında çalışmaya devam eder.

Güncelleme (1.5.0 → 1.5.1)

Kodu çektikten sonra php cy migrate çalıştırın (SSH yoksa panelde
çıkan "1 migration bekliyor → Şimdi çalıştır"). Yalnızca indeks
ekler, veriye dokunmaz.

Güncelleme (1.4.0 → 1.5.0)

Çekirdekte migration yok; kodu çekmeniz yeterli. Demo modu varsayılan
olarak kapalıdır. Var olan bir kurulumda Örnek Modül'ü açmanın en kolay
yolu panel: Sistem Bilgisi → Modüller bölümündeki düğme modülü açar
ve tablolarını kurar. Komut satırından açıp deneme kayıtlarıyla
doldurmak için:

php cy module --enable=Ornek
php cy migrate                          # modülün 2 migration'ı
php cy db:seed --class=OrnekIcerik      # 12 rastgele kayıt

Ornek modülü zaten açıksa yalnızca php cy migrate yeterlidir (SSH
yoksa Panel → Sistem Bilgisi'ndeki düğme).

Güncelleme (1.2.x ya da 1.3.x → 1.4.0)

1. Yedek alın (veritabanı + .env).
2. Kodu çekin.
3. php cy migrate çalıştırın — SSH yoksa **Panel → Sistem Bilgisi →

Migration'ları Çalıştır**. Migration'lar çalıştırılmadan da giriş
yapılabilir; panel her sayfada uyarır. Eski kurulum migration'ları bu
adımda kendiliğinden temel partiye (0) taşınır; elle SQL gerekmez.

1. .env dosyanızı açın ve şunları kontrol edin (eski sihirbaz bu

satırları geliştirme değerleriyle yazıyordu):

• APP_ENV=production ve APP_DEBUG=false olmalı (satırları SİLMEYİN,

değerlerini değiştirin).

• APP_KEY boşsa doldurun: php -r "echo bin2hex(random_bytes(32));"
• SESSION_NAME boşsa doldurun (örn. CYS_ + 10 rastgele harf/rakam);

aynı alan adında başka kurulum varsa her biri farklı olmalı.

• Site bir vekilin arkasındaysa TRUSTED_PROXIES yazın.
• Eksik anahtarlar için .env.example'a bakın.

1. php cy config:cache kullanıyorsanız yeniden çalıştırın.

Kurulum kimliği artık yalnızca APP_KEY'den türetildiği için bütün
kullanıcılar bir kez yeniden giriş yapar. 1.1.0'dan güncelliyorsanız
da aynı adımlar yeterlidir.

---