WordPress Debug Modunu Aktif Etme: Geliştirici Araçları

Tarafındankomut
0 Comments

WordPress ile çalışan her geliştirici ya da sistem yöneticisi, er ya da geç şu durumla karşılaşır: Site çalışmıyor, beyaz ekran var, ama neden olduğuna dair hiçbir fikrin yok. İşte tam bu noktada WordPress’in debug sistemi hayat kurtarıcı oluyor. Debug modunu doğru yapılandırmak, sorunları dakikalar içinde çözmenizi sağlarken, yanlış yapılandırmak production ortamında ciddi güvenlik açıkları yaratabilir. Bu yazıda WordPress debug araçlarını baştan sona ele alacağız; sadece aktif etmeyi değil, nasıl akıllıca kullanacağınızı da anlatacağız.

WordPress Debug Sistemi Nedir ve Neden Önemlidir?

WordPress, PHP tabanlı bir platform olduğu için olası hatalar, uyarılar ve bildirimler PHP’nin hata raporlama mekanizmasıyla yönetilir. Ancak WordPress bu mekanizmanın üstüne kendi debug katmanını eklemiştir. Bu katman sayesinde:

  • PHP hatalarını ve uyarılarını kontrol altında tutabilirsiniz
  • Hataları doğrudan ekranda göstermek yerine log dosyasına yönlendirebilirsiniz
  • Script ve stil dosyalarının minify edilmemiş versiyonlarını yükleyebilirsiniz
  • Veritabanı sorgularını takip edebilirsiniz
  • Eklenti ve tema geliştiricileri için özel hata mesajlarını etkinleştirebilirsiniz

Tüm bu ayarlar wp-config.php dosyasında tanımlı sabitler aracılığıyla yönetilir. Ama biz bu yazıda işi bir adım öteye taşıyarak bu kontrollerin bir kısmını functions.php üzerinden nasıl yönetebileceğinizi de göstereceğiz.

Temel Debug Sabitleri: wp-config.php

Her şeyin temeli wp-config.php dosyasında atılır. Bu dosyayı sunucunuza SSH ile bağlanarak ya da FTP üzerinden düzenleyebilirsiniz. WordPress kurulumunun kök dizininde bulunur.

# wp-config.php dosyasını nano ile düzenlemek için
nano /var/www/html/wp-config.php

# Ya da vim tercih ederseniz
vim /var/www/html/wp-config.php

Dosya içinde / That's all, stop editing! Happy publishing. / satırının üstüne debug sabitlerini eklemeniz gerekir. Temel yapılandırma şu şekildedir:

# wp-config.php içindeki debug sabitleri
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'SCRIPT_DEBUG', true );
define( 'SAVEQUERIES', true );

Bu sabitlerin ne anlama geldiğini tek tek açıklayalım:

  • WP_DEBUG: Ana debug anahtarıdır. true yapılmadan diğer debug sabitleri işe yaramaz
  • WP_DEBUG_LOG: Hataları /wp-content/debug.log dosyasına kaydeder
  • WP_DEBUG_DISPLAY: Hataları ekranda gösterip göstermeyeceğini belirler; production’da kesinlikle false olmalı
  • SCRIPT_DEBUG: WordPress’in birleştirilmiş ve sıkıştırılmış JS/CSS dosyaları yerine orijinal dosyaları kullanmasını sağlar
  • SAVEQUERIES: Tüm veritabanı sorgularını kaydeder; performans testleri için çok değerlidir

functions.php ile Debug Kontrolü

wp-config.php dosyasına dokunmak istemediğiniz durumlar olabilir. Örneğin paylaşımlı hosting kullanıyorsanız ya da wp-config.php‘ye erişiminiz kısıtlıysa, functions.php üzerinden bazı debug kontrollerini yapabilirsiniz. Ayrıca tema bazlı debug ayarları yapmak için bu yaklaşım çok işe yarar.

Ortam Bazlı Debug Fonksiyonu

