Canlı Arama ve Otomatik Tamamlama

---

Demoda 60 saniyede neleri deneyebilirsiniz?

İpucu: Demoyu açıkken F12 → Network sekmesini açın. Yazarken autocomplete ve search isteklerinin nasıl debounce edildiğini, her isteğe verilen seq numarasını ve HTTP durum kodlarını (200 / 403 / 405 / 429) canlı görebilirsiniz.

Demo alanı hakkında bilinmesi gerekenler

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

---

Bu Proje Nedir?

Arama kutusu, bir panelin en çok kullanılan ve en az düşünülen parçasıdır. Tipik uygulaması tek satırdır:

SELECT * FROM articles WHERE title LIKE '%$q%'

Bu satırın dört ayrı sorunu vardır ve hiçbiri hemen görünmez:

1. İndeks kullanamaz. Baştaki % yüzünden MySQL her satırı okur. Bin satırda fark edilmez, yüz binde sayfa donar.
2. Sıralama yoktur. Hangi sonucun daha alakalı olduğu bilinmez; tablo sırası neyse o gelir.
3. Her tuş vuruşunda çalışır. "performans" yazmak 10 istek demektir.
4. Yanıtlar sırasız döner. per isteği yavaş, performans isteği hızlı dönerse ekranda yanlış sonuç kalır — ve bu sorunu debounce çözmez.

Bu proje dördünü de ele alıyor: FULLTEXT indeksi ile alaka skoruna göre arıyor, boolean mod önek eşleşmesiyle kullanıcı henüz yazarken sonuç veriyor, debounce ile istek sayısını düşürüyor ve sıra numarasıyla yarış durumunu kapatıyor.

Bir de beşinci bir şey yapıyor: ne yaptığını söylüyor. Hangi modun çalıştığı (FULLTEXT mi LIKE mı), kaç sonuç bulunduğu ve sorgunun kaç milisaniye sürdüğü ekranda yazar. Bu satır gerçek bir projede kaldırılabilir — ama bir örneğin işi, kararlarını görünür kılmaktır.

Kimler için uygun?

• Kendi paneline arama kutusu ekleyecek ve LIKE '%...%' ile başlamak istemeyenler
• Elasticsearch kurmadan önce MySQL'in ne kadarını yapabileceğini merak edenler
• Türkçe metinde arama yapan herkes (harf katlaması, ekler, önek eşleşmesi)
• Otomatik tamamlamayı kütüphanesiz ve klavye erişilebilir yazmak isteyenler
• Bootstrap 5 üzerine kurulu, tekrar kullanılabilir bir tasarım kalıbı arayanlar

Klonla, cy_search.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.

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

---

İçindekiler

• Canlı Demo
• Ekran Görüntüleri
• Beş Kritik Karar
• Neler Var?
• Güvenlik: Neyi, Nasıl Kapattık?
• Kurulum
• Yapılandırma
• Kendi Projenize Eklemek
• Çı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

Canlı arama

Vurgulanmış sonuçlar, alaka skoru, kategori facet'leri ve ölçüm satırı. Sayaç şeridi hem veri kümesini (38 yazı, 6 kategori) hem o anki aramayı (8 sonuç, 48 ms, FULLTEXT boolean) gösterir.

Otomatik tamamlama ve klavye

Öneri listesi yalnızca başlıklarda arar ve eşleşen kısmı vurgular. Klavyeyle seçili öğe, fare ile üzerine gelinen öğeyle aynı görünür — kullanıcı girdi yöntemini değiştirdiğinde arayüzün dili değişmemelidir.

Yazı detayı

Sonuç kartı bir özet gösterir; tıklayınca yazının tamamı açılır ve arama sözcükleri burada da vurgulanır. Adres çubuğu #makale-7 olur; bağlantı paylaşılabilir. Etiketlere tıklamak yeni bir arama başlatır.

Mobil görünüm

