PHPackages                             ngunenc/nsql - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. ngunenc/nsql

ActiveLibrary

ngunenc/nsql
============

Modern PHP PDO veritabanı kütüphanesi (nsql) v1.5

1.5.0(3mo ago)03MITPHPPHP >=8.0CI failing

Since May 23Pushed 3mo ago1 watchersCompare

[ Source](https://github.com/ngunenc/nsql)[ Packagist](https://packagist.org/packages/ngunenc/nsql)[ RSS](/packages/ngunenc-nsql/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (4)Versions (11)Used By (0)

📚 nsql - Modern PHP PDO Veritabanı Kütüphanesi v1.5.0
=====================================================

[](#-nsql---modern-php-pdo-veritabanı-kütüphanesi-v150)

**nsql**, PHP 8.0+ için tasarlanmış, modern, güvenli ve yüksek performanslı bir veritabanı kütüphanesidir. PDO tabanlı bu kütüphane, gelişmiş özellikler ve optimizasyonlarla güçlendirilmiştir.

> **🚀 v1.5.0 Yeni Özellikler**: Thread-safe connection pool, LFU cache algoritması, per-table TTL, cache warming, identifier quoting, güvenli IP/HTTPS tespiti, gelişmiş exception handling ve memory leak düzeltmeleri!

🌟 Özellikler
------------

[](#-özellikler)

### Core Özellikler

[](#core-özellikler)

- PDO tabanlı veritabanı soyutlama
- Akıcı (fluent) sorgu arayüzü
- Otomatik bağlantı yönetimi
- Transaction desteği
- Migration sistemi

### Güvenlik

[](#güvenlik)

- SQL injection koruması (PDO prepared statements, identifier quoting)
- XSS ve CSRF koruma mekanizmaları
- Güvenli oturum yönetimi
- Rate limiting ve DDoS koruması
- Hassas veri filtreleme
- Thread-safe connection pool (file-based lock)
- Güvenli IP/HTTPS tespiti (proxy/load balancer desteği)

### Performans (v1.5.0 Optimizasyonları)

[](#performans-v150-optimizasyonları)

- **Connection Pool**: Thread-safe bağlantı yönetimi (file-based lock, circular buffer)
- **Memory Management**: Gelişmiş bellek yönetimi (circular buffer, agresif cleanup)
- **Cache Performance**: LFU algoritması desteği, dinamik cache size, per-table TTL
- **Cache Warming**: Önceden yükleme stratejileri ile performans artışı
- **Query Analyzer**: Analiz sonuçları cache'leme (100 analiz sonucu)
- **Generator Desteği**: Memory leak düzeltmeleri ile daha güvenli büyük veri işleme
- **Otomatik Optimizasyon**: Akıllı chunk size ayarlaması

### Geliştirici Araçları

[](#geliştirici-araçları)

- Detaylı debug sistemi
- Kapsamlı hata yönetimi
- PHPUnit test desteği
- PSR-12 kod standardı uyumluluğu
- PHPStan static analysis desteği
- PHP CS Fixer kod formatlama
- Composer script'leri ile otomatik test

📋 Kurulum
---------

[](#-kurulum)

### Sistem Gereksinimleri

[](#sistem-gereksinimleri)

- **PHP**: 8.0 veya üstü
- **PDO**: PHP PDO eklentisi
- **MySQL**: 5.7.8+ veya MariaDB 10.2+
- **OpenSSL**: Şifreleme özellikleri için
- **JSON**: Yapılandırma dosyaları için

### Composer ile Kurulum

[](#composer-ile-kurulum)

**⚠️ Önemli**: Paket henüz Packagist'te yayınlanmadığı için, GitHub repository'yi direkt kullanmanız gerekiyor.

#### Yöntem 1: Repository ile (Önerilen)

[](#yöntem-1-repository-ile-önerilen)

Projenizin `composer.json` dosyasına şunu ekleyin:

```
{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/ngunenc/nsql.git"
        }
    ],
    "require": {
        "ngunenc/nsql": "^1.5.0"
    }
}
```

Sonra:

```
composer require ngunenc/nsql:^1.5.0
```

#### Yöntem 2: Tek Komutla

[](#yöntem-2-tek-komutla)

```
composer require ngunenc/nsql:^1.5.0 --repository='{"type":"vcs","url":"https://github.com/ngunenc/nsql.git"}'
```

> 📝 **Packagist'e Eklendikten Sonra**: Normal `composer require ngunenc/nsql` komutu çalışacak.
>
> 📖 **Detaylı Kurulum Rehberi**: [INSTALLATION.md](INSTALLATION.md) dosyasına bakın.

### Manuel Kurulum

[](#manuel-kurulum)

```
git clone https://github.com/ngunenc/nsql.git
cd nsql
composer install
```

### Geliştirme Ortamı Kurulumu

[](#geliştirme-ortamı-kurulumu)

```
# Bağımlılıkları yükle
composer install

# Test veritabanını kur
composer test:setup

# Testleri çalıştır
composer test

# Kod kalitesini kontrol et
composer lint
composer stan
```

### Yapılandırma

[](#yapılandırma)

1. `env.example` dosyasını `.env` olarak kopyalayın:

```
cp env.example .env
```

2. `.env` dosyasındaki değerleri güncelleyin:

```
db_host=localhost
db_name=your_database
db_user=your_username
db_pass=your_password
DEBUG_MODE=false
```

📚 Dokümantasyon
---------------

[](#-dokümantasyon)

- [📘 Kullanım Klavuzu](docs/kullanim-klavuzu.md) - Temel kullanım ve kurulum
- [📖 Teknik Detaylar](docs/teknik-detay.md) - Mimari ve teknik bilgiler
- [📚 API Referansı](docs/api-reference.md) - Kapsamlı API dokümantasyonu
- [📝 Örnekler](docs/examples.md) - Detaylı kullanım örnekleri
- [📋 Değişiklik Günlüğü](CHANGELOG.md) - Sürüm geçmişi ve değişiklikler

### Kısa Özet ve Temel Kullanım

[](#kısa-özet-ve-temel-kullanım)

#### Veritabanı Bağlantısı

[](#veritabanı-bağlantısı)

```
use nsql\database\nsql;

// .env dosyasından yapılandırma ile (önerilen)
$db = new nsql();

// veya özel parametrelerle
$db = new nsql(
    host: 'localhost',
    db: 'veritabani_adi',
    user: 'kullanici',
    pass: 'sifre',
    charset: 'utf8mb4',
    debug: true
);
```

#### Veri Sorgulama

[](#veri-sorgulama)

```
// Tek satır getirme
$kullanici = $db->get_row(
    "SELECT * FROM kullanicilar WHERE id = :id",
    ['id' => 1]
);

// Çoklu satır getirme
$kullanicilar = $db->get_results("SELECT * FROM kullanicilar");

// Generator ile büyük veri setleri
foreach ($db->get_yield("SELECT * FROM buyuk_tablo") as $row) {
    // Hafıza dostu işlemler...
}
```

#### Veri Manipülasyonu

[](#veri-manipülasyonu)

```
// Ekleme
$db->insert("INSERT INTO kullanicilar (ad, email) VALUES (:ad, :email)", [
    'ad' => 'Ahmet',
    'email' => 'ahmet@ornek.com'
]);
$son_id = $db->insert_id();

// Güncelleme
$db->update("UPDATE kullanicilar SET ad = :ad WHERE id = :id", [
    'ad' => 'Mehmet',
    'id' => 1
]);

// Silme
$db->delete("DELETE FROM kullanicilar WHERE id = :id", ['id' => 1]);
```

---

### Örnek Uygulama Akışı

[](#örnek-uygulama-akışı)

Aşağıda, nsql kütüphanesinin bir web uygulamasında kullanıcı ekleme, listeleme ve güncelleme işlemleri için nasıl kullanılabileceğine dair tam bir akış örneği verilmiştir:

```
use nsql\database\nsql;

// Bağlantı
$db = new nsql();

// 1. Kullanıcı ekleme
$db->insert("INSERT INTO kullanicilar (ad, email) VALUES (:ad, :email)", [
    'ad' => 'Ayşe',
    'email' => 'ayse@ornek.com'
]);
$yeni_id = $db->insert_id();

// 2. Tüm kullanıcıları listeleme
$kullanicilar = $db->get_results("SELECT * FROM kullanicilar");
foreach ($kullanicilar as $kullanici) {
    echo $kullanici->ad . " - " . $kullanici->email . "";
}

// 3. Kullanıcı güncelleme
$db->update("UPDATE kullanicilar SET ad = :ad WHERE id = :id", [
    'ad' => 'Ayşe Yılmaz',
    'id' => $yeni_id
]);

// 4. Tek bir kullanıcıyı getirme
$ayse = $db->get_row("SELECT * FROM kullanicilar WHERE id = :id", ['id' => $yeni_id]);
echo "Güncellenen kullanıcı: " . $ayse->ad;

// 5. Kullanıcı silme
$db->delete("DELETE FROM kullanicilar WHERE id = :id", ['id' => $yeni_id]);
```

Bu örnek, nsql ile tipik bir CRUD (Create, Read, Update, Delete) akışının nasıl gerçekleştirileceğini göstermektedir. Tüm işlemler güvenli parametre bağlama ile yapılır ve hata yönetimi için try-catch blokları eklenebilir.

Kütüphanenin daha fazla özelliği ve gelişmiş kullanım örnekleri için [docs/kullanim-klavuzu.md](docs/kullanim-klavuzu.md) dosyasını inceleyebilirsiniz.

🧪 Test ve Kalite
----------------

[](#-test-ve-kalite)

### Test Çalıştırma

[](#test-çalıştırma)

```
# Tüm testleri çalıştır
composer test

# Coverage raporu ile
composer test -- --coverage-html coverage/html
```

### Kod Kalitesi

[](#kod-kalitesi)

```
# PHPStan static analysis
composer stan

# PHP CodeSniffer (PSR-12)
composer lint

# PHP CS Fixer
composer fix
```

### CI/CD

[](#cicd)

Proje GitHub Actions ile otomatik test edilir:

- PHP 8.0, 8.1, 8.2, 8.3 desteği
- Ubuntu ve Windows ortamları
- MySQL 8.0 test veritabanı
- Coverage raporları

📂 Proje Yapısı
--------------

[](#-proje-yapısı)

```
nsql/
├── src/
│   └── database/
│       ├── config.php               # Yapılandırma yönetimi
│       ├── connection_pool.php      # Bağlantı havuzu yönetimi
│       ├── migration.php           # Migration arayüzü
│       ├── migration_manager.php   # Migration yönetimi
│       ├── nsql.php               # Ana PDO wrapper sınıfı
│       ├── query_builder.php      # SQL sorgu oluşturucu
│       ├── migrations/            # Migration dosyaları
│       ├── schema/               # Şema validasyonu (v1.3.0)
│       ├── security/             # Güvenlik bileşenleri
│       │   ├── audit_logger.php   # Güvenlik log sistemi
│       │   ├── encryption.php     # Şifreleme işlemleri
│       │   ├── rate_limiter.php   # İstek sınırlama
│       │   ├── security_manager.php # Güvenlik yönetimi
│       │   └── sensitive_data_filter.php # Hassas veri filtresi
│       ├── seeds/                # Seed dosyaları
│       ├── templates/            # View şablonları
│       └── traits/               # Trait sınıfları
│           ├── cache_trait.php    # Önbellekleme işlemleri
│           ├── connection_trait.php # Bağlantı yönetimi
│           ├── debug_trait.php     # Hata ayıklama
│           ├── query_parameter_trait.php # Sorgu parametreleri
│           ├── statement_cache_trait.php # Statement önbellekleme
│           └── transaction_trait.php # Transaction yönetimi
├── tests/                      # Test dosyaları
├── .github/workflows/          # GitHub Actions CI
├── storage/logs/              # Log dosyaları
├── composer.json             # Composer yapılandırması
├── phpunit.xml               # PHPUnit yapılandırması
├── phpstan.neon              # PHPStan yapılandırması
├── .php_cs                   # PHP CS Fixer yapılandırması
├── env.example               # Yapılandırma örneği
└── README.md                # Dokümantasyon

```

### Sınıf Yapısı

[](#sınıf-yapısı)

#### Temel Bileşenler

[](#temel-bileşenler)

- **nsql**: PDO wrapper ve temel veritabanı işlemleri
- **config**: Yapılandırma yönetimi ve ortam değişkenleri
- **connection\_pool**: Veritabanı bağlantı havuzu ve optimizasyon
- **query\_builder**: Akıcı arayüz ile SQL sorgu oluşturma

#### Güvenlik Bileşenleri

[](#güvenlik-bileşenleri)

- **security\_manager**: Merkezi güvenlik yönetimi
- **encryption**: Veri şifreleme ve çözme işlemleri
- **rate\_limiter**: İstek sınırlama ve DDoS koruması
- **audit\_logger**: Güvenlik olayları loglama
- **sensitive\_data\_filter**: Hassas veri filtreleme

#### Veritabanı Yönetimi

[](#veritabanı-yönetimi)

- **migration\_manager**: Veritabanı şema yönetimi
- **migration**: Migration arayüzü tanımı
- **seeds**: Test ve başlangıç verisi yönetimi

🌟 Özellikler
------------

[](#-özellikler-1)

### Core Özellikler

[](#core-özellikler-1)

- PDO tabanlı veritabanı soyutlama
- Akıcı (fluent) sorgu arayüzü
- Otomatik bağlantı yönetimi
- Transaction desteği
- Migration sistemi

### Güvenlik

[](#güvenlik-1)

- SQL injection koruması (PDO prepared statements)
- XSS ve CSRF koruma mekanizmaları
- Güvenli oturum yönetimi ve cookie kontrolü
- Rate limiting ve DDoS koruması
- Hassas veri filtreleme ve şifreleme
- Güvenlik olay loglaması

### Performans

[](#performans)

- Connection Pool ile bağlantı yönetimi
- Statement Cache (LRU algoritması)
- Query Cache sistemi
- Generator desteği ile düşük bellek kullanımı
- Otomatik garbage collection

### Geliştirici Araçları

[](#geliştirici-araçları-1)

- Detaylı debug sistemi
- Kapsamlı hata yönetimi
- Komut satırı araçları (planlanan)
- PHPUnit test desteği
- PSR-12 kod standardı uyumluluğu

🔧 Kurulum
---------

[](#-kurulum-1)

### Sistem Gereksinimleri

[](#sistem-gereksinimleri-1)

- PHP 8.0+
- PDO PHP Eklentisi
- JSON PHP Eklentisi
- OpenSSL PHP Eklentisi (şifreleme için)
- MySQL 5.7.8+ veya MariaDB 10.2+

### Composer ile Kurulum

[](#composer-ile-kurulum-1)

```
composer require ngunenc/nsql
```

### Manuel Kurulum

[](#manuel-kurulum-1)

1. Projeyi klonlayın:

```
git clone https://github.com/ngunenc/nsql.git
```

2. Bağımlılıkları yükleyin:

```
composer install
```

3. Yapılandırma dosyasını oluşturun:

```
cp .env.example .env
```

4. Veritabanı ayarlarını yapılandırın:

```
db_host=localhost
db_name=database_name
db_user=database_user
db_pass=database_password
DB_CHARSET=utf8mb4

# Cache ayarları
QUERY_CACHE_ENABLED=true
STATEMENT_CACHE_LIMIT=100

# Güvenlik ayarları
RATE_LIMIT_ENABLED=true
ENCRYPTION_KEY=your-secure-key
```

📖 Kullanım
----------

[](#-kullanım)

### Temel Bağlantı

[](#temel-bağlantı)

```
use nsql\database\nsql;

// Basit bağlantı
$db = new nsql();

// veya özel parametrelerle
$db = new nsql(
    host: 'localhost',
    db: 'veritabanı',
    user: 'kullanici',
    pass: 'sifre',
    charset: 'utf8mb4',
    debug: true
);
```

### Veri Sorgulama

[](#veri-sorgulama-1)

```
// Tek satır getirme
$kullanici = $db->get_row("SELECT * FROM kullanicilar WHERE id = :id", ['id' => 1]);

// Çoklu satır getirme
$kullanicilar = $db->get_results("SELECT * FROM kullanicilar");

// Generator ile büyük veri setleri
foreach ($db->get_yield("SELECT * FROM buyuk_tablo") as $row) {
    // Hafıza dostu işlemler
}
```

### Veri Manipülasyonu

[](#veri-manipülasyonu-1)

```
// Ekleme
$db->insert("INSERT INTO kullanicilar (ad, email) VALUES (:ad, :email)", [
    'ad' => 'Ahmet',
    'email' => 'ahmet@ornek.com'
]);
$son_id = $db->insert_id();

// Güncelleme
$db->update("UPDATE kullanicilar SET ad = :ad WHERE id = :id", [
    'ad' => 'Mehmet',
    'id' => 1
]);

// Silme
$db->delete("DELETE FROM kullanicilar WHERE id = :id", ['id' => 1]);
```

### Transaction Kullanımı

[](#transaction-kullanımı)

```
try {
    $db->begin();

    // İşlemler...

    $db->commit();
} catch (Exception $e) {
    $db->rollback();
    // Hata yönetimi
}
```

🛡️ Güvenlik
-----------

[](#️-güvenlik)

### CSRF Koruması

[](#csrf-koruması)

```
// Token üretme
$token = \nsql\database\security\session_manager::get_csrf_token();

// Token doğrulama
if (nsql::validate_csrf($_POST['token'] ?? '')) {
    // Güvenli işlem
}
```

### XSS Koruması

[](#xss-koruması)

```
$guvenli_metin = nsql::escape_html($kullanici_girisi);
```

🚀 Performans
------------

[](#-performans)

### Statement Cache

[](#statement-cache)

Sık kullanılan sorgular için otomatik önbellekleme yapılır. LRU (Least Recently Used) ve LFU (Least Frequently Used) algoritmaları desteklenir. Memory kullanımına göre dinamik cache size ayarlaması yapılır.

### Connection Pool

[](#connection-pool)

Bağlantılar havuzda tutulur ve gerektiğinde yeniden kullanılır, böylece performans artışı sağlanır.

### Debug Modu

[](#debug-modu)

```
$db = new nsql(debug: true);

// Sorgu çalıştır
$db->get_results("SELECT * FROM tablo");

// Debug bilgilerini görüntüle
$db->debug();
```

📝 Örnekler
----------

[](#-örnekler)

### Güvenli Oturum Yönetimi

[](#güvenli-oturum-yönetimi)

```
// Güvenli oturum başlatma
nsql::secure_session_start();

// Oturum ID'sini yenileme
nsql::regenerateSessionId();
```

### Hata Yönetimi

[](#hata-yönetimi)

```
$db->safe_execute(function() use ($db) {
    return $db->get_results("SELECT * FROM tablo");
}, "Veriler alınırken bir hata oluştu");
```

---

### Gerçek Hayat Kullanım Senaryoları

[](#gerçek-hayat-kullanım-senaryoları)

#### Migration Kullanımı

[](#migration-kullanımı)

Gerçek projelerde veritabanı şemasını güncellemek için migration modülünü kullanabilirsiniz:

```
use nsql\database\migration_manager;

$migration = new migration_manager();
$migration->runMigrations(); // Tüm migration dosyalarını uygular
```

#### Seed Kullanımı

[](#seed-kullanımı)

Test ve demo verisi eklemek için seed modülünü kullanabilirsiniz:

```
use nsql\database\seeds\user_seeder;

$seeder = new user_seeder();
$seeder->run(); // Örnek kullanıcı verilerini ekler
```

#### Güvenlik Modülleri

[](#güvenlik-modülleri)

Gerçek uygulamalarda rate limiting ve veri şifreleme gibi güvenlik modüllerini entegre edebilirsiniz:

```
use nsql\database\security\rate_limiter;

$limiter = new rate_limiter();
if (!$limiter->check('user_ip')) {
    die('Çok fazla istek!');
}

use nsql\database\security\encryption;

$enc = new encryption();
$crypted = $enc->encrypt('gizli veri');
$plain = $enc->decrypt($crypted);
```

#### Cache Kullanımı

[](#cache-kullanımı)

Sorgu önbellekleme ile performansı artırmak için:

```
use nsql\database\nsql;

$db = new nsql();
// Cache yapılandırması .env/config üzerinden yönetilir
$sonuclar = $db->get_results("SELECT * FROM tablo");
// İstatistikleri görüntüleme
$stats = $db->get_all_cache_stats();
```

Bu örnekler, nsql kütüphanesinin migration, seed, güvenlik ve cache gibi modüllerinin gerçek bir projede nasıl kullanılabileceğini göstermektedir.

📜 Lisans
--------

[](#-lisans)

Bu proje MIT lisansı altında lisanslanmıştır. Detaylar için [LICENSE](LICENSE) dosyasına bakınız. DEBUG\_MODE=false

Loglama ayarları
================

[](#loglama-ayarları)

LOG\_FILE=error\_log.txt STATEMENT\_CACHE\_LIMIT=100

```

---

### ⚙️ **Kullanım**

#### Veritabanı Bağlantısı

nsql sınıfını yapılandırma dosyasından veya özel parametrelerle başlatabilirsiniz:

```php
// .env dosyasından yapılandırma ile
require_once 'pdo.php';
$db = new nsql();

// veya özel parametrelerle
$db = new nsql(
    host: 'localhost',
    db: 'veritabanı_adi',
    user: 'kullanici',
    pass: 'sifre',
    debug: true // Debug modu için
);

```

📦 Temel Kullanım
----------------

[](#-temel-kullanım)

### Satır Ekleme (Insert)

[](#satır-ekleme-insert)

```
$db->insert("INSERT INTO users (name, email) VALUES ('Ali', 'ali@example.com')");
echo $db->insert_id(); // Son eklenen ID
```

### Satır Güncelleme (Update)

[](#satır-güncelleme-update)

```
$db->update("UPDATE users SET name = 'Mehmet' WHERE id = 1");
```

### Satır Silme (Delete)

[](#satır-silme-delete)

```
$db->delete("DELETE FROM users WHERE id = 3");
```

### Tek Satır Getir (get\_row)

[](#tek-satır-getir-get_row)

```
$user = $db->get_row("SELECT * FROM users WHERE id = 1");
echo $user->name;
```

### Çoklu Satır Getir (get\_results)

[](#çoklu-satır-getir-get_results)

```
$users = $db->get_results("SELECT * FROM users WHERE status = :status", [
    'status' => 'active'
]);
foreach ($users as $user) {
    echo $user->email;
}
```

### Büyük Veri Setleri İçin Generator (get\_yield)

[](#büyük-veri-setleri-i̇çin-generator-get_yield)

Memory dostu yaklaşım ile büyük veri setlerini işlemek için:

```
foreach ($db->get_yield("SELECT * FROM big_table", []) as $row) {
    // Her satır tek tek işlenir, bellek şişmez
    process($row);
}
```

### Query Cache Kullanımı

[](#query-cache-kullanımı)

Query Cache özelliği, sık kullanılan sorguların sonuçlarını önbellekte tutarak performansı artırır:

```
// Cache otomatik olarak aktiftir (.env'de QUERY_CACHE_ENABLED=true ise)
$users = $db->get_results("SELECT * FROM users WHERE status = 'active'");
// İkinci çağrıda sonuç cache'den gelir
$users = $db->get_results("SELECT * FROM users WHERE status = 'active'");

// Cache'i manuel temizleme
// Cache istatistikleri
$stats = $db->get_all_cache_stats();
```

### Connection Pool Kullanımı

[](#connection-pool-kullanımı)

Connection Pool, veritabanı bağlantılarını yönetir ve performansı artırır:

```
// Pool istatistiklerini görüntüleme
$stats = nsql::get_pool_stats();
print_r($stats);

// Tüm istatistikleri görüntüleme (v1.4 Yeni!)
$all_stats = $db->get_all_stats();
print_r($allStats);

// Cache istatistikleri
$cache_stats = $db->get_all_cache_stats();
echo "Query Cache Hit Rate: " . $cacheStats['query_cache']['hit_rate'] . "%\n";
echo "Statement Cache Hit Rate: " . $cacheStats['statement_cache']['hit_rate'] . "%\n";

// Query Analyzer istatistikleri
$analyzer_stats = $db->get_query_analyzer_stats();
echo "Analysis Cache Hit Rate: " . $analyzerStats['cache_hit_rate'] . "%\n";

// Memory istatistikleri
$memory_stats = $db->get_memory_stats();
echo "Current Memory: " . $memoryStats['current_usage'] . " bytes\n";
echo "Peak Memory: " . $memoryStats['peak_usage'] . " bytes\n";

// Pool otomatik olarak yönetilir, manuel müdahale gerekmez
// Min ve max bağlantı sayıları .env dosyasından ayarlanır
```

### Debug ve Loglama

[](#debug-ve-loglama)

```
// Debug modunda detaylı sorgu bilgilerini görüntüle
$db->debug();

// Güvenli hata yönetimi
$result = $db->safe_execute(function() use ($db) {
    return $db->get_row("SELECT * FROM users WHERE id = :id", ['id' => 1]);
}, 'Kullanıcı bilgileri alınamadı');
```

### Güvenlik Fonksiyonları

[](#güvenlik-fonksiyonları)

```
// Güvenli oturum başlatma
nsql::secure_session_start();

// CSRF koruması
$token = \nsql\database\security\session_manager::get_csrf_token();
if (nsql::validate_csrf($_POST['token'] ?? '')) {
    // Form işleme
}

// XSS koruması
echo nsql::escape_html($userInput);
```

### Transaction İşlemleri

[](#transaction-i̇şlemleri)

```
try {
    $db->begin();

    // Sipariş oluştur
    $db->insert(
        "INSERT INTO orders (user_id, total_amount, status) VALUES (:user_id, :total, :status)",
        [
            'user_id' => $userId,
            'total' => $totalAmount,
            'status' => 'pending'
        ]
    );
    $orderId = $db->insert_id();

    // Sipariş ürünlerini ekle
    foreach ($items as $item) {
        $db->insert(
            "INSERT INTO order_items (order_id, product_id, quantity, price)
             VALUES (:order_id, :product_id, :quantity, :price)",
            [
                'order_id' => $orderId,
                'product_id' => $item->id,
                'quantity' => $item->quantity,
                'price' => $item->price
            ]
        );

        // Stok güncelle
        $db->update(
            "UPDATE products
             SET stock = stock - :quantity
             WHERE id = :id AND stock >= :quantity",
            [
                'id' => $item->id,
                'quantity' => $item->quantity
            ]
        );
    }

    // Tüm işlemler başarılı, kaydet
    $db->commit();

} catch (Exception $e) {
    // Hata durumunda geri al
    $db->rollback();
    throw $e;
}
```

---

### 📝 Parametreli Sorgu Kullanımı (Önerilen Güvenli Yöntem)

[](#-parametreli-sorgu-kullanımı-önerilen-güvenli-yöntem)

Tüm sorgularda parametre bağlama kullanmanız önerilir. Aşağıda insert, update ve delete işlemleri için güvenli örnekler verilmiştir:

```
// Güvenli INSERT
$db->insert("INSERT INTO users (name, email) VALUES (:name, :email)", [
    'name' => 'Ali',
    'email' => 'ali@example.com'
]);
echo $db->insert_id();

// Güvenli UPDATE
$db->update("UPDATE users SET name = :name WHERE id = :id", [
    'name' => 'Mehmet',
    'id' => 1
]);

// Güvenli DELETE
$db->delete("DELETE FROM users WHERE id = :id", [
    'id' => 3
]);
```

---

🚀 Performans Özellikleri
------------------------

[](#-performans-özellikleri)

### Connection Pool

[](#connection-pool-1)

- Verimli bağlantı yönetimi
- Minimum ve maksimum bağlantı sayısı kontrolü
- Otomatik bağlantı sağlığı kontrolü
- İstatistik izleme ve raporlama

### Query Cache

[](#query-cache)

- Sorgu sonuçları önbellekleme
- Yapılandırılabilir önbellek süresi
- Otomatik önbellek temizleme
- Boyut limitli LRU önbellekleme

### Statement Cache

[](#statement-cache-1)

- Hazırlanmış sorguları önbellekleme
- LRU (Least Recently Used) ve LFU (Least Frequently Used) algoritmaları
- Dinamik cache size (memory kullanımına göre otomatik ayarlama)
- Otomatik boyut yönetimi
- Performans optimizasyonu

### Memory Management

[](#memory-management)

- Generator kullanarak büyük veri setleri için bellek optimizasyonu
- Önbellek boyut limitleri
- Otomatik temizleme mekanizmaları

🔒 Güvenlik ve Performans
------------------------

[](#-güvenlik-ve-performans)

### Güvenlik Özellikleri

[](#güvenlik-özellikleri)

- **SQL Injection Koruması**
    - PDO prepared statements
    - LIMIT/OFFSET parametreleştirme
    - Identifier quoting (table/column name'ler backtick ile quote edilir)
    - Parametre tip kontrolü ve validasyonu
    - Otomatik parametre bağlama
- **XSS ve CSRF Koruması**
    - HTML çıktı temizleme (`escape_html()`)
    - Token tabanlı CSRF koruması
    - Otomatik token yenileme
- **Oturum Güvenliği**
    - Güvenli session başlatma ve yönetimi
    - Session fixation koruması
    - HttpOnly, Secure ve SameSite cookie ayarları
    - Otomatik session ID rotasyonu
    - Güvenli IP/HTTPS tespiti (proxy/load balancer desteği)
- **Thread Safety**
    - Connection pool file-based lock mekanizması
    - Cache invalidation race condition koruması

### Performans Optimizasyonları

[](#performans-optimizasyonları)

- **Bağlantı Yönetimi**
    - Connection Pool ile verimli kaynak kullanımı
    - Otomatik bağlantı sağlığı kontrolü
    - Bağlantı sayısı optimizasyonu
- **Önbellekleme Sistemleri**
    - Statement Cache (LRU ve LFU algoritmaları, dinamik cache size)
    - Query Cache ile sorgu sonuçları önbellekleme (per-table TTL, cache warming)
    - Thread-safe cache invalidation
    - Otomatik önbellek temizleme
- **Bellek Optimizasyonu**
    - Generator desteği ile düşük bellek kullanımı (memory leak düzeltmeleri)
    - Circular buffer ile verimli memory yönetimi
    - Büyük veri setleri için streaming
    - Agresif cleanup ve otomatik garbage collection

### Hata Yönetimi

[](#hata-yönetimi-1)

- Üretim/Geliştirme modu ayrımı
- Detaylı hata loglama
- Güvenli hata mesajları
- Exception wrapping (getPrevious() ile gerçek exception'a erişim)
- get\_last\_exception() metodu ile hata takibi
- try-catch wrapper

---

🏗️ Mimari Özellikler
--------------------

[](#️-mimari-özellikler)

### Katmanlı Mimari

[](#katmanlı-mimari)

```
   [Kullanıcı]
       |
   [index.php / uygulama]
       |
   [nsql (src/database/nsql.php)]
       |
   +-------------------+-------------------+
   |                   |                   |
[ConnectionPool]   [QueryBuilder]   [SecurityManager]
       |                   |                   |
   [PDO]              [SQL]              [Güvenlik modülleri]

```

- **config Katmanı**: Yapılandırma yönetimi (`config.php`)
- **Bağlantı Katmanı**: Veritabanı bağlantı havuzu yönetimi (`ConnectionPool.php`)
- **Core Katmanı**: Ana veritabanı işlemleri (`nsql.php`)
- **Güvenlik Katmanı**: XSS, CSRF ve Session güvenliği
- **Cache Katmanı**: Query ve Statement önbellekleme

### Tasarım Prensipleri

[](#tasarım-prensipleri)

- SOLID prensipleri
- DRY (Don't Repeat Yourself)
- KISS (Keep It Simple, Stupid)
- Separation of Concerns

### Genişletilebilirlik

[](#genişletilebilirlik)

- Plugin sistemi desteği
- Olay (Event) sistemi
- Custom handler desteği

📊 Sürüm Matrisi ve Uyumluluk
----------------------------

[](#-sürüm-matrisi-ve-uyumluluk)

### PHP Sürüm Uyumluluğu

[](#php-sürüm-uyumluluğu)

nsql SürümüPHP MinimumPHP MaksimumNotlar1.0.x8.0.08.2.xTam destek1.1.x8.0.08.3.xTam destek### Veritabanı Uyumluluğu

[](#veritabanı-uyumluluğu)

VeritabanıMinimum SürümÖnerilen SürümMySQL5.7.88.0+MariaDB10.210.6+---

### 🧠 Yeni Özellikler

[](#-yeni-özellikler)

⚡ Benchmark Sonuçları (v1.5.0)
------------------------------

[](#-benchmark-sonuçları-v150)

Yerel ortam ölçümleri, `benchmarks/` betikleri ile alınmıştır (MySQL, PHP 8.2, Windows). Değerler yaklaşıktır ve ortalama tek çalıştırma sonuçlarını temsil eder.

```
1) Küçük/Orta SELECT (nsql vs PDO, bench_users tablosu)
   case         nsql_ms   pdo_ms   count
   small_1k     ~3.10     ~1.94    1000
   medium_10k   ~12.84    ~12.38   10000

Yorum: Küçük setlerde nsql’in ek güvenlik/katman maliyeti küçük bir fark yaratır; orta setlerde fark kapanır.

2) Generator vs Array (get_yield vs get_results)
   mode        time_ms   mem_peak
   generator   ~4.6      ~4 MB
   array       ~41.9     ~16 MB

Yorum: Büyük veri setlerinde get_yield belirgin şekilde daha hızlı ve bellek dostu.

3) Cache Hit/Miss (aynı sorgu iki kez)
   phase    time_ms   hit_rate
   first    ~5.8      ~50%
   second   ~0.39     ~50%

Yorum: İkinci çağrıda cache sayesinde ciddi hızlanma elde edilir. TTL ve limit değerleri workload’a göre ayarlanmalıdır.

```

Benchmark’ları çalıştırmak için:

```
php benchmarks/select_small_vs_large.php
php benchmarks/iterators_vs_array.php
php benchmarks/cache_hit_miss.php
```

### SQL Sabitlerini Otomatik Parametreye Çevirme

[](#sql-sabitlerini-otomatik-parametreye-çevirme)

```
// Otomatik olarak :param1 ve :param2 parametrelerine çevrilir
$db->get_row("SELECT * FROM users WHERE id = 5 AND status = 'active'");
```

Bu özellik sayesinde doğrudan SQL içerisine sabit veri yazabilir, `nsql` sınıfı bu değerleri otomatik olarak `PDO` parametrelerine çevirir.

### Statement Cache Desteği

[](#statement-cache-desteği)

Aynı SQL sorgusu birden fazla kez çalıştırıldığında `prepare()` işlemi tekrar yapılmaz, bu da performansı artırır.

### Gelişmiş `debug()` Metodu

[](#gelişmiş-debug-metodu)

Hata oluştuğunda sorguyu ve parametreleri detaylı biçimde HTML formatında gösterir.

```
$db->debug(); // Hatalı sorgularda otomatik olarak çalışır
```

---

### 🔍 Debug ve Hata Yönetimi

[](#-debug-ve-hata-yönetimi)

#### Hata Kodları ve Çözümleri

[](#hata-kodları-ve-çözümleri)

Hata KoduAçıklamaÇözüm2006MySQL server has gone awayBağlantı otomatik yenilenir2013Lost connection to MySQL serverBağlantı otomatik yenilenir1045Access deniedVeritabanı kimlik bilgilerini kontrol edin1049Unknown databaseVeritabanının varlığını kontrol edin1146Table doesn't existTablo adını ve veritabanını kontrol edin1062Duplicate entryBenzersiz alan çakışması#### Debug Modu

[](#debug-modu-1)

Debug modunda aşağıdaki bilgileri görüntüleyebilirsiniz:

```
// Debug modu ile başlatma
$db = new nsql(debug: true);

// veya .env dosyasında
DEBUG_MODE=true

// Sorgu detaylarını görüntüleme
$db->debug();
```

Debug çıktısı şunları içerir:

- SQL sorgusu ve parametreleri
- Hata mesajları (varsa)
- Sonuç verisi (tablo formatında)
- Query execution detayları

#### Güvenli Hata Yönetimi

[](#güvenli-hata-yönetimi)

```
// Hata yönetimi için safe_execute kullanımı
$result = $db->safe_execute(function() use ($db) {
    return $db->get_row(
        "SELECT * FROM users WHERE id = :id",
        ['id' => 1]
    );
}, 'Kullanıcı bilgileri alınamadı.');

// Üretim ortamında: Genel hata mesajı gösterir
// Geliştirme ortamında: Detaylı hata mesajı gösterir
```

#### Otomatik Loglama

[](#otomatik-loglama)

Tüm SQL sorguları ve hatalar otomatik olarak log dosyasına kaydedilir:

```
# .env dosyasında log yapılandırması
LOG_FILE=error_log.txt
```

Log formatı:

```
[2025-05-21 10:30:15] SQL Sorgusu: SELECT * FROM users WHERE id = '1'
Parametreler: {"id": 1}

```

---

### 🧪 Test

[](#-test)

### Unit Tests

[](#unit-tests)

Testler PHPUnit ile yazılmıştır. Test sınıfları `tests` dizini altında bulunmaktadır.

#### Test Sınıfı Örneği

[](#test-sınıfı-örneği)

```
class NsqlTest extends TestCase
{
    private ?nsql $db = null;

    protected function setUp(): void
    {
        $this->db = new nsql(
            host: 'localhost',
            db: 'test_db',
            user: 'test_user',
            pass: 'test_pass'
        );
    }

    public function testCRUD()
    {
        // Insert test
        $id = $this->db->insert(
            "INSERT INTO test_table (name) VALUES (:name)",
            ['name' => 'Test Name']
        );
        $this->assertIsInt($id);

        // Read test
        $row = $this->db->get_row(
            "SELECT * FROM test_table WHERE id = :id",
            ['id' => $id]
        );
        $this->assertEquals('Test Name', $row->name);
    }

    // Edge case örneği: Boş veri ekleme
    public function testInsertEmptyName()
    {
        $id = $this->db->insert(
            "INSERT INTO test_table (name) VALUES (:name)",
            ['name' => '']
        );
        $this->assertIsInt($id);
    }

    // Entegrasyon testi örneği: Transaction
    public function testTransactionRollback()
    {
        $this->db->begin();
        $id = $this->db->insert(
            "INSERT INTO test_table (name) VALUES (:name)",
            ['name' => 'Rollback Test']
        );
        $this->db->rollback();
        $row = $this->db->get_row(
            "SELECT * FROM test_table WHERE id = :id",
            ['id' => $id]
        );
        $this->assertNull($row);
    }
}
```

#### Test Çalıştırma

[](#test-çalıştırma-1)

```
# Tüm testleri çalıştır
./vendor/bin/phpunit tests

# Belirli bir test sınıfını çalıştır
./vendor/bin/phpunit tests/NsqlTest.php

# Belirli bir test metodunu çalıştır
./vendor/bin/phpunit --filter testCRUD tests/NsqlTest.php
```

### Test Kapsamı ve İyi Uygulamalar

[](#test-kapsamı-ve-i̇yi-uygulamalar)

- CRUD işlemlerinin yanı sıra edge case ve hata senaryoları için testler yazın (ör. boş veri, hatalı parametre, bağlantı hatası).
- Transaction, rollback, cache, güvenlik ve migration gibi modüller için entegrasyon testleri ekleyin.
- Testlerde assert fonksiyonlarını kullanarak beklenen sonuçları doğrulayın.
- Her yeni fonksiyon veya modül için birim test eklemeyi unutmayın.
- Test veritabanı ile gerçek veritabanını ayırın, test ortamında dummy veri kullanın.
- Kodunuzu test etmeden production ortamına geçmeyin.

---

### 🔒 Oturum (Session) ve Cookie Güvenliği

[](#-oturum-session-ve-cookie-güvenliği)

Oturum başlatırken ve cookie ayarlarında güvenlik için aşağıdaki fonksiyonu kullanabilirsiniz:

```
// Oturum başlatmadan önce çağırın
nsql::secure_session_start();
```

Bu fonksiyon;

- Oturum çerezini `HttpOnly`, `Secure` ve `SameSite=Lax` olarak ayarlar.
- HTTPS kullanıyorsanız otomatik olarak `secure` flag'ini aktif eder.
- Session fixation saldırılarına karşı ilk oturumda session ID'yi yeniler.

Oturum ID'sini manuel olarak yenilemek için:

```
nsql::regenerateSessionId();
```

---

### 🛡️ XSS ve CSRF Koruması

[](#️-xss-ve-csrf-koruması)

#### XSS (Cross-Site Scripting) Koruması

[](#xss-cross-site-scripting-koruması)

Kütüphanede yer alan `nsql::escape_html()` fonksiyonu ile kullanıcıdan gelen verileri HTML'ye basmadan önce güvenle kaçışlayabilirsiniz:

```
// HTML çıktısı için güvenli şekilde kullanın
echo nsql::escape_html($kullanici->isim);
```

#### CSRF (Cross-Site Request Forgery) Koruması

[](#csrf-cross-site-request-forgery-koruması)

Formlarınızda CSRF koruması için aşağıdaki fonksiyonları kullanabilirsiniz:

**Token üretimi ve formda kullanımı:**

```