Laravel Config Cache Hatası: Nedenleri ve Kalıcı Çözüm

Laravel config cache hatası, çoğu zaman önbelleğin kendisinden değil; uygulamanın yapılandırmayı nereden okuduğunun yanlış anlaşılmasından çıkar. Özellikle .env dosyası güncellendiği hâlde eski veritabanı, e-posta veya uygulama adresinin kullanılmaya devam etmesi; env() çağrılarının üretimde null dönmesi ve deployment sonrasında 500 hatası görülmesi aynı kök nedene bağlanabilir.

Bu rehberde önce çalışan yapılandırmayı doğrulayacağız, sonra yalnızca gerekli önbelleği temizleyip yeniden oluşturacağız. Komutları körlemesine tekrarlamak yerine, hangi katmanın eski kaldığını belirleyen güvenli bir kontrol sırası izleyeceğiz. Böylece sorun yeniden oluştuğunda hangi dosyaya, komuta veya servise bakmanız gerektiği de netleşecek.

Laravel config cache ne yapar?

Laravel, config klasöründeki yapılandırma dosyalarını normalde uygulama açılırken okur. php artisan config:cache komutu bu değerleri tek bir önbellek dosyasında birleştirir. Üretim ortamında dosya sistemi erişimini azaltan bu işlem yararlıdır; ancak yapılandırma değiştiğinde önbelleğin de yeniden oluşturulması gerekir.

Resmî Laravel yapılandırma dokümantasyonuna göre config cache oluşturulduktan sonra istekler ve Artisan komutları sırasında .env dosyası yüklenmez. Bu nedenle env() yalnızca config/*.php dosyalarında kullanılmalı; controller, service, job veya başka uygulama kodlarında değerler config() ile okunmalıdır.

Doğru ve hatalı kullanım arasındaki fark

Örneğin bir servis sınıfında doğrudan env('MAIL_HOST') okumak yerel ortamda çalışabilir, fakat config cache açıkken beklenmeyen sonuç üretebilir. Değeri önce config/mail.php içinde tanımlayıp uygulama kodunda config('mail.mailers.smtp.host') ile okumak gerekir.

// config/services.php
'billing' => [
    'endpoint' => env('BILLING_API_URL'),
    'token' => env('BILLING_API_TOKEN'),
],

// app/Services/BillingClient.php
$endpoint = config('services.billing.endpoint');
$token = config('services.billing.token');

API anahtarını kod içine, log mesajına veya herkese açık repoya yazmayın. Ortam dosyasının görevini ve güvenli kullanımını daha ayrıntılı görmek için Laravel .env dosyası rehberine geçebilirsiniz.

Hata belirtilerini doğru sınıflandırın

“Config cache hatası” tek bir hata mesajı değildir. Belirtiyi sınıflandırmak, gereksiz cache temizleme döngüsünü önler:

• Eski değer kullanılıyor: .env değişmiştir ancak config cache yeniden oluşturulmamıştır.
• env() null dönüyor: Uygulama kodunda doğrudan env() çağrısı vardır.
• config:cache çalışırken hata oluşuyor: Bir config dosyasında söz dizimi, eksik sınıf veya uygun olmayan bir değer bulunabilir.
• Web isteği ve CLI farklı davranıyor: PHP sürümü, çalışma kullanıcısı, sistem ortam değişkenleri veya dosya izinleri farklı olabilir.
• Queue eski ayarla devam ediyor: Uzun çalışan worker süreçleri deployment sonrasında yeniden başlatılmamıştır.

Önce php artisan about --only=environment ile ortamı, ardından ilgili yapılandırmayı php artisan config:show database gibi bir komutla inceleyin. Bu komutlar Laravel’in o anda gördüğü yapılandırmayı gösterir. Çıktıyı paylaşırken parola, anahtar ve bağlantı bilgilerini mutlaka maskeleyin.

Adım adım Laravel config cache hatası çözümü

Aşağıdaki sıra, önce teşhis yapıp sonra önbelleği yeniden üretir. Canlı sunucuda işlemden önce güncel yedek ve geri dönüş planı bulundurmanız gerekir. Shared hosting kullanıyorsanız terminal komutlarını doğru PHP sürümüyle çalıştırdığınızdan emin olun; kurulum ayrıntıları için Laravel shared hosting yayınlama rehberine bakabilirsiniz.

1. Ortamı ve uygulama durumunu doğrulayın

php -v
php artisan about --only=environment
php artisan config:show app

Beklediğiniz APP_ENV, debug durumu ve uygulama adresi görünmüyorsa henüz cache üretmeyin. Yanlış dizinde komut çalıştırmadığınızı, web sunucusu ile terminalin aynı PHP sürümünü kullandığını ve doğru ortam dosyasının bulunduğunu kontrol edin.

2. Config dışındaki env çağrılarını bulun

grep -R "env(" app routes database --line-number

Windows ortamında editörünüzün genel aramasını kullanabilirsiniz. Bulduğunuz çağrıları doğrudan silmek yerine gerekli anahtarı uygun bir config/*.php dosyasına taşıyın ve uygulama tarafında config() ile okuyun. Paket kodlarını değiştirmeyin; ilgili paketin yayımlanabilir config dosyasını ve resmî dokümantasyonunu kontrol edin.

3. Yalnızca config cache’i temizleyin

php artisan config:clear
php artisan config:show app

Bu aşamada doğru değer görünüyorsa kök neden büyük olasılıkla eski config cache’tir. optimize:clear daha geniş kapsamlıdır ve resmî deployment dokümantasyonuna göre optimize komutunun ürettiği dosyaların yanında varsayılan cache sürücüsündeki anahtarları da temizler. Bu yüzden canlı sistemde etkisini değerlendirmeden ilk refleks olarak kullanmayın.

4. Config dosyalarını doğrulayıp cache’i yeniden oluşturun

php artisan config:cache
php artisan config:show app
php artisan config:show database

Komut hata verirse mesajın ilk anlamlı satırını inceleyin. Sorun düzelmeden cache komutunu tekrar tekrar çalıştırmak yerine, yakın zamanda değişen config dosyasını ve kullanılan sınıfları kontrol edin. Uygulamanın bootstrap/cache ve storage dizinlerine yazabilmesi gerekir; izinleri herkese açık hâle getirmek güvenli bir çözüm değildir.

5. Uzun çalışan servisleri yeniden yükleyin

Queue worker, Octane veya Reverb gibi uzun çalışan süreçler bellekteki eski kod ve ayarlarla devam edebilir. Güncel Laravel sürümlerinde deployment sonrasında php artisan reload kullanılabilir; farklı bir süreç yöneticiniz varsa onun güvenli yeniden başlatma akışını uygulayın. Queue tarafını ayrıca yapılandırmak için Laravel Queue sistemi rehberini inceleyebilirsiniz.

Deployment sırasını kalıcı hâle getirin

Kalıcı çözüm, elle cache temizlemekten çok deployment sırasını standartlaştırmaktır. Bağımlılıklar ve uygulama dosyaları hazırlandıktan, ortam değişkenleri doğrulandıktan sonra optimize komutları çalıştırılmalı; son adımda uzun çalışan servisler yeniden yüklenmelidir. Resmî Laravel deployment rehberi, üretimde php artisan optimize komutunu deployment sürecine eklemeyi önerir.

composer install --no-dev --prefer-dist --optimize-autoloader
php artisan about --only=environment
php artisan optimize
php artisan reload

Bu örnek her sunucuya aynen uygulanacak evrensel bir script değildir. Migration, bakım modu, health check ve rollback adımları projenin mimarisine göre eklenmelidir. Otomasyonu GitHub üzerinden kuruyorsanız GitHub Actions ile otomatik deployment rehberi güvenli bir başlangıç planı sunar.

Production kontrol listesi

• APP_ENV=production ve APP_DEBUG=false değerlerini doğrulayın.
• .env dosyasını sürüm kontrolüne eklemeyin ve web üzerinden erişilebilir bırakmayın.
• storage ile bootstrap/cache dizinlerinde yalnızca gerekli yazma izinlerini verin.
• Cache sonrasında kritik veritabanı, e-posta ve harici API yapılandırmalarını kontrollü test edin.
• Queue ve zamanlanmış görevlerin yeni ayarları kullandığını doğrulayın; cron tarafı için Laravel Schedule rehberinden yararlanın.
• Health check başarısız olursa önceki çalışan sürüme dönebilecek bir rollback adımı hazırlayın.

Sık yapılan hatalar ve güvenlik notları

chmod -R 777 gibi geniş izinler vermek, config cache sorununu çözmek yerine sunucunun güvenlik yüzeyini büyütür. Benzer şekilde APP_DEBUG=true ayarını canlı sitede açık bırakmak hassas yapılandırma bilgilerinin ziyaretçilere gösterilmesine yol açabilir. Daha geniş bir kontrol için Laravel güvenlik kontrol listesini uygulayın.

optimize:clear komutunu çalıştırdıktan sonra sorun geçici olarak kayboluyorsa bunu kalıcı çözüm saymayın. Hangi config anahtarının yanlış okunduğunu, bu değerin nerede çağrıldığını ve deployment sırasında cache’in hangi kullanıcıyla üretildiğini belirleyin. Log kaydında gizli değerleri göstermeden hata zamanı, çalışan komut, uygulama sürümü ve ilgili config anahtarının adını kaydetmek teşhisi kolaylaştırır.

Sonuç

Laravel config cache hatasını çözmenin güvenilir yolu; önce uygulamanın gördüğü ortamı doğrulamak, env() kullanımını config dosyalarıyla sınırlamak, önbelleği kontrollü biçimde yeniden oluşturmak ve uzun çalışan servisleri yeniden yüklemektir. Aynı kontrolleri deployment sürecine eklediğinizde, her .env değişikliğinden sonra elle müdahale etme ihtiyacı azalır ve geri dönüş noktası daha öngörülebilir olur.

Sık sorulan sorular

Laravel config cache nasıl temizlenir?

Yalnızca yapılandırma önbelleğini kaldırmak için php artisan config:clear kullanılır. Ardından doğru değerleri doğrulayıp üretimde php artisan config:cache ile cache’i yeniden oluşturabilirsiniz.

Config cache açıkken env neden null döner?

Cache oluşturulduktan sonra Laravel .env dosyasını isteklerde ve Artisan komutlarında yüklemez. Bu nedenle env() çağrısını yalnızca config dosyalarında kullanın; uygulama kodunda değeri config() ile okuyun.

config:clear ile optimize:clear aynı mı?

Hayır. config:clear yapılandırma önbelleğine odaklanır. optimize:clear daha geniş kapsamlı optimize dosyalarını ve güncel Laravel dokümantasyonuna göre varsayılan cache sürücüsündeki anahtarları da temizleyebilir.

Local ortamda config:cache kullanılmalı mı?

Laravel dokümantasyonu, yapılandırma değerleri geliştirme sırasında sık değiştiği için bu komutun genellikle yerel geliştirmede çalıştırılmamasını önerir. Asıl kullanım alanı kontrollü üretim deployment sürecidir.

Queue worker config değişikliğini hemen görür mü?

Uzun çalışan worker süreçleri eski kodu ve yapılandırmayı bellekte tutabilir. Cache yeniden oluşturulduktan sonra süreçleri kullandığınız process manager veya Laravel’in desteklediği reload mekanizmasıyla güvenli biçimde yeniden başlatın.