PHP Hata Raporlamayı Yönetme (display_errors ve log)

PHP ile çalışan bir sitede karşılaşabileceğiniz en can sıkıcı iki durum vardır. Birincisi, tarayıcıda ziyaretçilerin gözü önünde beliren Fatal error: Uncaught Error... satırları; ikincisi ise ekranda hiçbir şey göstermeden bembeyaz kalan, hiç ipucu vermeyen "beyaz ölüm ekranı". İkisi de aslında aynı madalyonun iki yüzüdür ve ikisinin de çözümü PHP'nin hata raporlama davranışını doğru yapılandırmaktan geçer. Bu davranışı belirleyen üç ana ayar vardır: display_errors, error_reporting ve log_errors. Bu üçünü doğru kurduğunuzda, hatalar geliştirme sırasında size net biçimde görünür, canlı sitede ise ziyaretçiden gizlenip sunucuda bir günlük dosyasına yazılır.

Bu rehberde, kıdemli bir sistem yöneticisinin bir müşteriye anlatacağı sadelikte, PHP hata raporlamasının nasıl çalıştığını, üretim ile geliştirme ortamı arasındaki farkı, hataları güvenli biçimde günlüğe nasıl yazacağınızı ve cPanel üzerinden bu ayarları koda dokunmadan nasıl değiştireceğinizi göreceksiniz. Ayrıca WordPress kullanıyorsanız WP_DEBUG ile PHP'nin kendi ayarlarının nasıl bir arada çalıştığını da netleştireceğiz. Amaç, sitenizi hem güvende tutmak hem de bir sorun çıktığında elinizi kolunuzu bağlamadan hızlıca teşhis koyabilmenizdir.

display_errors Üretimde Neden Kapalı Olmalı#

display_errors ayarı, PHP'nin ürettiği hata mesajlarını doğrudan tarayıcıya (HTML çıktısına) yazıp yazmayacağını belirler. Geliştirici makinenizde bu son derece yararlıdır: bir yazım hatası veya tanımsız değişken anında ekrana düşer, satır numarasıyla birlikte. Ancak aynı davranış canlı sunucuda ciddi bir güvenlik açığıdır.

Bir hata mesajı çoğu zaman göründüğünden çok daha fazlasını sızdırır. Tipik bir üretim hatasında ziyaretçi şunları görebilir: sunucudaki tam dosya yolu (/home/kullanici/public_html/wp-content/...), veritabanı tablo adları, kullanılan kütüphane sürümleri, hatta bazı durumlarda sorgu parçaları. Bu bilgiler, kötü niyetli birinin sitenizin dizin yapısını ve teknoloji yığınını haritalamasına yardımcı olur. Yani display_errors açık bir üretim sitesi, saldırgana bedava keşif imkânı sunar.

Bu yüzden altın kural nettir: üretimde display_errors daima kapalı olmalıdır. Hataları görmezden gelmiyoruz; sadece ekrandan gizleyip birazdan anlatacağımız günlük dosyasına yönlendiriyoruz. Canlı ortam için önerilen değerler şöyledir:

; Üretim (canlı site) için önerilen ayarlar
display_errors = Off
display_startup_errors = Off
log_errors = On
error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT

display_startup_errors ayrını da kapatmayı unutmayın; bu ayar, PHP'nin başlangıç aşamasında (uzantı yüklenirken vb.) oluşan hataları ekrana basar ve varsayılan olarak açık kalabilir. Kapalı display_errors ile açık display_startup_errors kombinasyonu, kimi zaman ekrana yine hata düşmesine neden olur; ikisini birlikte kapatmak temiz sonucu garantiler.

error_reporting ile Hangi Hataların Sayılacağını Seçmek#

error_reporting, PHP'nin hangi hata türlerini dikkate alacağını belirleyen bir maskedir. display_errors "hataları göster mi göstermeme mi" sorusunu yanıtlarken, error_reporting "hangi hataları" sorusunu yanıtlar. Bu ayar bit bayraklarından oluşur ve bunları | (VEYA), & (VE), ~ (DEĞİL) operatörleriyle birleştirirsiniz.

En sık kullanılan seviyelerin ne anlama geldiğini bir tabloyla özetleyelim:

Üretimde genellikle E_ALL & ~E_DEPRECATED & ~E_STRICT kullanmak mantıklıdır: her şeyi izlersiniz ama gürültü yaratan "kullanımdan kaldırıldı" ve stil uyarılarını günlüğü doldurmasınlar diye eleersiniz. Geliştirme ortamında ise tam tersini istersiniz; en küçük belirtiyi bile görmek için maskeyi sonuna kadar açarsınız:

; Geliştirme ortamı için
display_errors = On
display_startup_errors = On
log_errors = On
error_reporting = E_ALL

Bu ayarları PHP dosyanızın en üstünde çalışma zamanında da geçersiz kılabilirsiniz; ancak dikkat edin, display_errors'ı bir sözdizimi (parse) hatası oluştuktan sonra koddan açamazsınız çünkü betik zaten hiç çalışmaya başlamamıştır. Çalışma zamanı geçersiz kılma örneği:

<?php
// Yalnızca geçici teşhis için, üretimde bırakmayın
ini_set('display_errors', '1');
ini_set('display_startup_errors', '1');
error_reporting(E_ALL);

PHP'nin farklı sürümleri bu maskeleri biraz farklı yorumlayabilir; örneğin PHP 8 ile birçok eski "notice" seviyesi "warning" seviyesine yükseltilmiştir. Sürümler arası bu tür davranış değişikliklerini merak ediyorsanız, PHP sürüm yönetimi rehberimizi okumanızı öneririm; oradaki sürüm geçiş notları hata seviyelerindeki kaymaları da netleştiriyor.

log_errors ve error_log ile Hataları Dosyaya Yazmak#

Üretimde hataları ekrandan gizlediğimize göre, onları bir yere kaydetmemiz şart. İşte tam bu noktada log_errors devreye girer. Bu ayarı On yaptığınızda PHP, her hatayı belirlediğiniz bir dosyaya zaman damgasıyla yazar. Böylece ziyaretçi temiz bir sayfa görürken, siz sunucuda tüm ayrıntılara sahip olursunuz.

Nereye yazılacağını error_log yönergesiyle belirlersiniz. İki yaygın yaklaşım vardır: siteye özel tek bir dosya kullanmak veya sunucunun merkezi günlüğüne bırakmak. Çoğu paylaşımlı hosting kullanıcısı için siteye özel dosya en pratik olanıdır:

log_errors = On
error_log = /home/kullanici/logs/php_errors.log

Yolu belirlerken dizinin var olduğundan ve web sunucusu kullanıcısının o dizine yazma iznine sahip olduğundan emin olun. cPanel hesaplarında public_html dışında bir logs klasörü tutmak, günlüğün web'den erişilebilir olmamasını sağladığı için daha güvenlidir. Dosyanın oluştuğunu ve büyüdüğünü SSH ile takip edebilirsiniz:

# Günlüğü canlı izlemek için
tail -f /home/kullanici/logs/php_errors.log

# Son 50 satırı görmek için
tail -n 50 /home/kullanici/logs/php_errors.log

# Belirli bir dosyaya ait hataları filtrelemek için
grep "wp-content/plugins/eklenti-adi" /home/kullanici/logs/php_errors.log

Tipik bir günlük satırı şuna benzer ve içinde tarih, hata türü, mesaj ve dosya/satır bilgisi bulunur:

[10-Jul-2026 09-14-22 Europe/Istanbul] PHP Warning:  Undefined array key "email" in /home/kullanici/public_html/form.php on line 42

Günlük dosyaları zamanla büyüyebilir. Diskinizi doldurmasını önlemek için düzenli bir döndürme (rotation) uygulayın. VDS veya sunucu yönetimi hizmeti kullananlar için logrotate bunun standart aracıdır:

# /etc/logrotate.d/php-app
/home/kullanici/logs/php_errors.log:
  weekly: true
  rotate: 8
  compress: true
  missingok: true
  notifempty: true

Kendi sunucunuzu yönettiğinizde bu tür bakım işlerini de üstlenmeniz gerekir; bu yükü almak istemiyorsanız sunucu yönetimi hizmetimiz günlük döndürme, güvenlik ve güncelleme gibi işleri sizin yerinize yürütür.

Geliştirme ile Üretim Ayarlarını Ayırmak#

Aynı kod tabanını hem yerel makinenizde hem canlı sunucuda çalıştırırken, hata ayarlarının ortama göre değişmesini istersiniz. En temiz yöntem, ayarları kodun içine gömmek yerine bir ortam değişkenine bağlamaktır. Böylece tek bir dosyada iki farklı davranış tanımlar, hangi ortamda olduğunuza göre otomatik geçiş yaparsınız.

Aşağıdaki desen, uygulamanın giriş noktasında (index.php veya bootstrap.php) çalışır ve APP_ENV değişkenine bakarak doğru profili seçer:

<?php
$env = getenv('APP_ENV') ?: 'production';

if ($env === 'development') {
    ini_set('display_errors', '1');
    ini_set('display_startup_errors', '1');
    error_reporting(E_ALL);
} else {
    ini_set('display_errors', '0');
    ini_set('display_startup_errors', '0');
    ini_set('log_errors', '1');
    ini_set('error_log', __DIR__ . '/../logs/php_errors.log');
    error_reporting(E_ALL & ~E_DEPRECATED & ~E_STRICT);
}

Bu yaklaşımın güzelliği, canlıya yanlışlıkla "geliştirme" ayarlarıyla çıkma riskini azaltmasıdır; varsayılan daima güvenli tarafta, yani üretimde kalır. Ortam değişkenini web sunucusu yapılandırmasında tanımlayabilirsiniz. Nginx + PHP-FPM kullanan bir kurulumda, ortamı FPM havuz dosyasında belirlemek yaygındır:

# PHP-FPM havuzunda ortam belirleme (www.conf içinde)
# env[APP_ENV] = production
#
# Nginx tarafında ise FastCGI parametresi geçilebilir
location ~ \.php$ {
    include        fastcgi_params;
    fastcgi_param  APP_ENV production;
    fastcgi_pass   unix:/run/php/php8.2-fpm.sock;
}

Yerel geliştirme makinenizde ise APP_ENV=development tanımlarsınız ve aynı kod artık hataları ekrana basar. Uygulama sağlıklı çalışsa bile bu ayrımı yapmak, ekibinizin canlı ortamı yanlışlıkla tehlikeye atmasını engelleyen basit ama güçlü bir korumadır.

cPanel INI Editor ile Ayarları Değiştirmek#

Paylaşımlı hosting kullanıyorsanız php.ini dosyasına doğrudan erişiminiz olmayabilir, ama endişelenmeyin: cPanel, bu ayarları görsel bir arayüzden değiştirmenizi sağlar. cPanel ana ekranında Software bölümü altında yer alan MultiPHP INI Editor aracını açtığınızda, iki sekme görürsünüz. Basic Mode en sık kullanılan ayarları anahtarlarla sunar; Editor Mode ise seçtiğiniz alan adı için doğrudan INI metnini düzenlemenize izin verir.

Basic Mode'da yapmanız gereken tipik olarak şudur: önce üstteki menüden ilgili alan adını seçin, ardından display_errors anahtarını üretim için kapatın, log_errors anahtarını açın. Daha ayrıntılı kontrol için Editor Mode'a geçip aşağıdaki satırları ekleyebilirsiniz:

display_errors = Off
log_errors = On
error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT
error_log = /home/kullanici/logs/php_errors.log

Değişiklikleri kaydettikten sonra, ayarların gerçekten uygulandığını doğrulamak isterseniz geçici bir kontrol dosyası oluşturabilirsiniz. Bu dosya PHP yapılandırmanızın tümünü listeler; işiniz bitince mutlaka silin çünkü sunucu bilgilerinizi ifşa eder:

<?php
// gecici-kontrol.php — kontrol sonrası SİLİN
phpinfo();

Sayfada display_errors ve log_errors satırlarındaki "Local Value" sütununa bakın; girdiğiniz değerleri görüyorsanız ayar geçmiş demektir. Bazı hosting ortamlarında değişikliklerin etkinleşmesi için PHP-FPM'in yeniden başlaması gerekebilir; cPanel bunu genellikle otomatik yapar, aksi halde hosting sağlayıcınızın yardım hattına kısa bir bilet açmanız yeterlidir. Sitenizi taşırken bu ayarların da yeni sunucuda doğru kurulduğundan emin olmak isterseniz, site taşıma hizmetimiz yapılandırmayı sizin adınıza aktarır.

WordPress ve WP_DEBUG ile İlişkisi#

WordPress kullanıyorsanız, PHP'nin çekirdek ayarlarının üzerine bir katman daha eklenir: WP_DEBUG. Bu sabit, wp-config.php dosyasında tanımlanır ve WordPress'in kendi hata ayıklama davranışını kontrol eder. Aslında perde arkasında yaptığı şey, birazdan göreceğimiz gibi PHP'nin error_reporting ve display_errors ayarlarını etkilemektir; yani iki sistem birbirinden bağımsız değildir, iç içedir.

Doğru yaklaşım, WordPress'te hataları ekrana basmadan bir dosyaya yazdırmaktır. Bunu üç sabitin birlikte kullanımıyla yaparsınız:

// wp-config.php içine, "That's all, stop editing!" satırından ÖNCE

define( 'WP_DEBUG', true );        // Hata ayıklamayı aç
define( 'WP_DEBUG_LOG', true );    // Hataları wp-content/debug.log dosyasına yaz
define( 'WP_DEBUG_DISPLAY', false ); // Ekranda GÖSTERME

@ini_set( 'display_errors', 0 );   // PHP tarafında da ekrana basmayı kapat

Bu yapılandırmada hatalar wp-content/debug.log dosyasına düşer ve ziyaretçi hiçbir şey görmez. WP_DEBUG_LOG değerine bir dosya yolu vererek günlüğü web'den erişilemeyecek başka bir konuma da yönlendirebilirsiniz. Önemli bir uyarı: WP_DEBUG açık bir sitede bazı eklentiler ekstra çıktı ürettiği için AJAX veya REST API çağrıları bozulabilir; bu yüzden ayarları toparladıktan sonra sorununuzu çözdüyseniz WP_DEBUG değerini yeniden false yapmayı unutmayın.

WordPress kaynaklı hata çözümü konusunu daha derinlemesine ele aldığımız WordPress hata çözümü rehberimizde debug.log dosyasını okuma, eklenti çakışmalarını izole etme ve tema kaynaklı beyaz ekranları teşhis etme adımlarını bulabilirsiniz. WordPress'e özel optimize edilmiş bir altyapı arıyorsanız WordPress hosting paketlerimiz bu ayarların çoğu zaten güvenli varsayılanlarla gelir.

Yaygın Hatalar ve Hızlı Kontrol Listesi#

Uygulamada en çok karşılaşılan sorunları ve çözümlerini kısa bir tabloda toplayalım. Bir sitede hata ayıklarken bu listeyi baştan sona geçmek, çoğu zaman sorunu birkaç dakikada daraltmanızı sağlar:

Ayarlarınızın gerçekten yürürlükte olup olmadığını komut satırından da hızlıca doğrulayabilirsiniz. SSH erişiminiz varsa şu komutlar aktif değerleri gösterir:

# Aktif display_errors ve log ayarlarını görmek için
php -i | grep -E "display_errors|log_errors|error_log"

# Belirli bir dosyanın sözdizimini test etmek için
php -l public_html/wp-config.php

php -l komutu özellikle değerlidir çünkü bir dosyada sözdizimi hatası olup olmadığını, siteyi hiç çağırmadan söyler. Beyaz ekran sorunlarının önemli bir kısmı, düzenlenen bir dosyadaki eksik bir noktalı virgül ya da kapatılmamış bir paranteze dayanır; php -l bunu saniyeler içinde ortaya çıkarır. Daha karmaşık, sürekli tekrarlayan üretim sorunlarında ise günlükleri düzenli yedeklemek teşhis için altın değerindedir; bu noktada otomatik yedekleme çözümümüz hem site dosyalarınızı hem de günlüklerinizi güvenle saklar.

Sıkça Sorulan Sorular#

display_errors ile log_errors arasındaki fark nedir?#

display_errors hataların tarayıcıya, yani ziyaretçinin gördüğü sayfaya basılıp basılmayacağını belirler; log_errors ise hataların sunucudaki bir dosyaya yazılıp yazılmayacağını kontrol eder. İkisi tamamen bağımsız ayarlardır. Üretim ortamı için ideal kombinasyon, display_errors kapalı ve log_errors açık olmasıdır: ziyaretçi temiz bir sayfa görür, siz ise tüm hata ayrıntılarına günlük dosyasından ulaşırsınız.

Beyaz ekran görüyorum ama hiç hata mesajı yok, ne yapmalıyım?#