Gerçek dünyada en sık karşılaşılan problem şudur: Geliştirici local ortamda debug açık çalışır, kodu production’a alır ve debug’ı kapatmayı unutur. Bu durumu önlemek için ortam algılayan bir debug yöneticisi yazabiliriz:

<?php
/**
 * Ortam bazlı debug yöneticisi
 * functions.php dosyasına ekleyin
 */
function custom_debug_manager() {
    // Mevcut sunucu adresini al
    $server_name = isset( $_SERVER['SERVER_NAME'] ) ? $_SERVER['SERVER_NAME'] : '';
    
    // Local geliştirme ortamlarını tanımla
    $local_environments = array(
        'localhost',
        '127.0.0.1',
        '.local',
        '.test',
        '.dev'
    );
    
    $is_local = false;
    
    foreach ( $local_environments as $env ) {
        if ( strpos( $server_name, $env ) !== false ) {
            $is_local = true;
            break;
        }
    }
    
    // Local ortamda hata raporlamayı aç
    if ( $is_local ) {
        error_reporting( E_ALL );
        ini_set( 'display_errors', 1 );
        ini_set( 'display_startup_errors', 1 );
    } else {
        // Production'da hata raporlamayı kapat
        error_reporting( 0 );
        ini_set( 'display_errors', 0 );
    }
}

add_action( 'init', 'custom_debug_manager' );

Debug Log Fonksiyonu

WordPress’in varsayılan error_log() fonksiyonu yetersiz kalabilir. Daha zengin bilgi içeren özel bir log fonksiyonu yazalım:

<?php
/**
 * Gelişmiş debug log fonksiyonu
 * 
 * @param mixed  $data     Loglanacak veri (string, array, object)
 * @param string $label    Log satırı için etiket
 * @param string $log_file Özel log dosyası yolu (opsiyonel)
 */
function custom_debug_log( $data, $label = '', $log_file = '' ) {
    
    // Debug modu kapalıysa çalıştırma
    if ( ! defined( 'WP_DEBUG' ) || ! WP_DEBUG ) {
        return;
    }
    
    // Log dosyasını belirle
    if ( empty( $log_file ) ) {
        $log_file = WP_CONTENT_DIR . '/debug.log';
    }
    
    // Zaman damgası
    $timestamp = date( 'Y-m-d H:i:s' );
    
    // Veriyi okunabilir formata çevir
    if ( is_array( $data ) || is_object( $data ) ) {
        $output = print_r( $data, true );
    } else {
        $output = $data;
    }
    
    // Etiket varsa ekle
    $label_text = ! empty( $label ) ? "[{$label}] " : '';
    
    // Log satırını oluştur
    $log_entry = "[{$timestamp}] {$label_text}{$output}" . PHP_EOL;
    
    // Dosyaya yaz
    error_log( $log_entry, 3, $log_file );
}

Bu fonksiyonu kullanmak çok basit:

<?php
// Basit string log
custom_debug_log( 'Kullanıcı giriş yaptı', 'AUTH' );

// Array log
$user_data = array(
    'id'    => 42,
    'email' => '[email protected]',
    'role'  => 'editor'
);
custom_debug_log( $user_data, 'USER_DATA' );

// WooCommerce sipariş debug örneği
function debug_woocommerce_order( $order_id ) {
    $order = wc_get_order( $order_id );
    
    if ( ! $order ) {
        custom_debug_log( "Sipariş bulunamadı: {$order_id}", 'WC_ORDER_ERROR' );
        return;
    }
    
    custom_debug_log( array(
        'order_id'     => $order_id,
        'status'       => $order->get_status(),
        'total'        => $order->get_total(),
        'customer_id'  => $order->get_customer_id(),
        'items_count'  => count( $order->get_items() )
    ), 'WC_ORDER_DEBUG' );
}

add_action( 'woocommerce_order_status_changed', 'debug_woocommerce_order', 10, 1 );

Admin Panelinde Debug Bilgisi Gösterme

Bazen hata ayıklama bilgilerini sadece admin kullanıcılarına göstermek istersiniz. Ziyaretçilere hata mesajı göstermeden, admin olarak siteyi gezinirken anlık debug bilgisi almak için şu yaklaşımı kullanabilirsiniz:

