PHP PDO Ajax CRUD Örneği

---

Demoda 60 saniyede neleri deneyebilirsiniz?

İpucu: Demoyu açıkken F12 → Network sekmesini açın. Her istekte ajax.php'ye giden action ve csrf_token alanlarını, dönen JSON'u ve HTTP durum kodlarını (200 / 419 / 422) canlı görebilirsiniz. Öğrenmenin en hızlı yolu budur.

Demo alanı hakkında bilinmesi gerekenler

Demo geçici olarak kapalıysa endişelenmeyin: depoyu klonlayıp crud.sql'i içe aktarmanız aynı ekranı kendi bilgisayarınızda 2 dakikada ayağa kaldırır → Kurulum

---

Bu Proje Nedir?

"PHP CRUD örneği" diye aratınca çıkan sonuçların çoğu aynı üç hataya sahiptir: sorgular $_POST ile birleştirilir, ekrana basılan veri kaçışlanmaz, dosya yükleme uzantıya güvenir. Yeni başlayan biri bu kodu kopyalayıp öğrenir — ve yanlışı da öğrenmiş olur.

Bu proje o kısır döngüyü kırmak için var: aynı CRUD'u, aynı sadelikte, ama gerçekten güvenli yazılmış haliyle gösteriyor. Fark satır sayısında değil, satırların neden öyle yazıldığında. getimagesize() neden explode('.', $name)'den daha güvenli, EMULATE_PREPARES = false ne değiştiriyor, hash_equals() olmadan CSRF token'ı neden kırılabilir — bunların hepsi kod içindeki yorumlarda, olduğu yerde anlatılıyor. Ayrı bir kitap okumanız gerekmiyor; dosyayı açıp okumanız yeterli.

Kimler için uygun?

• PHP + AJAX + DataTables üçlüsünü doğru öğrenmek isteyenler
• Kendi projesine hazır ve güvenli bir CRUD iskeleti arayanlar
• Bootstrap 5 üzerine kurulu, tekrar kullanılabilir bir tasarım kalıbı arayanlar
• Bir CRUD'un ne kadar mobil dostu, erişilebilir ve bağımlılıksız olabileceğini merak edenler

Klonla, crud.sql'i içe aktar, çalıştır. Başka hiçbir kurulum adımı yok. Composer yok, npm yok, internet bağlantısı bile gerekmiyor — tüm kütüphaneler proje içinde. Hiç kurulum yapmadan denemek isterseniz Canlı Demo bölümüne göz atın.

Bu proje, Çılgın Yazılım Kütüphanesi altında yayınlanan açıklamalı, üretime hazır örneklerden biridir — aynı tasarım kalıbıyla hazırlanmış diğer örnekleri de orada bulabilirsiniz.

---

İçindekiler

• Canlı Demo
• Ekran Görüntüleri
• Neler Var?
• Güvenlik: Neyi, Nasıl Kapattık?
• Kurulum
• Yapılandırma
• Çılgın Yazılım Tasarım Kalıbı
• Dosya Yapısı
• Nasıl Çalışıyor?
• AJAX API Referansı
• Veritabanı Şeması
• Sık Sorulanlar
• Canlı Ortama Alırken
• Sorun Giderme
• Yol Haritası
• Katkı
• Lisans

---

Ekran Görüntüleri

Kayıt listesi

Gradyanlı marka başlığı, canlı arama, sıralanabilir sütunlar ve tek sütunda toplanmış işlem butonları. Görseli olmayan kayıtlar için adın baş harfinden otomatik rozet üretilir.

Detay modalı

Göz butonuna basıldığında açılır. Büyük profil görseli, kayıt bilgileri ve düzenlemeye geçiş kısayolu içerir.

Ekleme / düzenleme formu

Tek bir modal hem ekleme hem düzenleme için kullanılır. Görsel seçildiğinde canlı önizleme gösterilir, hatalar ilgili alanın altında belirir.