Bu klasik durum genellikle display_errors ayarının kapalı olduğunu ve ölümcül bir hatanın sessizce betiği durdurduğunu gösterir. Öncelikle log_errors ayarını açıp error_log ile belirlediğiniz dosyaya bakın; hata büyük olasılıkla oraya yazılmıştır. Günlük de boşsa, dosyanın bir sözdizimi hatası içerip içermediğini php -l dosya.php komutuyla test edin, çünkü parse hataları koddan display_errors açsanız bile ekrana yansımaz.

error_reporting için üretimde hangi değeri kullanmalıyım?#

Üretim için dengeli bir seçim E_ALL & ~E_DEPRECATED & ~E_STRICT değeridir. Bu maske tüm gerçek hataları ve uyarıları izler, ancak günlüğü gereksiz yere şişiren "kullanımdan kaldırıldı" bildirimlerini ve stil önerilerini eler. Geliştirme ortamında ise en küçük belirtiyi bile yakalamak için E_ALL kullanmanızı öneririm; orada gürültü değil, tam görünürlük istersiniz.

phpinfo dosyasını sitede bırakmak neden tehlikelidir?#

phpinfo() çıktısı, sunucunuzun PHP sürümünü, yüklü uzantıları, dosya yollarını, ortam değişkenlerini ve daha birçok yapılandırma ayrıntısını herkese açık biçimde listeler. Bu bilgiler, bir saldırganın sitenizin zayıf noktalarını tespit etmesini kolaylaştırır. Bu yüzden bir kontrol dosyasını yalnızca geçici olarak oluşturun, doğrulamanızı yapar yapmaz mutlaka silin ve asla tahmin edilmesi kolay bir adla üretimde bırakmayın.

WP_DEBUG açtığımda sitem yavaşlar mı veya bozulur mu?#

WP_DEBUG açıkken WordPress ve eklentiler ekstra uyarılar üretebilir; bu da özellikle WP_DEBUG_DISPLAY açık bırakılırsa AJAX ve REST API yanıtlarını bozabilir ya da günlüğü hızla büyütebilir. Performansta hissedilir bir yavaşlama da olabilir çünkü ek denetimler çalışır. Bu nedenle hata ayıklamayı yalnızca sorunu araştırdığınız süre boyunca açık tutun, WP_DEBUG_DISPLAY değerini false bırakın ve teşhis biter bitmez WP_DEBUG sabitini yeniden kapatın.

Ayarları değiştirdim ama hiçbir şey değişmedi, neden?#

Bunun en yaygın nedeni yanlış yapılandırma dosyasını düzenlemenizdir; sunucuda birden fazla php.ini bulunabilir ve web sunucusu bambaşka birini kullanıyor olabilir. phpinfo() çıktısındaki "Loaded Configuration File" satırı size aktif dosyanın tam yolunu söyler. Ayrıca bazı ortamlarda PHP-FPM'in değişiklikleri okuması için yeniden başlatılması gerekir; cPanel bunu genellikle otomatik yapsa da, gerekirse hosting sağlayıcınızdan bir yeniden başlatma talep edebilirsiniz.

Kapanış#

PHP hata raporlaması, doğru kurulduğunda hem güvenliğinizi hem de teşhis hızınızı aynı anda yükseltir. Özetlersek: üretimde display_errors daima kapalı, log_errors daima açık olmalı; error_reporting maskesini ortama göre ayarlamalı; hataları web'den erişilemeyen bir günlük dosyasına yazmalı ve WordPress kullanıyorsanız WP_DEBUG üçlüsünü ekrana basmadan günlüğe alacak biçimde kurmalısınız. Bu birkaç satırlık yapılandırma, bir sorun çıktığında saatlerce karanlıkta el yordamıyla arama yapmakla, dosyaya bakıp iki dakikada kaynağı bulmak arasındaki farkı yaratır.

Bu ayarları güvenli varsayılanlarla gelen, hızlı ve destekli bir altyapıda çalıştırmak isterseniz Clou.TR yanınızda. İhtiyacınıza göre performanslı web hosting ve WordPress hosting paketlerimize, tam denetim isteyen projeler için sanal ve VDS sunucu çözümlerimize göz atabilir; yapılandırma, güncelleme ve izleme yükünü bize bırakmak isterseniz sunucu yönetimi hizmetimizden faydalanabilirsiniz. Sorularınız olduğunda destek ekibimiz, tam da bu rehberde anlattığımız günlükleri sizinle birlikte okuyup sorunu çözmeye hazır.