PHP Hata Raporlamasını Etkinleştirme: Tam Bir Geliştirici Kılavuzu

PHP uygulamalarında hata ayıklamayı verimli bir şekilde yapmak, saatlerce süren hayal kırıklığı ile hızlı ve temiz bir düzeltme arasındaki farkı yaratabilir. İster yeni bir web uygulaması oluşturuyor olun ister mevcut bir uygulamayı yönetiyor olun, PHP hata raporlamasını etkinleştirmeyi ve yapılandırmayı bilmek her geliştiricinin ihtiyaç duyduğu temel bir beceridir. Bu kapsamlı kılavuz, mevcut olan her yöntemi — hızlı betik içi düzeltmelerden sunucu düzeyinde yapılandırmaya kadar — kapsar ve hem geliştirme hem de üretim ortamlarında hata raporlamasını güvenli bir şekilde nasıl ele alacağınızı açıklar.

PHP Hata Raporlaması Nedir ve Neden Önemlidir?

PHP hata raporlaması, komut dosyası yürütülmesi sırasında PHP’nin hangi hata, uyarı ve bildirim türlerini göstereceğini kontrol eden yerleşik bir özelliktir. Düzgün şekilde yapılandırıldığında, kodunuzdaki sorunlar hakkında anında, işlem yapılabilir geri bildirim sağlar — söz konusu sorunlar arasında söz dizimi hataları, tanımlanmamış değişkenler, kullanımdan kaldırılan işlevler, çalışma zamanı özel durumları ve başarısız veritabanı sorguları yer alır.

Varsayılan olarak, birçok sunucu yapılandırması hata çıkışını tamamen bastırır; özellikle üretim ortamlarında. Bu kasıtlıdır: ham hata mesajlarını son kullanıcılara göstermek, dosya yolları, veritabanı kimlik bilgileri ve dahili uygulama mantığı gibi hassas bilgileri ortaya çıkarabilir. Ancak geliştirme sırasında, hataları bastırmak hata ayıklamayı gereksiz yere zorlaştırır.

Hata raporlamasını açıp kapatmayı — ve nerede yapılandıracağını — anlamak, VPS Hosting ortamında veya paylaşılan sunucuda PHP ile çalışan herhangi bir geliştirici için gereklidir.

PHP Hata Seviyeleri Bir Bakışta

PHP hataları farklı seviyelere kategorize eder; her biri bağımsız olarak kontrol edilir:

Geliştirme sırasında E_ALL kullanmak, her olası sorunu üretim ortamına ulaşmadan önce yakalamanızı sağlar.

Yöntem 1: PHP Hata Raporlamasını Doğrudan Betiğinizde Etkinleştirin

Hata raporlamasını etkinleştirmenin en hızlı yolu, PHP dosyanızın en üstüne, başka herhangi bir çıktıdan önce iki satır eklemektir. Bu yaklaşım, sunucu genelinde yapılandırma dosyalarını değiştirmeden belirli bir betiği hızlı bir şekilde hata ayıklamak için idealdir.

<?php
error_reporting(E_ALL);          // Report all types of errors
ini_set('display_errors', 1);    // Display errors directly in the browser
ini_set('display_startup_errors', 1); // Also show errors during PHP startup
?>

Her Satırın Yaptığı İşlem

• error_reporting(E_ALL) — Hata raporlama seviyesini, bildirimler, uyarılar, kullanımdan kaldırma uyarıları ve ölümcül hatalar da dahil olmak üzere her hata kategorisini yakalamak için ayarlar. Ayrıca, örneğin E_ALL & ~E_NOTICE gibi bitwise operatörleri kullanarak belirli sabitleri birleştirebilirsiniz ve bunu bildirimleri hariç tutmak için kullanabilirsiniz.
• ini_set('display_errors', 1) — PHP’ye hata mesajlarını doğrudan tarayıcıya veya komut satırına çıkarmak için talimat verir. Bunu 0 olarak ayarlamak, hataları günlüğe kaydetmeyi devre dışı bırakmadan çıktıdan gizler.
• ini_set('display_startup_errors', 1) — PHP’nin başlangıç sırası sırasında oluşan hataların raporlanmasını etkinleştirir; bu, display_errors tek başına kapsamaz.

> Önemli: Bu satırları her zaman betiğinizin en üstüne yerleştirin. Bu satırlara ulaşılmadan önce ölümcül bir ayrıştırma hatası oluşursa, hiçbir etkisi olmayacaktır. Ayrıştırma hataları için, bunun yerine hata raporlamasını php.ini seviyesinde yapılandırmanız gerekir.

Bu Yöntemi Ne Zaman Kullanmalısınız

Bu yöntem aşağıdakiler için en uygun olanıdır:

• Tek bir betiği veya modülü hızlı bir şekilde hata ayıklamak

php.ini erişiminiz olmayan paylaşılan barındırma ortamları
Etkin geliştirme sırasında geçici hata ayıklama oturumları

Yöntem 2: php.ini Aracılığıyla PHP Hata Raporlamasını Etkinleştirin (Önerilen)
Kalıcı, sunucu genelinde bir yapılandırma için, php.ini dosyasını değiştirmek en güvenilir yaklaşımdır. Burada yapılan değişiklikler, sunucuda çalışan tüm PHP betikleri için küresel olarak geçerli olur ve bu da bunu adanmış geliştirme ortamları için tercih edilen yöntem haline getirir.
Adım 1: php.ini Dosyanızı Bulun
php.ini dosyasının konumu, işletim sisteminize, PHP sürümünüze ve web sunucunuza bağlı olarak değişir. Bunu bulmanın en kolay yolu, aşağıdakini içeren geçici bir PHP dosyası oluşturmaktır:
<?php
phpinfo();
?>
Bu dosyayı sunucunuza yükleyin, tarayıcıda açın ve “Loaded Configuration File” girişini arayın. Bu, etkin php.ini dosyasının tam yolunu gösterecektir.
Yaygın varsayılan konumlar şunları içerir:

Linux (Apache): /etc/php/8.x/apache2/php.ini

> Güvenlik hatırlatması: phpinfo() dosyanıza erişimi kullanımdan hemen sonra silin veya kısıtlayın. İstismar edilebilecek ayrıntılı sunucu yapılandırma verilerini ortaya çıkarır.

Adım 2: php.ini Dosyasını Düzenleyin

Sunucunuzda bir metin editörü veya SSH kullanarak php.ini dosyasını açın:

sudo nano /etc/php/8.x/apache2/php.ini

Aşağıdaki yönergeleri bulun ve gösterildiği gibi güncelleyin:

Önce (tipik üretim varsayılanları):

display_errors = Off
display_startup_errors = Off
error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT
log_errors = On

Sonra (geliştirme yapılandırması):

display_errors = On
display_startup_errors = On
error_reporting = E_ALL
log_errors = On
error_log = /var/log/php/error.log

Adım 3: Web Sunucunuzu Yeniden Başlatın

Değişikliklerinizi kaydettikten sonra, yeni yapılandırmayı uygulamak için web sunucusunu yeniden başlatın:

Apache için:

sudo systemctl restart apache2

Nginx ile PHP-FPM için:

sudo systemctl restart php8.x-fpm
sudo systemctl restart nginx

Windows üzerinde XAMPP için:

XAMPP Kontrol Panelini açın ve Apache’nin yanındaki Durdur‘u ve ardından Başlat‘ı tıklayın.

Yöntem 3: .htaccess Aracılığıyla Hata Raporlamasını Etkinleştirme (Yalnızca Apache)

Eğer php.ini dosyasına doğrudan erişim olmayan paylaşılan bir barındırma ortamındaysanız ve sunucunuz Apache çalıştırıyorsa, web sitenizin kök dizinine yerleştirilen bir .htaccess dosyası kullanarak PHP ayarlarını geçersiz kılabilirsiniz.

php_flag display_errors On
php_flag display_startup_errors On
php_value error_reporting 32767
php_flag log_errors On
php_value error_log /home/yourusername/logs/php_errors.log

32767 sayısal değeri PHP’de E_ALL ile karşılık gelir. Bu yöntem, sunucu düzeyinde yapılandırma erişiminin kısıtlandığı Paylaşılan Web Barındırma planlarında özellikle kullanışlıdır.

> Not: Bu yöntem yalnızca barındırma sağlayıcınız .htaccess aracılığıyla PHP yönergesi geçersiz kılmalarına izin veriyorsa çalışır. Bazı barındırma sağlayıcılar güvenlik nedenleriyle bunu devre dışı bırakır.

Yöntem 4: Yerel Geliştirme Ortamlarında Hata Raporlamayı Yapılandırın

XAMPP, MAMP veya WAMP gibi yerel bir geliştirme yığını çalıştırıyorsanız, işlem basittir.

XAMPP (Windows / Linux / macOS)

1. XAMPP Control Panel‘i açın
2. Apache’nin yanındaki Config‘e tıklayın
3. Açılır menüden PHP (php.ini)‘yi seçin
4. Yöntem 2’de açıklanan geliştirme ayarlarını uygulayın
5. Control Panel’den Apache’yi yeniden başlatın

MAMP (macOS)

1. MAMP Preferences‘i açın
2. PHP sekmesine gidin
3. Yapılandırma dosyasını açmak için php.ini düğmesine tıklayın
4. Geliştirme ayarlarını uygulayın ve kaydedin
5. MAMP sunucularını yeniden başlatın

Docker Tabanlı Ortamlar

Yerel geliştirme için Docker kullanıyorsanız, PHP yapılandırma değerlerini doğrudan ortam değişkenleri aracılığıyla iletebilir veya özel bir php.ini dosyasını bağlayabilirsiniz:

RUN echo "display_errors = On" >> /usr/local/etc/php/conf.d/custom.ini
RUN echo "error_reporting = E_ALL" >> /usr/local/etc/php/conf.d/custom.ini

Hata Raporlama Yapılandırmanızı Test Etme

Yukarıdaki yöntemlerden herhangi birini kullanarak hata raporlamayı etkinleştirdikten sonra, bir test betiğine kasıtlı olarak bir hata ekleyerek doğru şekilde çalışıp çalışmadığını doğrulayın:

<?php
error_reporting(E_ALL);
ini_set('display_errors', 1);

// Intentional error: undefined variable
echo $undefinedVariable;

// Intentional warning: wrong argument count
strlen();

// Intentional notice: undefined array key
$array = [];
echo $array['missing_key'];
?>

Hata raporlama doğru şekilde yapılandırılmışsa, PHP bu sorunların her biri için bildirimler ve uyarılar görüntüleyecektir. Aşağıdakine benzer bir çıktı görmelisiniz:

Notice: Undefined variable: undefinedVariable in /var/www/html/test.php on line 5
Warning: strlen() expects exactly 1 argument, 0 given in /var/www/html/test.php on line 8
Notice: Undefined index: missing_key in /var/www/html/test.php on line 12

Üretimde Hata Görüntülemeyi Devre Dışı Bırakma ve Hataları Günlüğe Kaydetme

Uygulamanız dağıtıma hazır olduğunda, son kullanıcılara hiçbir zaman hata mesajları görüntülememeli. Açığa çıkan hatalar şunları ortaya çıkarabilir:

• Sunucudaki mutlak dosya yolları
• Veritabanı tablo adları ve sorgu yapıları
• PHP sürümü ve uzantı ayrıntıları
• Uygulama mantığı ve yapılandırma verileri

Bu bilgiler önemli bir güvenlik riski oluşturur ve kötü niyetli kişiler tarafından istismar edilebilir. Bunun yerine, PHP’yi hataları sessizce bir dosyaya kaydetmek için yapılandırın.

Önerilen Üretim php.ini Ayarları

display_errors = Off
display_startup_errors = Off
error_reporting = E_ALL
log_errors = On
error_log = /var/log/php/production_errors.log

error_reporting ayarının üretimde de E_ALL olarak ayarlanmış kaldığına dikkat edin. Bu, tüm hataların ziyaretçilere açığa çıkarılmadan günlük dosyanızda yakalanmasını sağlar.

Hata Günlüğü Dosyasını Oluşturma ve Güvenliğini Sağlama

# Create the log directory
sudo mkdir -p /var/log/php

# Create the log file
sudo touch /var/log/php/production_errors.log

# Set appropriate ownership
sudo chown www-data:www-data /var/log/php/production_errors.log

# Restrict permissions
sudo chmod 640 /var/log/php/production_errors.log

Hata Günlüklerinizi İzleme

tail komutunu kullanarak PHP hata günlüğünüzü gerçek zamanlı olarak izleyebilirsiniz:

tail -f /var/log/php/production_errors.log

Bu, tam kök erişimine sahip olduğunuz ve günlük döndürme, uyarı ve Logwatch veya Fail2Ban gibi izleme araçlarını yapılandırabileceğiniz bir Dedicated Server‘da özellikle yararlıdır.

PHP Hata Raporlaması: Geliştirme ve Üretim Ayarları Özeti

Advanced: Custom Error Handlers

Daha sofistike uygulamalar için, PHP set_error_handler() kullanarak özel bir hata işleme işlevi tanımlamanıza olanak sağlar. Bu, hataların nasıl işlendiği, biçimlendirildiği ve depolandığı üzerinde tam kontrol sağlar.

<?php
function customErrorHandler(int $errno, string $errstr, string $errfile, int $errline): bool {
    $timestamp = date('Y-m-d H:i:s');
    $message = "[$timestamp] Error $errno: $errstr in $errfile on line $errline" . PHP_EOL;

    // Log to a custom file
    error_log($message, 3, '/var/log/php/custom_errors.log');

    // Optionally display a friendly message to users in production
    if (ini_get('display_errors')) {
        echo "<pre>$message</pre>";
    }

    return true; // Prevent PHP's default error handler from running
}

set_error_handler('customErrorHandler');
?>

