Güncelleme sonrası beyaz ekran: hata logunu mühendis gibi okumak

Güncelleme bitti, vitrini yenilediniz ve tarayıcıda hiçbir şey yok. Hata yok, tasarım yok, OpenCart yok. Site silinmiş gibi hissettirir. Öyle değildir: PHP sayfayı kurarken durmuştur ve durma nedeni bir yere yazılmıştır — yalnızca önünüzdeki ekrana değil.

Aşağıdaki, arıza çağrılarında sırayla uyguladığımız yöntem. Saatler değil dakikalar alır ve OpenCart 3.0.x ile 4.x'te aynı şekilde işler.

Beyaz ekran, göremediğiniz bir 500'dür

İşe durum kodundan başlayın, çünkü problemi ikiye böler. Vitrini ve yönetim panelini ayrı ayrı sorun; biri cevap veriyorsa arama alanını daha ilk adımda yarıya indirmiş olursunuz.

curl -s -o /dev/null -D - "https://example.com/" | head -n 1
curl -s -o /dev/null -D - "https://example.com/index.php?route=common/home" | head -n 1
curl -s -o /dev/null -D - "https://example.com/yonetim/index.php" | head -n 1

HTTP 500, PHP'nin öldüğünü ve web sunucusunun bundan haberdar olduğunu gösterir; nedeni FPM ve web sunucusu loglarındadır. Gövdesi boş bir HTTP 200 ise daha kafa karıştırıcı durumdur: PHP çalışmış, hiçbir çıktı üretmemiş ve hata gösterimi kapalıdır. Bu neredeyse her zaman display_errors kapalıyken oluşan ölümcül bir hatadır — ki üretimde doğru ayar budur ve sonraki adımlar tam olarak bu yüzden vardır.

Bu arada PHP ile hiç ilgisi olmayan iki ihtimali de eleyin. CDN ya da tam sayfa önbelleği, site düzeldikten çok sonra bile boş cevabı servis etmeye devam edebilir; tarayıcı da onu seve seve saklar. curl ikisini de atlar: curl size HTML döndürüyor ama tarayıcınız hâlâ beyaz gösteriyorsa sorun OpenCart'ın içinde değil, önündedir.

Üç log, şu sırayla

OpenCart kendi logunu system/storage/logs/error.log dosyasına yazar; depolama dizini web kökünün dışına taşındıysa config.php içindeki DIR_LOGS neyi gösteriyorsa oraya. Bu dosya ilk durak olsa da hikâyenin tamamı değildir: OpenCart'ın hata yakalayıcısı yalnızca çatı ayağa kalktıktan sonra PHP'nin kendisine verdiklerini görür. Bir sözdizimi hatası ya da açılış sırasındaki bir çökme buraya hiç ulaşmaz; sadece PHP veya web sunucusu logunda görünür. Üç logu da açtıktan sonra ilk işiniz saatleri hizalamak olsun: güncellemeyi kurduğunuz dakikayı bilin ve o dakikadan sonraki kayıtlara bakın. Sunucu saatiyle panelin saat dilimi farklıysa bunu şimdi not edin, yoksa aynı olayı iki ayrı arıza sanırsınız.

tail -n 100 /var/www/store/system/storage/logs/error.log
tail -n 100 /var/log/php8.1-fpm.log
tail -n 200 /var/log/nginx/error.log      # Apache: /var/log/apache2/error.log

Hataları on dakikalığına geri açmak

OpenCart'ın hata yönetimi Sistem, Ayarlar, mağazayı düzenle, Sunucu sekmesindedir: Hataları Göster, Hataları Logla ve Hata Log Dosya Adı. Bu üçü oc_setting tablosundaki config_error_display, config_error_log ve config_error_filename anahtarlarına karşılık gelir. Yönetim paneli de beyazsa oraya ulaşamazsınız; o zaman ayarları SQL ile verin ya da PHP'yi giriş dosyasında konuşturun.

UPDATE oc_setting SET `value` = '1'
WHERE `code` = 'config' AND `key` IN ('config_error_display','config_error_log') AND store_id = 0;

<?php
// index.php — geçici, yalnızca ilk satırlar
ini_set('display_errors', '1');
ini_set('display_startup_errors', '1');
error_reporting(E_ALL);

Bulduğunuz satırı okumak

OpenCart log kaydının biçimi sabittir: zaman damgası, hata türü, mesaj, ardından dosya ve satır.

2026-08-04 23:14:07 - PHP Fatal error:  Uncaught TypeError: count(): Argument #1
($value) must be of type Countable|array, null given in
/var/www/store/extension/acme_shipping/catalog/model/shipping/acme.php:118
Stack trace:
#0 /var/www/store/system/engine/loader.php(122): Acme\Shipping->getQuote(Array)

Üç alışkanlık bu işi hızlandırır. Dosyadaki en yeni satırı değil, kurulum saatinden sonraki ilk ölümcül hatayı okuyun; sonrakiler genellikle ilkinin sonucudur. Satır numarasından önce yola bakın: extension/ altındaki ya da 3.0.x'te catalog/controller/extension altındaki her şey üçüncü taraf koddur, yani kapatabileceğiniz bir şeydir. Arama sürerken Notice ve Deprecated kayıtlarını da görmezden gelin; neredeyse her mağazada vardır ve dün de oradaydılar.

Güncelleme sonrası beyaz ekranın beş klasik nedeni

1. 1PHP sürümü güncellemeyle birlikte değişmiştir. OpenCart 4 PHP 8 ister; 3.0.x mağazası ve eklentileri ise PHP 7 için yazılmıştır. PHP 8.0'da kaldırılan each(), create_function() ve süslü parantezli dizge erişimi gibi kullanımlar eski eklenti kodunda ölümcül hataya dönüşür.
2. 2Bayatlamış modification önbelleği — yalnızca 3.0.x. system/storage/modification, çekirdek dosyaların yamalanmış kopyalarını tutar; yeni çekirdek dosyaları kurulduğunda bu kopyalar artık uyuşmaz. Klasörü boşaltın, ardından Eklentiler, Değişiklikler ekranından yenileyin.
3. 3Şablon ve veri önbelleği. system/storage/cache hâlâ önceki sürümden derlenmiş şablonları servis ediyor olabilir.
4. 4Bellek. Büyüyen katalog ya da tek bir yeni eklenti memory_limit sınırını aşar ve PHP sayfanın ortasında, çoğu zaman hiç çıktı vermeden durur.
5. 5Eksik PHP modülü ya da arşivden geri yükleme sonrası hatalı dosya sahipliği: Call to undefined function curl_init() veya failed to open stream: Permission denied.

cd /var/www/store
rm -rf system/storage/cache/*
rm -rf system/storage/modification/*        # yalnızca OpenCart 3.0.x
php -r 'foreach (["curl","gd","zip","mbstring","openssl"] as $e) printf("%-10s %s\n", $e, extension_loaded($e) ? "ok" : "MISSING");'
chown -R www-data:www-data . && find . -type d -exec chmod 755 {} \; && find . -type f -exec chmod 644 {} \;

Bu blokta iki tuzak var. php -v ve php -r komut satırı PHP'sini raporlar; bu çoğu zaman ne nginx'in kullandığı sürümdür ne de aynı modül kümesidir — havuzu php-fpm8.1 -v ile ve vhost dosyanızda adı geçen soketle doğrulayın. İkincisi: 3.0.x'te system/storage/modification klasörünü boşaltıp Yenile demezseniz OCMOD özelleştirmeleriniz hiç uygulanmaz; mağaza sorunsuz açılır, özellikler sessizce kaybolur.

OpenCart 3.0.3.x

PHP 7.4

OpenCart 4.0.x

PHP 8.0+

İlk açılacak log

system/storage/logs/error.log

Önce ayağa kaldırmak, sonra nedeni bulmak

Mağaza sipariş alıyorsa önce geri yükleyin, incelemeyi sonra yapın. Kurtarma ile teşhis iki ayrı iştir ve aynı saatte yapılmak zorunda değildir. Canlıda saatlerce deneme yapmanın maliyeti, kaybedilen siparişlerin yanında hemen her zaman daha büyüktür.

1. 1Güncelleme öncesi dosya arşivini ve veritabanı yedeğini geri yükleyin; vitrinin ve panelin 200 döndüğünü doğrulayın.
2. 2Geri yüklenen bu hâli bir test adresine kopyalayın ve güncellemeyi orada, hata gösterimi açıkken tekrarlayın.
3. 3Ölümcül hata bir eklentiyi işaret ediyorsa kopyada o eklentiyi kapatıp tekrar deneyin; her seferinde tek eklenti. Log dosyanın adını verdiği için arama alanı zaten dardır.
4. 4Düzeltmeyi kopyada yapın, sonra sakin bir saatte bakım modu açıkken ve log ekranda açıkken yeniden kurun.

Sürprizi ortadan kaldıran rutin

• Demo değil, gerçek mağazanın test kopyası: aynı eklentiler, aynı tema, aynı PHP sürümü.
• Güncellemeden hemen önce alınmış veritabanı yedeği ile dosya arşivi — ve bir kez geri yüklenerek test edilmiş olmaları.
• Başlangıçta boşaltılmış bir error.log; böylece sonradan içine düşen her şey bu güncellemeye aittir.
• Yazılı eklenti envanteri: ad, sürüm, geliştirici, son güncelleme tarihi.
• Geçiş boyunca bakım modu ve mod kapanmadan önce vitrin ile panelin curl ile kontrolü.

mysqldump --single-transaction --routines opencart | gzip > /backup/oc-$(date +%F-%H%M).sql.gz
tar czf /backup/oc-files-$(date +%F-%H%M).tar.gz -C /var/www store
: > /var/www/store/system/storage/logs/error.log

Ne zaman bize yazın

Log satırı bir anlam ifade etmiyorsa ya da ekibinizden kimsenin yazmadığı bir dosyayı işaret ediyorsa error.log dosyasının son yüz satırını OpenCart ve PHP sürümlerinizle birlikte bize gönderin. Lansman kampanyası boyunca işler saatlik 10 $ + KDV ile faturalanır ve tahmini siz onaylamadan hiçbir şey başlamaz. İlk yanıt 2 saat içinde, Pzt–Cmt 09:00–22:00 (GMT+3) arasında verilir. Mağaza şu anda kapalıysa bunu ilk satırda yazın.