<?php
/**
 * Admin kullanıcıları için debug toolbar
 * Sadece WP_DEBUG true iken ve admin kullanıcılar için çalışır
 */
function admin_debug_toolbar() {
    
    // Sadece debug modunda ve admin kullanıcılar için göster
    if ( ! defined( 'WP_DEBUG' ) || ! WP_DEBUG ) {
        return;
    }
    
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    
    global $wpdb;
    
    $query_count    = count( $wpdb->queries );
    $memory_usage   = size_format( memory_get_usage( true ) );
    $memory_limit   = ini_get( 'memory_limit' );
    $peak_memory    = size_format( memory_get_peak_usage( true ) );
    $load_time      = timer_stop( 0, 3 );
    
    echo '<div id="custom-debug-bar" style="
        position: fixed;
        bottom: 0;
        left: 0;
        right: 0;
        background: #1d2327;
        color: #72aee6;
        font-family: monospace;
        font-size: 12px;
        padding: 8px 15px;
        z-index: 999999;
        border-top: 2px solid #2271b1;
        display: flex;
        gap: 20px;
    ">';
    
    echo '<span><strong style="color:#fff;">DEBUG BAR</strong></span>';
    echo '<span>Sorgular: <strong>' . $query_count . '</strong></span>';
    echo '<span>Bellek: <strong>' . $memory_usage . '</strong> / ' . $memory_limit . '</span>';
    echo '<span>Peak: <strong>' . $peak_memory . '</strong></span>';
    echo '<span>Yüklenme: <strong>' . $load_time . 's</strong></span>';
    echo '<span>PHP: <strong>' . PHP_VERSION . '</strong></span>';
    
    echo '</div>';
}

add_action( 'wp_footer', 'admin_debug_toolbar' );
add_action( 'admin_footer', 'admin_debug_toolbar' );

Debug Log Dosyasını Yönetme

Debug log dosyası zamanla çok büyüyebilir. Özellikle yoğun trafikli sitelerde debug.log dosyasının birkaç GB’a ulaştığını gördüm. Bunu yönetmek için log rotasyon mekanizması ekleyelim:

<?php
/**
 * Debug log rotasyon yöneticisi
 * Günlük çalışacak şekilde wp-cron ile entegre edilir
 */
function rotate_debug_log() {
    
    $log_file = WP_CONTENT_DIR . '/debug.log';
    $max_size  = 5 * 1024 * 1024; // 5 MB limit
    
    if ( ! file_exists( $log_file ) ) {
        return;
    }
    
    $file_size = filesize( $log_file );
    
    if ( $file_size < $max_size ) {
        return;
    }
    
    // Eski log dosyalarını sıkıştır ve yeniden adlandır
    $backup_file = WP_CONTENT_DIR . '/debug-' . date( 'Y-m-d-His' ) . '.log';
    
    rename( $log_file, $backup_file );
    
    // Eski yedekleri temizle (7 günden eski olanlar)
    $log_dir  = WP_CONTENT_DIR . '/';
    $old_logs = glob( $log_dir . 'debug-*.log' );
    
    if ( $old_logs ) {
        $cutoff_time = time() - ( 7 * 24 * 60 * 60 );
        
        foreach ( $old_logs as $old_log ) {
            if ( filemtime( $old_log ) < $cutoff_time ) {
                unlink( $old_log );
                custom_debug_log( "Eski log silindi: {$old_log}", 'LOG_ROTATION' );
            }
        }
    }
}

// Günlük cron görevi olarak ekle
if ( ! wp_next_scheduled( 'rotate_debug_log_cron' ) ) {
    wp_schedule_event( time(), 'daily', 'rotate_debug_log_cron' );
}

add_action( 'rotate_debug_log_cron', 'rotate_debug_log' );

Veritabanı Sorgularını Debug Etme

SAVEQUERIES sabiti aktif olduğunda tüm DB sorguları hafızada tutulur. Bu verileri analiz etmek için şu fonksiyonu kullanabilirsiniz:

<?php
/**
 * Yavaş veritabanı sorgularını tespit et ve logla
 * SAVEQUERIES sabitinin true olması gerekir
 * 
 * @param float $threshold Eşik değer (saniye cinsinden)
 */
function detect_slow_queries( $threshold = 0.05 ) {
    
    // Gerekli sabitler kontrolü
    if ( ! defined( 'SAVEQUERIES' ) || ! SAVEQUERIES ) {
        return;
    }
    
    if ( ! defined( 'WP_DEBUG' ) || ! WP_DEBUG ) {
        return;
    }
    
    global $wpdb;
    
    if ( empty( $wpdb->queries ) ) {
        return;
    }
    
    $slow_queries   = array();
    $total_time     = 0;
    $total_queries  = count( $wpdb->queries );
    
    foreach ( $wpdb->queries as $query ) {
        $query_time  = $query[1]; // Sorgu süresi
        $total_time += $query_time;
        
        if ( $query_time > $threshold ) {
            $slow_queries[] = array(
                'sql'      => $query[0],
                'time'     => round( $query_time, 5 ),
                'caller'   => $query[2]
            );
        }
    }
    
    if ( ! empty( $slow_queries ) ) {
        custom_debug_log( array(
            'total_queries'    => $total_queries,
            'total_time'       => round( $total_time, 5 ),
            'slow_query_count' => count( $slow_queries ),
            'threshold'        => $threshold,
            'slow_queries'     => $slow_queries
        ), 'SLOW_QUERIES' );
    }
}

add_action( 'shutdown', function() {
    detect_slow_queries( 0.05 ); // 50ms'den uzun sorguları logla
});

Gerçek Dünya Senaryosu: WooCommerce Ödeme Hatası Debug

Müşterilerden en çok aldığım destek taleplerinden biri WooCommerce ödeme hatalarıdır. “Ödeme yapılamıyor” şikayeti geldiğinde ne yapacağınızı bilmiyorsanız saatler kaybedebilirsiniz. İşte bu senaryoda kullandığım debug yaklaşımı:

<?php
/**
 * WooCommerce ödeme gateway debug
 * Ödeme hatalarını detaylı loglar
 */
function debug_wc_payment_errors( $order_id, $transaction_id, $message ) {
    
    if ( ! defined( 'WP_DEBUG' ) || ! WP_DEBUG ) {
        return;
    }
    
    $order = wc_get_order( $order_id );
    
    if ( ! $order ) {
        return;
    }
    
    $debug_data = array(
        'order_id'       => $order_id,
        'transaction_id' => $transaction_id,
        'message'        => $message,
        'gateway'        => $order->get_payment_method(),
        'gateway_title'  => $order->get_payment_method_title(),
        'order_status'   => $order->get_status(),
        'order_total'    => $order->get_total(),
        'currency'       => $order->get_currency(),
        'customer_ip'    => $order->get_customer_ip_address(),
        'user_agent'     => $order->get_customer_user_agent(),
        'billing_country'=> $order->get_billing_country(),
        'created_via'    => $order->get_created_via(),
        'timestamp'      => current_time( 'mysql' )
    );
    
    custom_debug_log( $debug_data, 'WC_PAYMENT_ERROR' );
}

add_action( 'woocommerce_payment_complete', function( $order_id ) {
    custom_debug_log( "Ödeme tamamlandı: #{$order_id}", 'WC_PAYMENT_SUCCESS' );
}, 10, 1 );

add_action( 'woocommerce_order_status_failed', function( $order_id ) {
    debug_wc_payment_errors( $order_id, 'N/A', 'Sipariş durumu failed olarak değişti' );
}, 10, 1 );

Debug Logunu Terminal’den Takip Etme

Debug log dosyası oluştuktan sonra, anlık takip için terminal üzerinden çalışmak çok daha verimlidir. Sunucunuza SSH ile bağlandıktan sonra şu komutları kullanabilirsiniz:

# Debug logunu canlı takip et
tail -f /var/www/html/wp-content/debug.log