Özel hata işleyiciler, yapılandırılmış günlüğe kaydetme, Sentry veya Datadog gibi izleme hizmetleriyle entegrasyon veya kullanıcı dostu hata sayfaları gerektiren uygulamalar oluştururken özellikle değerlidir.

PHP Geliştirme için Doğru Hosting Ortamını Seçmek

Hosting ortamınız, PHP hata raporlamasını ne kadar etkili bir şekilde yapılandırabileceğiniz ve yönetebileceğiniz konusunda kritik bir rol oynar. Her ortamın sunduğu şeyin hızlı bir özeti aşağıdadır:

• Paylaşımlı Web Hosting — php.ini erişimi sınırlı; .htaccess veya betik içi yapılandırmaya güvenin. Küçük projeler için en iyisi.
• VPS Hosting — Tam root erişimi, php.ini, PHP-FPM havuzları ve sunucu yapılandırması üzerinde tam kontrol. Profesyonel PHP geliştirme için ideal.
• cPanel ile VPS — Root düzeyinde kontrolü, PHP sürümleri ve etki alanı başına ayarları yönetmek için grafik arayüzün rahatlığı ile birleştirir.
• Dedicated Sunucular — Maksimum performans ve izolasyon; karmaşık günlük kaydı ve izleme gereksinimleri olan yüksek trafikli PHP uygulamaları için en iyisi.

PHP geliştirme konusunda ciddiyseniz ve sunucu yığını üzerinde tam kontrol sahibi olmak istediğiniz istikrarlı, yapılandırılabilir bir ortama ihtiyacınız varsa, VPS veya dedicated sunucu doğru seçimdir.

Sık Sorulan Sorular

Komut dosyamda hata raporlamasını etkinleştirdikten sonra bile PHP hatalarım neden gösterilmiyor?

Bu genellikle bir php.ini yönergesi tarafından komut dosyası içi ayarlarınızın geçersiz kılınması veya error_reporting() çağrısına ulaşılmadan önce bir ayrıştırma hatası oluşmasından kaynaklanır. php.ini ayarlarınızı doğrulayın ve sunucu düzeyinde hata raporlamasını etkinleştirmeyi düşünün.

Hata raporlamasını yalnızca bir dizin için etkinleştirebilir miyim?

Evet. Belirli dizine PHP hata yönergeleri içeren bir .htaccess dosyası yerleştirin veya sunucunuz destekliyorsa dizin başına php.ini dosyası kullanın.

Hata raporlamasını etkinleştirmek uygulamamı yavaşlatır mı?

Önemsiz düzeyde. Hata raporlamasının kendisinin performans etkisi minimumdur. Ancak, her istekte günlük dosyalarına yazma işlemi, yüksek trafikli ortamlarda küçük I/O yükü ekleyebilir.

display_errors ile log_errors arasındaki fark nedir?

display_errors hata çıktısını tarayıcıya veya komut satırına gönderir. log_errors hataları bir dosyaya yazar. Üretimde, her zaman log_errors = On ile display_errors = Off kullanın.

Sonuç

PHP hata raporlamasını etkinleştirmek, geliştirme iş akışınızı iyileştirmek için alabileceğiniz en etkili adımlardan biridir. Sessiz, görünmez hataları, sizi doğrudan sorunun kaynağına işaret eden net, işlem yapılabilir mesajlara dönüştürür — saatlerce tahmin ve hata ayıklama zamanından tasarruf eder.

Bu kılavuzun temel çıkarımları şunlardır:

1. error_reporting(E_ALL) ve ini_set('display_errors', 1) kullanın hızlı, komut dosyası başına hata ayıklama için
2. php.ini değiştirin geliştirme ortamlarında kalıcı, sunucu genelinde hata raporlaması için
3. .htaccess kullanın paylaşılan barındırmada php.ini için doğrudan erişiminiz olmadığında
4. Üretimde her zaman display_errors devre dışı bırakın ve hata çıktısını güvenli bir günlük dosyasına yönlendirin
5. Gelişmiş günlüğe kaydetme, izleme ve kullanıcı dostu hata sayfaları için özel bir hata işleyicisini düşünün

Doğru barındırma ortamını seçmek de önemlidir. Basit bir proje için Paylaşılan Web Barındırması‘nı seçseniz de ya da profesyonel bir PHP uygulaması için tam yönetilen VPS Barındırması planını seçseniz de, doğru düzeyde sunucu erişimine sahip olmak, hata raporlamasını projenizin talep ettiği şekilde yapılandırabileceğinizi sağlar.

PHP hata raporlamasında uzmanlaşarak — ve ne zaman etkinleştireceğinizi ya da bastıracağınızı bilerek — baştan itibaren daha güvenilir, güvenli ve bakımı kolay uygulamalar oluşturursunuz.