JekCMS Hata Ayıklama: Error Log, Xdebug ve Profiling

Hata Ayıklama Araç Seti

Production'da sabah 2'de bir şey bozulduğunda hızla teşhis edip düzeltmeniz gerekir. jekcms için hata ayıklama araç setimizin üç katmanı var: istisnaları yakalamak için PHP hata logu, karmaşık mantıkta adım adım ilerlemek için Xdebug ve performans darboğazlarını bulmak için sorgu zamanlaması.

PHP Hata Log Yapılandırması

jekcms hata loglamasını ortama göre, doğrudan config/config.php içinde yapılandırır:

// Production: hataları logla, asla gösterme
error_reporting(E_ALL & ~E_NOTICE & ~E_DEPRECATED);
ini_set('display_errors', 0);
ini_set('log_errors', 1);
ini_set('error_log', LOGS_PATH . '/php-errors.log');

// Geliştirme (DEBUG_MODE): göster ve logla
error_reporting(E_ALL);
ini_set('display_errors', 1);

Bunun üzerine kurulu özel bir loglama katmanı yoktur — jekcms düz PHP error_log() kullanır ve logs/php-errors.log dosyasına yazar. Bu dosya doğrudan web erişiminden korunur. Bu bilinçli olarak basittir: log döndürme servisi yok, öğrenilmesi gereken özel bir log biçimi yok, zaten nasıl okuyup takip edeceğinizi bildiğiniz standart PHP hata logu var.

VS Code ile Xdebug Kurulumu

Xdebug standart PHP hata ayıklama uzantısıdır ve jekcms ile tıpkı herhangi bir PHP koduyla çalışacağı gibi çalışır — kurulumda jekcms'e özgü hiçbir şey yoktur:

; php.ini
[xdebug]
zend_extension=xdebug
xdebug.mode=debug,profile
xdebug.start_with_request=trigger
xdebug.client_port=9003
xdebug.client_host=127.0.0.1

VS Code'da PHP Debug uzantısını kurun, "Listen for Xdebug" için bir başlatma yapılandırması ekleyin, PHP dosyalarınıza breakpoint koyun ve XDEBUG_TRIGGER çerezi ya da sorgu parametresiyle hata ayıklamayı tetikleyin.

Adım hata ayıklama, "bu yazı neden yanlış kategoriyi gösteriyor?" gibi sorular için paha biçilmezdir. Yazının sorgulandığı yere bir breakpoint koyun, adım adım ilerleyin, her satırda değişkenleri inceleyin ve mantığın beklediğinizden tam olarak nerede saptığını bulun.

Yavaş Sorguları Bulmak

jekcms'in Database sınıfı, prepare/execute çağrısının etrafında microtime(true) ile her sorguyu zamanlar. Bu dahili zamanlamanın hata ayıklama için verdiğinden fazlasını, production'da yavaş sorgulara görünürlük olarak istiyorsanız, basit bir desen sorgu çağrılarını sarmalayıp seçtiğiniz eşiğin üzerindeki her şeyi düz error_log() ile loglamaktır:

$start = microtime(true);
$stmt = $db->query($sql, $params);
$duration = microtime(true) - $start;

if ($duration > 0.5) { // eşiği sitenize göre ayarlayın
    error_log(sprintf(
        '[SLOW QUERY] %.3fs: %s',
        $duration,
        $sql
    ));
}

Bu, doğrudan aynı logs/php-errors.log dosyasına yazar — ayrı bir log dosyası yok, özel bir loglama sınıfı yok, yalnızca grep'leyebileceğiniz net bir önekle error_log().

Yaygın Hata Kalıpları

• 500 Dahili Sunucu Hatası: Genellikle PHP sözdizimi hatası ya da fatal exception. Önce logs/php-errors.log'u kontrol edin.
• Headers Already Sent: header() çağrısından ya da session_start()'tan önce HTML çıktısı. POST işlemesini herhangi bir çıktıdan önce taşıyın.
• CSRF Token Uyuşmazlığı: Oturum süresi doldu ya da tarayıcı geri düğmesi. Formu tekrar açtığınızda token'ı yeniden üretin.
• Girişten Sonra Oturum Kaybı: Siteler arası oturum çakışması. Aynı sunucuda birden fazla jekcms kurulumu çalıştırıyorsanız, oturum adının site başına benzersiz olduğunu kontrol edin.
• Görseller Yüklenmiyor: Dosya izinlerini (dizinler için 755, dosyalar için 644) ve veritabanındaki uploads yolunun çift uploads/ ön eki almadığını kontrol edin.

Production İzleme

logs/php-errors.log'u düzenli kontrol etmek, kullanıcılar bildirmeden önce sorunları yakalar. Basit bir yaklaşım, günlüğün son 24 saatini WARNING seviyesinin üzerindeki her şey için tarayan ve bir şey bulursa size e-posta gönderen küçük bir betiktir — cron görevi olarak, ya da barındırmanız gerçek cron erişimi vermiyorsa jekcms'in kendi sözde-cron mekanizması üzerinden zamanlanabilir. Bu yerleşik bir jekcms özelliği değildir; herhangi bir production sitesi için yazmaya değer beş dakikalık bir betiktir.