Arama kutusu küçültülmez — dokunmatik ekranda asıl hedef odur. Skor rozeti gizlenir, facet çipleri sarar, yatay kaydırma yoktur.

---

Beş Kritik Karar

1) LIKE değil FULLTEXT — ve neden boolean mod

LIKE '%kelime%' indeks kullanamaz: baştaki joker yüzünden MySQL tabloyu baştan sona okur. FULLTEXT indeksi ise kelimeleri önceden ayrıştırıp saklar ve alaka skoru üretir.

FULLTEXT'in iki modu vardır ve bu proje boolean modu seçer:

Boolean modun seçilme sebebi tek bir kelimede özetlenir: *****. Canlı aramada kullanıcı henüz yazmaktadır; perfor yazdığında performans bulunmalıdır. Önek eşleşmesi yalnızca boolean modda vardır.

Türkçe için ikinci bir sebep daha var: dil eklemeli olduğu için indeks, indeksin, indeksleri üç ayrı sözcüktür ve natural language modu bunları birbirine bağlamaz. indeks* üçünü de yakalar — kök bulmaya (stemming) yaklaşan ücretsiz bir yaklaşıklık.

2) Ham girdi asla AGAINST() içine konmaz

Boolean modda + - * " ( ) ~ < > @ karakterlerinin hepsi operatördür. Kullanıcının yazdığını olduğu gibi geçirmek iki farklı hataya yol açar:

• C++ araması sözdizimi hatası verir
• -güvenlik yazan kullanıcı, farkında olmadan o kelimeyi dışlar ve neden sonuç bulamadığını anlayamaz

Çözüm, harf ve rakam dışındaki her şeyi atmak; operatörleri biz eklemek:

function boolean_query(string $raw): string
{
    $clean = preg_replace('/[^\p{L}\p{N}\s]+/u', ' ', $raw) ?? '';
    $words = preg_split('/\s+/u', trim($clean), -1, PREG_SPLIT_NO_EMPTY) ?: [];

    $terms = [];
    foreach ($words as $w) {
        if (mb_strlen($w) < 2) { continue; }
        $terms[] = '+' . $w . '*';      // +kelime*  → zorunlu + önek
    }
    return implode(' ', $terms);
}

3) Debounce yarış durumunu ÇÖZMEZ

Canlı aramanın iki ayrı sorunu vardır ve çoğu örnek yalnızca birincisini çözer.

Sorun 1 — çok fazla istek. Çözüm debounce: yazma durduktan 200 ms sonra tek istek.

Sorun 2 — yanıtların sırasız dönmesi. Debounce bunu azaltır ama kapatmaz. Ağ gecikmesi eşit değildir:

gönderilen:  1(per) ────────────────────→ yavaş
             2(perf) ──────→ hızlı
             3(performans) ─→ hızlı
dönen:       2 ✔ → 3 ✔ → 1 ✗  (1 < 3 olduğu için ATILIR)

Bu koruma olmasaydı ekranda per sonuçları kalırdı — kullanıcı doğru yazmıştır ama yanlış sonucu görür. Çözüm, her isteğe artan bir numara vermek ve sunucunun onu aynen geri döndürmesi:

if (res.seq < renderedSeq) { return; }   // eski yanıt — at
renderedSeq = res.seq;

Kararın istemcide verilmesi zorunludur: "en son hangi isteği gönderdim" bilgisi yalnızca orada vardır.

4) Türkçe harf katlaması iki ayrı yerde çözülür

IŞIK araması ışık kelimesini bulmalı ve vurgulamalıdır. Bunlar iki farklı sorundur:

• Bulmak MySQL'in işidir ve utf8mb4_unicode_ci karşılaştırması bunu hallederi
• Vurgulamak PHP'nin işidir ve orada iki tuzak vardır

Birincisi bilinen tuzak: mb_strtolower('I') → i verir, ama Türkçede Inın küçüğü ıdır. İkincisi daha sinsi ve arayanı uzun süre uğraştırır:

mb_strlen('İ')                     // 1
mb_strlen(mb_strtolower('İ'))      // 2  ← i + birleştirici nokta!

Vurgulama konumları karakter indisine dayandığı için, katlanmış metnin uzunluğu orijinalden farklı olduğunda bütün işaretler kayar. Bu yüzden kendi eşlememizi yazıyoruz — ve tablo birebirdir:

function tr_fold(string $s): string
{
    $map = ['İ'=>'i','I'=>'i','ı'=>'i','Ş'=>'s','ş'=>'s','Ğ'=>'g','ğ'=>'g',
            'Ü'=>'u','ü'=>'u','Ö'=>'o','ö'=>'o','Ç'=>'c','ç'=>'c'];

    return mb_strtolower(strtr($s, $map), 'UTF-8');
}

5) Vurgulama sırası: önce işaretle, sonra kaçışla

İlk akla gelen yol çalışıyor gibi görünür ama HTML varlıklarını bozar:

// YANLIŞ: önce kaçışla, sonra <mark> ekle
$safe = htmlspecialchars($text);
$safe = str_replace($word, '<mark>' . $word . '</mark>', $safe);

Metinde & geçtiğinde kaçışlanmış hâli & olur. Kullanıcı amp aratırsa vurgulama tam o varlığın ortasına girer:

&amp;   →   &<mark>amp</mark>;      ← bozuk HTML, ekranda ham "&amp;"

Doğru sıra üç adımdır:

1. Ham metinde eşleşmeleri bul, yerlerine \x00 … \x01 gibi metinde asla bulunmayacak ayraçlar koy
2. Metnin tamamını kaçışla (ayraçlar da güvenle taşınır)
3. Ayraçları ` ve ` ile değiştir

$out = str_replace(["\x00", "\x01"], ['<mark>', '</mark>'], e($prefix . $out . $suffix));

Bu, vurgulama özelliğinin XSS'e dönüşmeden çalışmasını sağlayan şeydir: çıktıdaki tek HTML etiketi bizim koyduğumuzdur.

---

Neler Var?

Arama çekirdeği

• MySQL FULLTEXT indeksi, boolean mod, önek eşleşmesi
• Ham girdi güvenli bir boolean ifadeye çevrilir (operatör enjeksiyonu yok)
• 3 harften kısa terimlerde bilinçli LIKE geri dönüşü — ve bunu söyler
• Alaka skoru ekranda; sıralama alaka / en yeni / en eski (beyaz liste)
• Kategori facet sayıları, filtre uygulanmadan hesaplanır
• Sonuç yoksa terim düşürerek sonuç veren bir sorgu önerir
• Türkçe harf katlaması (tr_fold) — birebir, indis kaydırmaz
• Özet penceresi ilk eşleşmenin çevresinden kesilir
• Öneri listesi yalnızca başlıklarda arar (ayrı FULLTEXT indeksi)

Arayüz ve altyapı

• Debounce (200 ms) + sıra numarasıyla yarış koruması
• Klavye gezinmesi: ↑ ↓ Enter Esc, döngüsel
• role="combobox" + aria-activedescendant ile ekran okuyucu desteği
• Vurgulama XSS'e dönüşmeden: işaretle → kaçışla → etikete çevir
• URL senkronu: ?q=...&kategori=...&sirala=...&sayfa=...
• Derin bağlantı #makale-7, paylaşılabilir yazı detayı
• Önerilen aramalar, arama kaydı tutmadan etiketlerden üretilir
• Sayaç şeridi + ölçüm satırı (mod ve süre)
• İki ayrı hız sınırı kovası (autocomplete / search)
• Mobil: 767 / 480px eşikleri, yatay kaydırma yok

---

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

---

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 mbstring eklentileri)
• MySQL 5.6+ veya MariaDB 10.0.5+ — InnoDB FULLTEXT indeksi için
• Apache (XAMPP / WAMP / Laragon) — ya da PHP'nin yerleşik sunucusu

Adımlar

1 — Projeyi indirin

git clone https://github.com/CilginYazilim/search-autocomplete.git
cd search-autocomplete

2 — Veritabanını oluşturun

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

mysql -u root -p < cy_search.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ç → cy_search.sql → Başlat

3 — Çalıştırın

php -S 127.0.0.1:8000

XAMPP kullanıyorsanız projeyi htdocs altına koyup şu adresi açın:
http://localhost/search-autocomplete/

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

Karşınıza 38 yazı dolu, çalışır durumda bir arama ekranı gelecek. ▶ Örnek arama düğmesine basarak hemen deneyebilirsiniz.

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çindedir.

MIN_QUERY_LEN iki yerde tutulmaz

Sunucudaki sabit index.php tarafından istemciye taşınır:

window.CY_MIN_LEN = <?= (int) MIN_QUERY_LEN ?>;

Elle kopyalanmış bir sayı olsaydı, biri değişip diğeri unutulduğunda kullanıcı sunucunun "çok kısa" dediği bir sorgu için boş bir liste görür ve nedenini anlamazdı.

FULLTEXT sözcük eşiğini değiştirmek

InnoDB varsayılan olarak 3 harften kısa sözcükleri indekslemez. Bunu düşürmek MySQL yapılandırmasında yapılır ve indeksin yeniden oluşturulmasını gerektirir:

[mysqld]
innodb_ft_min_token_size = ••••••••

-- MySQL yeniden başlatıldıktan sonra:
ALTER TABLE articles DROP INDEX ft_articles_title_body;
ALTER TABLE articles ADD FULLTEXT ft_articles_title_body (title, body);

Bu proje eşiği değiştirmez; bunun yerine kısa terimlerde LIKE'a düşer ve hangi modda çalıştığını söyler. Sebebi basit: paylaşılan bir sunucuda MySQL yapılandırmasına erişiminiz olmayabilir.

Şifreyi koda yazmayın

Canlı veritabanı künyesi config.php'ye yazılmaz: o dosya depoda durur ve her dağıtımda depodaki sürümle değiştirilir. Bunun yerine yanına config.local.php koyun (.gitignore içindedir):

cp system/config.local.php.example system/config.local.php
# sonra dört satırı doldurun

Öncelik sırası: config.local.php → .env → ortam değişkeni → yerel varsayılan.

---

Kendi Projenize Eklemek

Arama katmanını başka bir tabloya (ürün, belge, kişi) taşımak için:

1 — FULLTEXT indeksini ekleyin

MATCH() içindeki sütun listesi bir indeksin sütun listesiyle birebir eşleşmelidir:

ALTER TABLE products
  ADD FULLTEXT ft_products_name_desc (name, description),
  ADD FULLTEXT ft_products_name (name);   -- öneri listesi için

İkinci indeks olmadan MATCH(name) yazamazsınız ve MySQL şunu der: Can't find FULLTEXT index matching the column list.

2 — Sorgulardaki tablo ve sütun adlarını değiştirin

handle_search() ve handle_autocomplete() içindeki üç sorgu. Yer tutucu adlandırma düzenini (:q_facet, :q_cnt, :q_sel, :q_whr) bozmayın — sebebi aşağıdaki tuzakta.

3 — Facet sütununu seçin

Bu projede category. Sizde brand, status ya da department olabilir. Facet sorgusuna kategori filtresi uygulanmaz; bu bilinçlidir.

4 — Vurgulanacak alanları belirleyin

highlight() alan bağımsızdır; hangi metni verirseniz onu işaretler. Detayda null uzunluk vererek tam metni alabilirsiniz.

Atlamayın: boolean_query() fonksiyonunu kopyalamadan AGAINST() kullanmayın. Ham girdiyi boolean moda vermek, kullanıcının yazdığı bir tire işaretinin aramayı sessizce bozmasına yeter.

---

Çı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; bu örneğe özgü her şey (arama kutusu, öneri listesi, sonuç kartları, sayfalama) assets/css/style.css içindedir.

Hazır bileşenler

Bu örneğe özgü (style.css): .cy-searchbox / __icon / __clear, .cy-ac / __cat, .cy-chip, .cy-meta / __mode / __time, .cy-result / __title / __score / __snippet, .cy-pager / .cy-page, .cy-empty-state, .cy-stats / .cy-stat, mark.

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);
}

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ı

search-autocomplete/
├── index.php                 → Arayüz. Veritabanına DOKUNMAZ; tek kart + bir modal.
├── .env.example              → Veritabanı bilgileri (isteğe bağlı) — .gitignore içinde
├── cy_search.sql             → Şema + 38 yazı (NOW() - INTERVAL) + iki FULLTEXT indeksi
├── .htaccess                 → Dizin listeleme kapalı, .sql/.md kapalı (README istisna)
│
├── system/
│   ├── config.php            → Ayarlar, PDO bağlantısı, APP_DEBUG türetimi
│   ├── config.local.php      → (siz oluşturursunuz) canlı künye — .gitignore'da
│   ├── config.local.php.example
│   ├── function.php          → CSRF, hız sınırı, Türkçe katlama, boolean sorgu, vurgulama
│   ├── ajax.php              → 4 uç nokta
│   └── .htaccess             → BEYAZ LİSTE: yalnızca ajax.php dışarıya açık
│
├── assets/
│   ├── css/
│   │   ├── cilginyazilim.css → MARKA KALIBI (projeler arası ortak — dokunmayın)
│   │   ├── style.css         → Yalnızca bu örneğe özgü stiller
│   │   └── bootstrap.min.css
│   ├── js/
│   │   ├── search.js         → Debounce, yarış koruması, klavye, URL senkronu (8 bölüm)
│   │   ├── jquery-3.7.0.js
│   │   └── bootstrap.bundle.js
│   └── images/logo.png
│
├── docs/screenshots/         → README'de kullanılan görseller
├── CHANGELOG.md
├── README.md · README.en.md
└── LICENSE                   → MIT

---

Nasıl Çalışıyor?

KULLANICI YAZIYOR: p → e → r → f → o → r
                              │
                              ▼
┌─ DEBOUNCE (200 ms) ──────────────────────────────────────────────────┐
│  clearTimeout(timer) → setTimeout(…, 200)                            │
│  10 tuş vuruşu → 1 istek                                             │
└──────────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─ autocomplete ───────────────┐  ┌─ search ─────────────────────────────┐
│ MATCH(title) AGAINST(…)      │  │ 1) facet:  GROUP BY category         │
│ ft_articles_title indeksi    │  │    (kategori filtresi UYGULANMAZ)    │
│ yalnızca BAŞLIKLAR           │  │ 2) count:  filtre UYGULANMIŞ toplam  │
│ LIMIT 7                      │  │ 3) page:   skor + LIMIT off, len     │
│                              │  │ 4) 0 sonuç → terim düşürme önerisi   │
│ ↳ seq geri döner             │  │ ↳ seq, mod, took_ms geri döner       │
└──────────────────────────────┘  └──────────────────────────────────────┘
              │                               │
              ▼                               ▼
┌─ YARIŞ KORUMASI ─────────────────────────────────────────────────────┐
│  if (res.seq < renderedSeq) return;   ← eski yanıt ATILIR            │
│  renderedSeq = res.seq;                                              │
└──────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─ ÇİZİM ──────────────────────────────────────────────────────────────┐
│  · vurgulanmış başlık ve özet  (.html() — sunucuda kaçışlanmış)      │
│  · kategori ve tarih           (esc()  — ham veri)                   │
│  · facet çipleri, sayfalama, ölçüm satırı                            │
│  · history.replaceState → ?q=…&kategori=…&sayfa=…                    │
└──────────────────────────────────────────────────────────────────────┘