# Son 100 satırı göster
tail -n 100 /var/www/html/wp-content/debug.log

# Sadece hata satırlarını filtrele
tail -f /var/www/html/wp-content/debug.log | grep "PHP Fatal"

# WooCommerce ödeme hatalarını filtrele
tail -f /var/www/html/wp-content/debug.log | grep "WC_PAYMENT"

# Log dosyasının boyutunu kontrol et
du -sh /var/www/html/wp-content/debug.log

# Log dosyasını temizle (içeriği sil, dosyayı bırak)
truncate -s 0 /var/www/html/wp-content/debug.log

Debug Log Dosyasını Güvenceye Alma

Debug log dosyası içindeki bilgiler (kullanıcı verileri, veritabanı sorguları, sistem yolları) son derece hassastır. Bu dosyaya web üzerinden erişimi engellemeniz şarttır:

# .htaccess ile debug.log'u koru (Apache)
# /wp-content/.htaccess dosyasına ekleyin

<Files "debug.log">
    Order Allow,Deny
    Deny from all
</Files>

Nginx kullanıyorsanız server bloğunuza şunu ekleyin:

# Nginx konfigürasyonuna ekleyin
location ~* /wp-content/debug.log {
    deny all;
    return 404;
}

# Aynı zamanda debug.log'un farklı bir dizine taşınmasını da düşünebilirsiniz
# wp-config.php içinde:
# define( 'WP_DEBUG_LOG', '/home/username/logs/wp-debug.log' );

WP_DEBUG_LOG sabitine true yerine özel bir dosya yolu vermek, log dosyasını web erişiminden tamamen uzak bir dizine almanızı sağlar. Bu hem daha güvenli hem de daha yönetilebilir bir yaklaşımdır.

Production’da Debug: Dikkat Edilmesi Gerekenler

Sysadmin olarak şunu defalarca yaşadım: Geliştirici “neden çalışmıyor” diye soruyor, sunucuya bakıyorum, WP_DEBUG_DISPLAY true ve tüm hata mesajları ziyaretçilere görünüyor. Bu hem güvenlik açığı hem de son derece kötü bir kullanıcı deneyimi.

Production ortamı için doğru yapılandırma şöyledir:

  • WP_DEBUG: İdeal olarak false olmalı. Eğer production’da sorun araştırıyorsanız geçici olarak true yapıp işiniz bitince false‘a alın
  • WP_DEBUG_DISPLAY: Kesinlikle false. Hata mesajları hiçbir zaman ekranda görünmemeli
  • WP_DEBUG_LOG: Sorun araştırırken true, normal zamanlarda false yapabilirsiniz
  • SAVEQUERIES: Production’da kesinlikle false. Bellek tüketimini ciddi oranda artırır
  • SCRIPT_DEBUG: Production’da false. Aksi halde minified dosyalar yerine ham dosyalar yüklenir, bu performansı düşürür

Sonuç

WordPress debug sistemi, doğru kullanıldığında hem geliştirme hem de sorun giderme süreçlerini dramatik biçimde hızlandırır. wp-config.php üzerindeki temel sabitleri, functions.php ile yazacağınız özel debug fonksiyonları ve terminal araçlarını birleştirerek güçlü bir hata ayıklama altyapısı kurabilirsiniz.

Özetlemek gerekirse temel prensip şudur: Geliştirme ortamında her şeyi açık tutun, production’da her şeyi kapalı tutun. Ortam algılayan fonksiyonlar yazarak bu geçişi otomatik hale getirmeniz, en sık yapılan hataların önüne geçecektir. Debug log dosyasını düzenli izleyin, büyümesine izin vermeyin ve web üzerinden erişimini mutlaka engelleyin.

WooCommerce gibi karmaşık sistemlerde özelleştirilmiş debug fonksiyonları yazmak, saatlerinizi kurtaracaktır. “Site çalışmıyor” diye gelen bir destek talebini, iyi kurgulanmış bir log sistemiyle dakikalar içinde çözebilmek, hem sizin hem de müşterinizin hayatını kolaylaştırır.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir