OPcache resetlenmezse yeni PHP dosyaları neden görünmeyebilir?

Yeni yüklediğiniz bir PHP dosyasının tarayıcıda görünmemesi, çoğu zaman dosyanın hatalı yüklendiği veya yönlendirme kuralının yanlış olduğu düşüncesini doğurur. Ancak özellikle yoğun trafikli sitelerde ve paylaşımlı ya da yönetilen hosting ortamlarında sorun, PHP’nin performans için kullandığı OPcache mekanizmasından kaynaklanabilir. OPcache resetlenmediğinde sunucu, diskteki yeni veya güncellenmiş dosya yerine bellekte tuttuğu eski derlenmiş çıktıyı çalıştırmaya devam edebilir.

Bu durum geliştirici için kafa karıştırıcıdır çünkü FTP, SFTP veya dosya yöneticisinde dosya doğru yerde görünür; hatta dosya izinleri de normaldir. Buna rağmen tarayıcıda eski davranış devam eder, yeni sınıf yüklenmez, yeni endpoint çalışmaz veya WordPress tarafında eklenen özel PHP dosyası beklenen çıktıyı üretmez.

OPcache ne yapar ve neden önemlidir?

PHP normalde her istekte ilgili dosyaları okur, yorumlar ve çalıştırılabilir ara koda dönüştürür. OPcache bu ara kodu bellekte saklayarak aynı işlemin tekrar tekrar yapılmasını engeller. Bu, sunucu kaynaklarını daha verimli kullanır ve sayfa yanıt sürelerini düşürür.

Performans açısından faydalı olan bu yapı, dosya değişikliklerinin algılanması geciktiğinde geliştirme ve yayın alma süreçlerinde sorun yaratabilir. Özellikle sunucu yapılandırmasında dosya değişikliklerini kontrol etme sıklığı yüksek tutulmuşsa veya doğrulama kapatılmışsa, yeni PHP dosyaları hemen devreye girmeyebilir.

Yeni PHP dosyaları neden görünmeyebilir?

OPcache yalnızca eski dosyaları değil, bazı durumlarda dosya yoluna bağlı önbellek bilgisini de koruyabilir. Bu nedenle yeni eklenen bir dosya, autoload mekanizması, include yolu veya framework cache katmanı ile birlikte değerlendirildiğinde beklenenden farklı davranabilir.

Dosya değişikliği kontrolü gecikmiş olabilir

opcache.validate_timestamps aktifse PHP, dosyalarda değişiklik olup olmadığını belirli aralıklarla kontrol eder. Bu aralık opcache.revalidate_freq değeriyle yönetilir. Değer birkaç saniye olsa bile yoğun dağıtım anlarında geliştirici, değişikliğin uygulanmadığını sanabilir.

Zaman damgası doğrulaması kapalı olabilir

Performans için bazı üretim ortamlarında opcache.validate_timestamps kapatılır. Bu ayarda PHP, dosya değişikliklerini otomatik kontrol etmez. Yeni dosya yükleseniz bile OPcache resetlenene kadar uygulama eski derlenmiş kodla çalışabilir. Kurumsal projelerde bu tercih yapılacaksa dağıtım sürecine mutlaka OPcache temizleme adımı eklenmelidir.

Yanlış PHP-FPM havuzu veya kullanıcı etkileniyor olabilir

Birden fazla PHP sürümü, ayrı PHP-FPM pool yapısı veya farklı site kullanıcıları varsa reset işlemi beklediğiniz ortamda çalışmayabilir. Örneğin komut satırında reset çalıştırmak, web sunucusunun kullandığı PHP-FPM sürecini etkilemeyebilir. Bu ayrım özellikle panel tabanlı hosting hizmetlerinde sık görülür.

OPcache reset nasıl yapılır?

En doğru yöntem, kullandığınız altyapıya göre değişir. Paylaşımlı ortamlarda kontrol panelinde PHP ayarları, önbellek yönetimi veya hizmet yeniden başlatma seçenekleri olabilir. Yönetilen sunucularda destek ekibi OPcache reset işlemini uygulayabilir. Kendi VPS veya dedicated sunucunuz varsa PHP-FPM servisinin yeniden yüklenmesi çoğu zaman yeterlidir.

Bazı durumlarda geçici bir PHP dosyasıyla reset yapılabilir. Bu yöntem yalnızca yetkili kullanıcıların erişebileceği güvenli bir ortamda kullanılmalı ve işlemden sonra dosya mutlaka silinmelidir.

<?php
if (function_exists('opcache_reset')) {
    opcache_reset();
    echo 'OPcache resetlendi';
} else {
    echo 'OPcache aktif değil veya reset fonksiyonu kullanılamıyor';
}

Bu dosyayı herkese açık bırakmak güvenlik riski oluşturur. Kötü niyetli kişiler bu endpoint’i çağırarak performans sorunlarına veya beklenmedik davranışlara neden olabilir. Mümkünse IP kısıtlaması, temel kimlik doğrulama veya panel üzerinden güvenli işlem tercih edilmelidir.

Sorunun OPcache kaynaklı olup olmadığını nasıl anlarsınız?

Önce dosyanın gerçekten doğru dizine yüklendiğini kontrol edin. Büyük-küçük harf farkları Linux tabanlı sistemlerde önemlidir; Class.php ile class.php aynı dosya değildir. Ardından dosya izinlerini, sahipliği ve include yolunu inceleyin.

Yeni eklenen kodu basit bir çıktı ile test etmek yanıltıcı olabilir; çünkü istek farklı PHP sürümüne veya farklı document root dizinine gidiyor olabilir. Bu nedenle phpinfo() çıktısında OPcache ayarlarını, çalışan PHP sürümünü ve yüklenen yapılandırma dosyasını kontrol etmek faydalıdır.

WordPress sitelerde dikkat edilmesi gerekenler

WordPress’te tema dosyası, özel eklenti veya mu-plugin güncellemelerinde sorun yalnızca OPcache olmayabilir. Sayfa önbelleği, object cache, CDN cache ve tarayıcı cache aynı anda devreye girebilir. Bu nedenle önce uygulama önbelleklerini temizlemek, ardından PHP tarafını kontrol etmek daha sağlıklı bir sıralamadır.

Özel eklenti geliştirirken autoload yapısı kullanılıyorsa Composer autoload dosyasının güncellenip güncellenmediğini de kontrol edin. Yeni sınıf dosyası sunucuya yüklenmiş olsa bile autoload haritası eskiyse PHP dosyayı çağırmayabilir.

Canlı ortamda güvenli yayın alma yaklaşımı

Canlı projelerde OPcache reset işlemi plansız yapılmamalıdır. Trafiğin yoğun olduğu saatlerde tüm cache’in boşaltılması kısa süreli CPU artışına neden olabilir. Daha güvenli yaklaşım, dağıtım sırasında dosyaları eksiksiz aktarmak, gerekli bağımlılıkları hazırlamak, ardından kontrollü biçimde OPcache resetlemektir.

Birden fazla sunucu kullanılan yapılarda işlem her node üzerinde uygulanmalıdır. Aksi halde bazı kullanıcılar yeni kodu görürken bazıları eski sürümle karşılaşabilir. Bu tip tutarsızlıklar ödeme, üyelik veya yönetim paneli gibi kritik alanlarda ciddi operasyonel sorunlara yol açabilir.

OPcache kaynaklı görünmeme sorunlarında aceleyle dosya silip yeniden yüklemek yerine; PHP sürümü, dosya yolu, önbellek katmanları ve reset kapsamı birlikte değerlendirilmelidir. Böylece yeni PHP dosyalarının devreye alınması daha öngörülebilir hale gelir ve hosting altyapısında gereksiz kesinti riski azaltılır.