Sorumluluk dağılımı

---

AJAX API Referansı

Tüm istekler system/ajax.php adresine POST ile gider ve CSRF token taşır.

search — sonuç listesi + facet

İstek: q, seq, page, category, sort

{
  "success": true,
  "seq": 7,
  "q": "performans",
  "mode": "FULLTEXT boolean",
  "sort": "alaka",
  "total": 8,
  "all_total": 8,
  "page": 1,
  "pages": 2,
  "facets": [{"category": "Veritabanı", "count": 3}, {"category": "Web", "count": 2}],
  "results": [
    {"id": 37, "title": "Mobil <mark>performans</mark>: ilk boyama süresi",
     "snippet": "… <mark>Performans</mark> bir özellik değil…",
     "category": "Mobil", "published": "31.07.2026", "score": 0.92}
  ],
  "did_you_mean": null,
  "took_ms": 48.1
}

all_total kategori filtresi uygulanmadan önceki toplamdır; "Tümü" çipinde o kullanılır. total ise filtre uygulanmış hâlidir. İkisini karıştırmak, bir kategoriye tıklandığında "Tümü (3)" gibi yanlış bir sayı gösterirdi.

Sonuç yoksa did_you_mean dolu gelir:

{"total": 0, "did_you_mean": {"q": "mysql", "total": 2}}

autocomplete — öneri listesi

İstek: q, seq

{
  "success": true, "seq": 12, "q": "perf",
  "suggestions": [
    {"id": 37, "title": "Mobil performans: ilk boyama süresi",
     "category": "Mobil",
     "html": "Mobil <mark>perf</mark>ormans: ilk boyama süresi"}
  ]
}

title ham metindir (kutuya yazılır), html vurgulanmış hâldir (listede gösterilir). İki ayrı alan olmasının sebebi budur: biri .val(), diğeri .html() ile kullanılır.

detail — tek yazı

İstek: id, q (vurgulama için)

{
  "success": true,
  "article": {
    "id": 7, "title": "SQL enjeksiyonu ve prepared statement",
    "body": "Kullanıcı verisi asla … en sık görülen <mark>güvenlik</mark> açığıdır.",
    "category": "Güvenlik", "tags": ["sql", "injection", "pdo", "guvenlik"],
    "published": "28.08.2026", "words": 34
  }
}

Gövde kırpılmaz: highlight() fonksiyonuna null uzunluk verilir, yani pencere yoktur.

stats — sayaçlar ve önerilen aramalar

{"success": true, "total": 38, "categories": 6, "newest": "28.08.2026",
 "min_len": 2, "suggested": ["performans", "guvenlik", "llm", "mysql", "arama"]}

suggested bir arama geçmişi tablosundan değil, yazıların etiketlerinden üretilir; en sık geçen sekiz etiket döner.

Çok kısa sorgu bir hata değildir

q uzunluğu MIN_QUERY_LEN altındaysa sunucu 200 ile ve too_short: true ile döner. 400 dönmez — kullanıcı henüz yazmaktadır ve tarayıcı konsolunu kırmızı hatalarla doldurmanın bir anlamı yoktur.

HTTP durum kodları

---

Veritabanı Şeması

CREATE TABLE `articles` (
  `id`           INT UNSIGNED NOT NULL AUTO_INCREMENT,
  `title`        VARCHAR(200) NOT NULL,
  `body`         TEXT NOT NULL,
  `category`     VARCHAR(60)  NOT NULL,
  `tags`         VARCHAR(255) NOT NULL DEFAULT '',
  `published_at` DATE NOT NULL,
  PRIMARY KEY (`id`),
  KEY `idx_articles_category` (`category`),
  KEY `idx_articles_published` (`published_at`),
  FULLTEXT KEY `ft_articles_title_body` (`title`, `body`),
  FULLTEXT KEY `ft_articles_title` (`title`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

---

Sık Sorulanlar

Ne zaman Elasticsearch'e geçmeliyim?

MySQL FULLTEXT şunları yapmaz: kök bulma (stemming), eş anlamlı sözlüğü, yazım denetimi ("bunu mu demek istediniz?"), coğrafi arama, çok dilli analiz zincirleri ve gerçek anlamda ölçeklenen dağıtık indeks.

Bunlara ihtiyacınız yoksa —ki çoğu panel aramasında yoktur— MySQL yeter ve ayrı bir servis işletmek zorunda kalmazsınız. Yüz binlerce belgede ve kelime bazlı aramada FULLTEXT hâlâ makul çalışır.

Geçiş sinyalleri: eş anlamlıya ihtiyaç duymaya başladığınızda, sorgu süreleri kabul edilemez olduğunda, ya da aramanın kendisi ürünün ana özelliği hâline geldiğinde.

Neden natural language modu değil boolean mod?

Tek sebep yeter: önek eşleşmesi. Canlı aramada kullanıcı henüz yazmaktadır; perfor yazdığında performans bulunmalıdır. * operatörü yalnızca boolean modda vardır.

Türkçe için ikinci bir sebep daha var: dil eklemeli olduğu için indeks, indeksin, indeksleri üç ayrı sözcüktür. indeks* üçünü de yakalar; natural language modu yakalamaz.

Bedeli: boolean mod varsayılan olarak alaka skorunu natural language kadar iyi hesaplamaz ve %50 eşiği gibi kolaylıkları yoktur. Bu örnek için doğru ödünleşim.

"ci" gibi kısa terimler neden LIKE'a düşüyor?

InnoDB'de innodb_ft_min_token_size varsayılan olarak 3'tür: daha kısa sözcükler indekse hiç girmez. ci araması boolean modda sessizce sıfır sonuç döndürür — hata yok, sadece boşluk. Kullanıcı için bu, aramanın bozuk olduğu anlamına gelir.

Bu yüzden sorgudaki en uzun sözcük 3 harften kısaysa LIKE'a düşüyoruz. LIKE indeks kullanamaz ve yavaştır; ama kısa bir terimde doğru cevap vermek, hızlı biçimde hiçbir şey dönmemekten iyidir. Hangi modun çalıştığı ekranda da yazar.

Eşiği düşürmek mümkündür ama MySQL yapılandırmasına erişim ve indeksin yeniden oluşturulmasını gerektirir (bkz. Yapılandırma).

Debounce varken yarış koruması gerçekten gerekli mi?

Evet, çünkü ikisi farklı sorunları çözer. Debounce istek sayısını azaltır; ağ gecikmesinin eşit olmasını sağlamaz.

200 ms sonra perf isteği gider. Kullanıcı yazmaya devam eder, 200 ms sonra performans isteği gider. İkinci istek 40 ms'de, birinci istek 600 ms'de dönerse ekranda perf sonuçları kalır. Debounce bunu engellemez; yalnızca daha seyrek yaşanmasını sağlar.

Kaçınılması kolay, fark edilmesi zor bir hatadır: yerelde neredeyse hiç görülmez, gerçek ağda düzenli olarak görülür.

Vurgulama neden sunucuda yapılıyor, istemcide değil?

İki sebep. Birincisi, özet penceresi zaten sunucuda kesiliyor: 900 karakterlik bir gövdeden ilk eşleşmenin çevresini almak, hangi kelimelerin arandığını bilmeyi gerektirir. İstemcide yapmak, gövdenin tamamını ağdan geçirmek demektir.

İkincisi ve daha önemlisi güvenlik: kaçışlama ile vurgulamanın sırası kritiktir (bkz. 5. karar). Bunu tek bir yerde, sunucuda doğru yapmak; her çizim noktasında istemcide tekrar doğru yapmaya çalışmaktan güvenlidir.

Önerilen aramalar nereden geliyor? Arama kaydı tutuyor musunuz?

Hayır, bir arama geçmişi tablosu yok. Öneriler yazıların etiketlerinden üretilir: en sık geçen sekiz etiket alınır.

Bu bilinçli bir tercih. Arama kaydı tutmak kişisel veri toplamaktır ve ayrı bir sorumluluk getirir; ayrıca yeni kurulmuş bir sistemde geçmiş boştur ve öneri kutusu haftalarca boş kalır. İçerikten türeyen öneriler ilk günden anlamlıdır.

Facet sayıları neden kategori filtresi uygulanmadan hesaplanıyor?

Çünkü facet'in işi "buradan nereye gidebilirim?" sorusunu cevaplamaktır. "Web" kategorisine tıkladığınızda diğer kategorilerin sayısı 0 görünseydi, oradan başka bir kategoriye geçemezdiniz — tek çıkış yolu filtreyi tamamen temizlemek olurdu.

Bu yüzden iki ayrı sayı vardır: all_total (filtresiz toplam, "Tümü" çipinde) ve total (filtreli toplam, ölçüm satırında).

---

Canlı Ortama Alırken

• [ ] APP_DEBUG zaten ortamdan türetiliyor — yine de canlıda false olduğunu doğrulayın
• [ ] system/config.local.php oluşturun; künyeyi config.php'ye yazmayın
• [ ] Veritabanı için root yerine sınırlı yetkili (yalnızca SELECT) bir kullanıcı oluşturun — bu uygulama hiçbir şey yazmaz
• [ ] FULLTEXT indekslerinin gerçekten oluştuğunu doğrulayın: SHOW INDEX FROM articles
• [ ] Ölçüm satırını (mod ve ms) göstermek istemiyorsanız renderResults() içinden kaldırın
• [ ] Hız sınırı kovalarını trafiğinize göre gözden geçirin; otomatik tamamlama beklediğinizden sık çağrılır
• [ ] HTTPS kullanın; session.cookie_secure = 1 ve session.cookie_httponly = 1 ayarlayın
• [ ] Tablo büyüdükçe EXPLAIN ile sorgu planını kontrol edin; facet GROUP BY'ı ilk yavaşlayan yerdir
• [ ] Nginx kullanıyorsanız .htaccess çalışmaz; .sql ve .md erişimini sunucu yapılandırmasından kapatın:

```nginx
location ~* \.(sql|log|ini|bak)$ { deny all; }
```

---

Sorun Giderme

---

Yol Haritası

• [ ] Eş anlamlı sözlüğü (arama ↔ search, veritabanı ↔ database)
• [ ] Yazım denetimi ve "bunu mu demek istediniz?" (trigram benzerliği)
• [ ] Tarih aralığı filtresi ve çoklu kategori seçimi
• [ ] Sonsuz kaydırma seçeneği (anahtar tabanlı sayfalama ile)
• [ ] Arama sonuçlarının CSV / JSON dışa aktarımı
• [ ] Başlığı gövdeden ağırlıklı sayan bileşik skor (iki MATCH toplamı)
• [ ] PHPUnit testleri (boolean_query, tr_fold, highlight, should_use_like)
• [ ] 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/search-autocomplete

Katkı ölçütleri

• Kod açıklamalı olsun. Bu projenin temel amacı öğretmek; yorumsuz kod PR'ı geri döner.
• Ham girdiyi AGAINST() içine koymayın. boolean_query() bu projenin güvenlik sınırıdır.
• Vurgulama sırasını değiştirmeyin. Önce işaretle, sonra kaçışla, en son etikete çevir — ters sıra XSS'e ya da bozuk HTML'e açılır.
• Yarış korumasını kaldırmayın. Yerelde hiç görülmeyen, üretimde düzenli görülen bir hatayı kapatır.
• Tasarım değişikliklerini style.css üzerinden yapın; cilginyazilim.css markaya aittir ve diğer projelerle ortaktır.

---

Lisans

MIT — ticari kullanım dahil serbesttir.