## Canlı Arama ve Otomatik Tamamlama
#### PHP PDO · MySQL FULLTEXT · AJAX · Bootstrap 5 · Çılgın Yazılım Tasarım Kalıbı
**Yazarken arayan, ne bulduğunu ve nasıl bulduğunu söyleyen bir arama kutusu.**
[](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/search-autocomplete/) · [Kaynak Kütüphanesi](https://cilginyazilim.com/kutuphane/php-search-autocomplete) · [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
---
### 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:
| Mod | Sözdizimi | Ne yapar |
|-----|-----------|----------|
| Natural language | `AGAINST('yapay zeka')` | Kelimeleri VEYA'lar, skora göre sıralar |
| **Boolean** | `AGAINST('+yapay* +zeka*' IN BOOLEAN MODE)` | Operatör ve **önek eşleşmesi** destekler |
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:
```php
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:
```js
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 `I`nın küçüğü `ı`dır. İkincisi daha sinsi ve arayanı uzun süre uğraştırır:
```php
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 **birebir**dir:
```php
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**:
```php
// YANLIŞ: önce kaçışla, sonra ekle
$safe = htmlspecialchars($text);
$safe = str_replace($word, '' . $word . '', $safe);
```
Metinde `&` geçtiğinde kaçışlanmış hâli `&` olur. Kullanıcı `amp` aratırsa vurgulama tam o varlığın ortasına girer:
```
& → & ← bozuk HTML, ekranda ham "&"
```
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
```php
$out = str_replace(["\x00", "\x01"], ['', ''], 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?
search — sonuç listesi + facetautocomplete — öneri listesidetail — tek yazıstats — sayaçlar ve önerilen aramalar
**[cilginyazilim.com](https://cilginyazilim.com)** tarafından ❤ ile geliştirildi
## Sık Sorulan Sorular
### Ne zaman Elasticsearch gerekir, MySQL FULLTEXT nereye kadar yeter?
MySQL FULLTEXT kök bulma, eş anlamlı sözlüğü, yazım denetimi, coğrafi arama ve dağıtık indeks sunmaz. Bunlara ihtiyacınız yoksa — ç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şlamak, sorgu sürelerinin kabul edilemez olması, ya da aramanın ürünün ana özelliği hâline gelmesi.
### Neden natural language modu değil boolean mod kullanılıyor?
Tek sebep yeter: önek eşleşmesi. Canlı aramada kullanıcı henüz yazmaktadır ve "perfor" yazdığında "performans" bulunmalıdır; yıldız 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 ve indeksleri üç ayrı sözcüktür ve natural language modu bunları bağlamaz. Bedeli, boolean modun alaka skorunu natural language kadar iyi hesaplamaması ve yüzde elli eşiği gibi kolaylıklara sahip olmamasıdır.
### İki harflik terimler neden bulunamıyor?
InnoDB'de innodb_ft_min_token_size varsayılan olarak üçtür: daha kısa sözcükler indekse hiç girmez ve boolean modda sessizce sıfır sonuç döner. Kullanıcı için bu, aramanın bozuk olduğu anlamına gelir. Bu yüzden uygulama sorgudaki en uzun sözcük üç harften kısaysa LIKE yoluna düşer; yavaştır ama doğru cevap verir ve hangi modda çalıştığını ekranda söyler. Eşiği düşürmek mümkündür ama MySQL yapılandırmasına erişim ve indeksin yeniden oluşturulmasını gerektirir.
### Debounce varken yarış koruması gerçekten gerekli mi?
Evet, çünkü ikisi farklı sorunları çözer. Debounce istek sayısını azaltır ama ağ gecikmesinin eşit olmasını sağlamaz. "perf" isteği gider, kullanıcı yazmaya devam eder, "performans" isteği gider; ikinci istek kırk milisaniyede, birinci istek altı yüz milisaniyede dönerse ekranda "perf" sonuçları kalır. 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ürmesidir; karar istemcide verilir çünkü "en son hangi isteği gönderdim" bilgisi yalnızca orada vardır.
### Türkçe arama neden ayrı bir çaba gerektiriyor?
İki ayrı yerde sorun çıkar. Bulmak MySQL'in işidir ve utf8mb4_unicode_ci karşılaştırması ü ile u, İ ile i katlamasını yapar. Vurgulamak ise PHP'nin işidir ve orada iki tuzak vardır: birincisi mb_strtolower büyük I harfini i yapar ama Türkçede I'nın küçüğü ı'dır; ikincisi ve daha sinsisi, mb_strtolower büyük İ harfini iki kod noktasına çevirir (i artı birleştirici nokta). Vurgulama konumları karakter indisine dayandığı için katlanmış metnin uzunluğu değiştiğinde bütün işaretler kayar. Bu yüzden birebir kendi eşleme tablomuzu kullanıyoruz.
### Vurgulama neden sunucuda yapılıyor ve sırası neden önemli?
Özet penceresi zaten sunucuda kesiliyor: dokuz yüz karakterlik bir gövdeden ilk eşleşmenin çevresini almak, hangi kelimelerin arandığını bilmeyi gerektirir. Sıra ise güvenlik meselesidir. Önce kaçışlayıp sonra mark etiketi eklemek HTML varlıklarını bozar: metinde ve işareti geçtiğinde kaçışlanmış hâli ampersand-amp-noktalı virgül olur ve kullanıcı "amp" aratırsa vurgulama tam o varlığın ortasına girer. Doğru sıra üç adımdır: ham metinde ayraçla işaretle, tamamını kaçışla, en son ayraçları etikete çevir. Böylece çıktıdaki tek HTML etiketi kodun koyduğu olur.
---
Kaynak: [Canlı Arama ve Otomatik Tamamlama](https://cilginyazilim.com/kutuphane/php-search-autocomplete)