Sunucu taraflı sayfalama

Sayfalama, arama ve sıralama sunucuda yapılır; tarayıcıya yalnızca görüntülenen sayfa gönderilir.

Arama

Ad ve soyad üzerinde arama yapılır. recordsFiltered doğru hesaplandığı için sayfalama filtreye uyum sağlar.

Üç modal:

---

Neler Var?

Arayüz

• Marka gradyanlı başlık ve modallar
• Üç ayrı modal (detay / form / silme onayı)
• Sağ üstte toast bildirimleri
• Görsel canlı önizleme (yüklemeden önce)
• Görselsiz kayıtlar için baş harf rozeti
• Otomatik koyu tema (işletim sistemi ayarını izler)
• Mobil için ayrıca inceltilmiş — dokunma hedefleri ≥40px, tablo yatay kaydırmaya zorlamaz, erişilebilir (ARIA etiketli)
• Tamamı Türkçe — CDN'siz, çevrimdışı çalışır

Altyapı

• Sunucu taraflı (server-side) DataTables
• Tek AJAX uç noktası, action tabanlı yönlendirme
• Çift katmanlı doğrulama (istemci + sunucu)
• Alan bazlı hata mesajları (HTTP 422)
• Otomatik dosya temizliği (yetim dosya bırakmaz)
• Ortam değişkeni desteği
• 50 hazır örnek kayıt
• Kodun her satırı açıklamalı

---

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

İnternetteki benzer örneklerin çoğunda bulunan açıklar ve bu projede nasıl önlendikleri:

---

Kurulum

Sadece görmek istiyorsanız kurulum gerekmez → Canlı Demoyu açın. Aşağıdaki adımlar, projeyi kendi bilgisayarınızda çalıştırmak içindir (~2 dakika).

Gereksinimler

• PHP 8.0+ (pdo_mysql ve gd eklentileri)
• MySQL 5.7+ veya MariaDB 10.3+
• Apache (XAMPP / WAMP / Laragon) — ya da PHP'nin yerleşik sunucusu

Adımlar

1 — Projeyi indirin

git clone https://github.com/CilginYazilim/php-pdo-ajax-crud.git
cd php-pdo-ajax-crud

2 — Veritabanını oluşturun

crud.sql veritabanını da kendisi oluşturur; önceden crud adında bir veritabanı açmanıza gerek yok.

mysql -u root -p < crud.sql

İsteğe bağlı — kendi veritabanı bilgileriniz:
cp .env.example .env (Windows: copy .env.example .env) deyip DB_*
satırlarını doldurun. Bu dosya olmadan da çalışır; varsayılanlar yerel bir
XAMPP kurulumuna (root, boş parola) göredir. .env .gitignore
içindedir — parolanız depoya gitmez.

phpMyAdmin ile: İçe Aktar → Dosya seç → crud.sql → Başlat

3 — Çalıştırın

php -S 127.0.0.1:8000

XAMPP kullanıyorsanız projeyi htdocs altına koymanız ve şu adresi açmanız yeterli:
http://localhost/php-pdo-ajax-crud/

4 — Tarayıcıda açın → http://127.0.0.1:8000/

Karşınıza 50 örnek kayıt dolu, çalışır durumda bir tablo gelecek.

Linux/macOS kullanıcıları: upload/ klasörüne yazma izni gerekir → chmod 755 upload

Ortam değişkenleri

Depo kökündeki .env dosyasına yazın; system/config.php dosyasına
hiç dokunmayın:

cp .env.example .env        # Windows: copy .env.example .env

.env .gitignore içindedir: depoya gönderilmez ve dağıtım (deploy) onu
silmez. system/config.php ise depoda durur ve her dağıtımda depodaki
sürümle değiştirilir — parolayı oraya yazarsanız hem GitHub'a gider hem de
ilk deploy'da kaybolur.

Dosyayı hiç oluşturmasanız da uygulama çalışır; aşağıdaki varsayılanlar
yerel bir XAMPP kurulumuna göredir.

Değer arama sırası: .env → sunucunun gerçek ortam değişkeni
(Apache SetEnv, systemd…) → buradaki varsayılan.

APP_TIMEZONE neden var? XAMPP'ın php.ini dosyasındaki
date.timezone, MySQL'in kullandığı sistem diliminden farklı olabilir.
Test makinesinde PHP Europe/Berlin, MySQL Europe/Istanbul
kullanıyordu; aynı anı anlatan iki satır bir saat farklı görünüyordu.
Zaman hesapları SQL tarafında yapıldığı için doğruydu, ama ekrana
basılan saat kayıyordu. Artık dilim açıkça sabitleniyor — sunucunuz başka
bir bölgedeyse bu değişkeni tanımlamanız yeterli, koda dokunmayın.

---

Yapılandırma

Tüm ayarlar system/config.php içinde, açıklamalarıyla birlikte:

Şifreyi koda yazmayın

Tüm DB_* sabitleri ortam değişkeniyle geçersiz kılınabilir. Böylece şifreniz GitHub'a düşmez:

# Linux / macOS
export DB_HOST=localhost DB_USER=uygulama DB_PASS='••••••••'

# Windows (PowerShell)
$env:DB_USER = "uygulama"; $env:DB_PASS = "••••••••"

Apache için .htaccess ya da httpd.conf içinde: SetEnv DB_PASS "guclu-sifre"

---

Çılgın Yazılım Tasarım Kalıbı

assets/css/cilginyazilim.css dosyası, bu projeye değil markaya aittir. Diğer örnek projelerde de aynı görsel dili kullanabilmek için ayrı bir dosya olarak tutulur.

Başka bir projede kullanmak

<!-- 1) Bootstrap'ten SONRA ekleyin -->
<link rel="stylesheet" href="assets/css/bootstrap.min.css">
<link rel="stylesheet" href="assets/css/cilginyazilim.css">

<!-- 2) body'ye tema sınıfını verin -->
<body class="cy-app">

Hazır bileşenler

Renkleri değiştirmek

Tüm bileşenler CSS değişkenlerinden beslenir. Tek yeri değiştirmek yeter:

:root {
    --cy-brand-900: #061321;   /* Logodaki en koyu lacivert */
    --cy-brand-600: #0b5cb5;   /* Ana marka mavisi          */
    --cy-accent:    #0ea5e9;   /* Vurgu rengi               */
    --cy-gradient:  linear-gradient(135deg, #061321, #0b5cb5 45%, #0284c7);
}

Renk paleti cilginyazilim.com logosundan türetilmiştir: koyu lacivertten canlı maviye uzanan geçiş. Logo assets/images/logo.png içinde yer alır ve başlıkta beyaz yuvarlak bir zemine oturtulur.

Koyu tema

Kullanıcının işletim sistemi koyu temadaysa otomatik devreye girer. Zorlamak isterseniz:

<html data-cy-theme="dark">   <!-- veya "light" -->

---

Dosya Yapısı

.
├── index.php                      # Arayüz + tüm JavaScript mantığı
├── .env.example                   # Veritabanı bilgileri (isteğe bağlı) — .gitignore içinde
├── crud.sql                       # Veritabanı şeması + 50 örnek kayıt
├── README.md                      # Türkçe belgelendirme
├── README.en.md                   # İngilizce belgelendirme
├── LICENSE                        # MIT lisansı
├── .gitignore
│
├── docs/
│   └── screenshots/               # README'de kullanılan ekran görüntüleri
│
├── system/
│   ├── config.php                 # Ayarlar, oturum, PDO bağlantısı
│   ├── function.php               # Yardımcı fonksiyonlar
│   └── ajax.php                   # AJAX uç noktası / CRUD yönlendiricisi
│
├── assets/
│   ├── css/
│   │   ├── bootstrap.min.css
│   │   ├── dataTables.bootstrap5.min.css
│   │   ├── cilginyazilim.css      # ★ MARKA TASARIM KALIBI
│   │   └── style.css              # Sadece bu sayfaya özel eklemeler
│   └── js/
│       ├── jquery-3.7.0.js
│       ├── bootstrap.bundle.js
│       ├── jquery.dataTables.min.js
│       └── dataTables.bootstrap5.min.js
│
└── upload/
    ├── .htaccess                  # Klasörde kod çalıştırmayı engeller
    └── *.png                      # Örnek görseller

Yükleme sırası önemlidir:

CSS:  bootstrap → dataTables → cilginyazilim → style
JS:   jQuery → bootstrap.bundle → dataTables → dataTables.bootstrap5

Sıra bozulursa $ is not defined gibi hatalar alırsınız.

---

Nasıl Çalışıyor?

┌─────────────────────────────────────────────────────────────────────┐
│  TARAYICI  (index.php)                                              │
│                                                                      │
│  DataTables ──┐                                                      │
│  Form gönder ─┤                                                      │
│  Detay butonu ┼──► jQuery AJAX ──► POST { action, csrf_token, ... }  │
│  Sil butonu ──┘                              │                       │
└──────────────────────────────────────────────┼───────────────────────┘
                                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│  SUNUCU  (system/ajax.php)                                          │
│                                                                      │
│   1. POST mu?              → değilse 405                            │
│   2. require_csrf()        → geçersizse 419                         │
│   3. action'a göre dağıt:  list │ add │ edit │ fetch │ delete       │
│   4. validate_name()       → hatalıysa 422 + errors                 │
│   5. upload_image()        → içerikten tür doğrulama                │
│   6. PDO prepared query    → MySQL                                  │
│   7. json_response()       → tek noktadan JSON çıkışı               │
│                                                                      │
│   Tüm bunlar try/catch içinde: hiçbir hata çıplak PHP mesajı olarak │
│   sızmaz, hepsi düzgün JSON'a çevrilir.                             │
└─────────────────────────────────────────────────────────────────────┘

Sorumluluk dağılımı

Öğrenirken dikkat çeken noktalar

Kod içindeki yorumlarda ayrıntısıyla anlatılan, yeni başlayanların sık takıldığı konular:

• serverSide: true ne demek? — 50 kayıtta fark etmez ama 100.000 kayıtta tarayıcıya tüm veriyi göndermemenizi sağlar.
• Event delegation — AJAX ile sonradan gelen butonlara neden $('.js-edit').click() çalışmaz, $('#user_data').on('click', '.js-edit', ...) neden çalışır.
• EMULATE_PREPARES = false tuzağı — aynı isimli yer tutucu (:search) neden iki kez kullanılamaz, Invalid parameter number hatası nereden gelir.
• contentType: false, processData: false — dosya yüklerken bu ikisi neden zorunlu.
• Sütun adı neden bind edilemez — ve bu yüzden neden beyaz liste şart.

---

AJAX API Referansı

Tüm istekler POST ile system/ajax.php adresine yapılır ve geçerli bir csrf_token içermelidir. Yanıtlar application/json türündedir.

action=list — DataTables listeleme

İstek: draw, start, length, search[value], order[0][column], order[0][dir]

Yanıt:

{
  "draw": 1,
  "recordsTotal": 50,
  "recordsFiltered": 50,
  "data": [[50, "<img …>", "Ozan", "TOPAL", "<span…>23.02.2025 23:28</span>", "<div class=\"cy-actions\">…</div>"]]
}

Sıralanabilir sütunlar beyaz listeyle sınırlıdır: 0 → id, 2 → name, 3 → surname, 4 → tarih.
Foto (1) ve İşlemler (5) sütunları veritabanı sütunu olmadıkları için sıralanamaz.

action=add — Yeni kayıt

İstek: name, surname, image_user (opsiyonel, multipart/form-data)

Başarılı (200):

{ "success": true, "type": "success", "description": "Kayıt başarıyla eklendi.", "id": 51 }

Doğrulama hatası (422):

{
  "success": false,
  "type": "danger",
  "description": "Lütfen formdaki hataları düzeltin.",
  "errors": { "name": "Ad alanı boş bırakılamaz." }
}

errors nesnesinin anahtarları form alanlarının id'leriyle birebir aynıdır; JavaScript mesajı doğrudan ilgili alanın altına yazar.

action=edit — Güncelleme

İstek: user_id, name, surname, image_user (opsiyonel)

Yeni görsel gönderilmezse mevcut görsel korunur. Gönderilirse yenisi kaydedilir ve eski dosya diskten silinir.

action=fetch — Tek kayıt (detay + düzenleme)

İstek: id

{
  "success": true,
  "id": 1,
  "name": "Evren",
  "surname": "ÇILGIN",
  "image": "2090273627.png",
  "image_url": "upload/2090273627.png",
  "tarih": "06.01.2025 19:34"
}

Hazır HTML değil ham veri döner; ekranı JavaScript .text() ile doldurduğu için XSS riski oluşmaz.

action=delete — Silme

İstek: id

Kayıt ve ilişkili görsel dosyası birlikte silinir. Kayıt yoksa 404 döner.

HTTP durum kodları

---

Veritabanı Şeması

CREATE TABLE `users` (
  `id`      INT UNSIGNED NOT NULL AUTO_INCREMENT,
  `name`    VARCHAR(150) NOT NULL,
  `surname` VARCHAR(150) NOT NULL,
  `image`   VARCHAR(191) NOT NULL DEFAULT '',   -- sadece dosya adı, tam yol değil
  `tarih`   TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_users_name`    (`name`),             -- arama ve sıralama için
  KEY `idx_users_surname` (`surname`),
  KEY `idx_users_tarih`   (`tarih`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Mevcut (eski) bir kurulumu veri kaybetmeden yükseltmek için crud.sql dosyasının sonundaki ALTER TABLE komutlarını kullanın.

---

Sık Sorulanlar

Bu kodu kendi projemde kullanabilir miyim?

Evet. MIT lisanslı — ticari projeler dahil serbestçe kullanabilir, değiştirebilir, dağıtabilirsiniz. Atıf zorunlu değil ama sevindirir.

Tabloya yeni bir sütun eklemek istiyorum, nereleri değiştirmeliyim?

Örnek: email sütunu eklemek için beş nokta:

1. crud.sql → tabloya sütunu ekleyin
2. index.php → forma input, `'e ekleyin
3. system/function.php → find_user() içindeki SELECT listesine ekleyin
4. system/ajax.php → handle_save() içinde doğrulama + INSERT/UPDATE, handle_list() içinde $data[] dizisine yeni hücre
5. system/ajax.php → sütun eklediyseniz $sortableColumns` indekslerini kaydırmayı unutmayın

` sayısı ile $data[]` dizisinin uzunluğu aynı olmak zorundadır, aksi halde DataTables hata verir.

Görsel boyutu sınırını nasıl artırırım?

system/config.php içinde UPLOAD_MAX_BYTES değerini değiştirin. Ayrıca php.ini içindeki upload_max_filesize ve post_max_size değerlerini de artırın — PHP'nin limiti sizinkinden düşükse dosya sunucuya hiç ulaşmaz.

Neden hem istemcide hem sunucuda doğrulama var?

İstemci doğrulaması kullanıcı deneyimi içindir: kullanıcı sunucuya gitmeden anında geri bildirim alır. Ama JavaScript kapatılabilir veya istek doğrudan curl ile atılabilir. Bu yüzden gerçek koruma her zaman sunucudadır. İkisi birlikte kullanılır.

DataTables'ın serverSide: true ayarını kapatabilir miyim?

Kapatabilirsiniz ama o zaman tüm kayıtlar tek seferde tarayıcıya gönderilir. 50 kayıtta sorun olmaz; 50.000 kayıtta sayfa donar. Bu örnekte gerçek dünya senaryosunu göstermek için açık bırakıldı.

Bootstrap 5 sürümünü güncelleyebilir miyim?

Evet, assets/ altındaki dosyaları değiştirmeniz yeterli. Tasarım kalıbı Bootstrap'in üzerine ekleme yapar, onu değiştirmez — bu yüzden sürüm yükseltmeleri sorunsuz geçer.

---

Canlı Ortama Alırken

• [ ] APP_DEBUG değerini false yapın
• [ ] Veritabanı için root yerine sınırlı yetkili bir kullanıcı oluşturun
• [ ] Kimlik bilgilerini ortam değişkeni olarak tanımlayın, koda gömmeyin
• [ ] HTTPS kullanın; session.cookie_secure = 1 ve session.cookie_httponly = 1 ayarlayın
• [ ] Nginx kullanıyorsanız .htaccess çalışmaz — yükleme klasöründe PHP'yi sunucu yapılandırmasından kapatın:

```nginx
location ^~ /upload/ {
location ~ \.php$ { deny all; }
}
```

• [ ] upload/ klasörünü düzenli yedekleyin
• [ ] Giriş sistemi ekleyin — bu örnekte kimlik doğrulama yoktur, herkes tüm kayıtları düzenleyebilir

---

Sorun Giderme

---

Yol Haritası

• [ ] Kullanıcı girişi ve rol tabanlı yetkilendirme
• [ ] Toplu silme (checkbox ile çoklu seçim)
• [ ] Excel / CSV / PDF dışa aktarma (DataTables Buttons)
• [ ] Sunucu tarafında görsel yeniden boyutlandırma ve thumbnail
• [ ] REST API katmanı (JWT ile)
• [ ] Soft delete + işlem geçmişi (audit log)
• [ ] PHPUnit ile birim testleri
• [ ] Koyu tema için elle açma/kapama düğmesi

---

Katkı

Bu proje herkese açıktır — dilediğiniz geliştirmeyle katkı sağlayabilirsiniz.

📦 Depo: github.com/CilginYazilim/php-pdo-ajax-crud

Pull request adımları

# 1) Depoyu çatallayın (GitHub'da "Fork" butonu), sonra kendi kopyanızı indirin
git clone https://github.com/KULLANICI-ADINIZ/php-pdo-ajax-crud.git
cd php-pdo-ajax-crud

# 2) Değişikliğiniz için yeni bir dal açın
git checkout -b ozellik/yeni-ozellik

# 3) Kodunuzu yazın, sonra kaydedin
git add .
git commit -m "Yeni özellik: kısa ve açıklayıcı bir başlık"

# 4) Kendi çatalınıza gönderin
git push origin ozellik/yeni-ozellik

# 5) GitHub'da "Compare & pull request" butonuna tıklayın

Katkı ölçütleri

• Kod açıklamalı olsun. Bu projenin temel amacı öğretmek; yorumsuz kod PR'ı geri döner.
• Güvenlik kontrollerini atlamayın. Prepared statement, e() ile kaçışlama ve require_csrf() her yeni işlemde de olmalı.
• Tasarım değişikliklerini cilginyazilim.css üzerinden yapın, satır içi style="..." kullanmayın.
• Sütun eklerken ` sayısı ile $data[]` uzunluğunu eşitlemeyi unutmayın.
• Yeni bir dış kütüphane eklemeden önce issue açıp tartışalım — proje bilinçli olarak bağımlılıksızdır.

---

Lisans

MIT — ticari kullanım dahil serbesttir.