Üzerinde çalıştığım makinede çalışıyor: Üretimde kaybolan env() gizemi

“Ama da, yerel ortamımda hiç sorun yok.”

Bir özelliği tamamladınız. Yerel ortamda test ettiniz, çalışıyor. Üretime geçtiniz.

Ve aniden, bir ortam değişkenine bağlı olan bir şey çalışmamaya başladı. Örneğin, bir ödeme geçidi ile olan entegrasyonunuz boş bir anahtar kullanıyor. Dış bir API’nin istemcisi ise nereye gideceğini bilmiyor.

Log dosyasını açıyorsunuz, .env dosyasını kontrol ediyorsunuz, değişken orada, her şey tam. Tekrar yerel ortamda çalıştırıyorsunuz: çalışıyor. Üretimde ise: null. 🙃

Eğer bu korkulu sahneyi yaşadıysanız, muhtemelen suçlu tek bir şeydir: env() fonksiyonunu kullanmamanız gereken bir yerde kullandınız.

Masum görünen kod

Diyelim ki bir API ile iletişim kurmak üzere bir servis oluşturmanız gerekiyor. Anahtara ihtiyacınız var, bu yüzden en mantıklısını yapıyorsunuz:

class FreteService
{
    public function __construct()
    {
        // doğru görünüyor, değil mi? .env'den aldım ve oldu
        $this->apiKey = env('FRETE_API_KEY');
        $this->baseUrl = env('FRETE_API_URL', 'https://api.frete.com');
    }
}

Yerelde bu harika çalışıyor. Laravel, .env dosyasını okuyor, FRETE_API_KEY anahtarını buluyor ve devam ediyor.

Ancak sorun şu ki, bu kod bir zaman bombası içeriyor. Ve pim, her ciddi dağıtımın çalıştırdığı bir komutla çekiliyor.

config:cache ne yapar (ve neden sizi kandırır)

.env dosyasını diskten okumak ve her istek başına ayrıştırmak yavaştır. Bu nedenle, üretimde resmi öneri şudur:

php artisan config:cache

Bu komut, tüm config/ dosyalarınızı tek bir optimize edilmiş ve önbellekli PHP dosyası haline getirir. Bundan sonra, Laravel .env dosyasını bir daha okumaz — önbelleği okur.

İşte burada bir tuzak var: config önbelleğe alındığında, env() fonksiyonu, yapılandırma dosyalarında olmayan her şey için null döndürmeye başlar.

Yani, hizmetinizdeki env('FRETE_API_KEY') ifadesi üretimde null olur. Yerelde muhtemelen hiç config:cache komutunu çalıştırmadınız, bu yüzden “sadece makinenizde çalışıyor”. Hata daima oradadır ama uyuyordur.

Altın kural

env() yalnızca config/ klasöründeki dosyaların içinde çağrılmalıdır. Asla servislerde, denetleyicilerde, modellerde, işler veya başka herhangi bir yerde.

Doğru yol şudur: env()‘yi yapılandırma dosyasında okursunuz ve sonra uygulamanızın geri kalanında config() ile okursunuz.

Öncelikle bir yapılandırma dosyası oluşturun (veya mevcutsa kullanın):

// config/frete.php
return [
    'api_key'  => env('FRETE_API_KEY'),
    'base_url' => env('FRETE_API_URL', 'https://api.frete.com'),
];

Daha sonra, hizmette env() çağrısını config() ile değiştirin:

class FreteService
{
    public function __construct()
    {
        // artık cache'e dayanıyor olacak olan yapılandırmadan okuyor
        $this->apiKey  = config('frete.api_key');
        $this->baseUrl = config('frete.base_url');
    }
}

Artık env() doğru yerde, config:cache değeri de birlikte paketleniyor ve üretim yerel ortamla aynı şekilde çalışıyor.

Pratikte nasıl kullanılmalı

Kural her zaman aynıdır, her bağlamda:

• API anahtarı bir serviste → config/services.php dosyasında bir giriş oluşturun ve config('services.frete.key') ile okuyun. (Ayrıca, config/services.php zaten bunun için mevcut.)
• Bir denetleyicide özellik bayrağı → config('app.features.novo_checkout') kullanmak, env('NOVO_CHECKOUT') yerine.
• Bir işin zaman aşımı → config/queue.php dosyasına koyun veya özel bir yapılandırma oluşturun ve orada config('...') çağırın.

Zihinsel kural basit: Eğer env() yazmaya hazırlanıyorsanız ve dosya config/ altında değilse, durun. Hemen üretim hatasına dönüşebilir.

Tuzağın tuzağı

“Ama ben env() kullanıyorum ve çalışıyor!” — evet, bu doğru, config:cache komutunu çalıştırmadığınız sürece çalışıyor.

Tehlike tam burada: geliştirme sırasında her şey geçiyor, testler geçiyor, PR onaylanıyor. Hata, yalnızca önbelleği çalıştıran ilk dağıtımda ortaya çıkıyor. Ve o zaman en kötü anda üretimde hata ayıklamaya başlıyorsunuz.

Artık kodunuzun temiz olup olmadığını test etmek ister misiniz? Yerel ortamda bunu çalıştırın:

php artisan config:cache

Eğer bir şey kırılırsa, env()‘lerinizi yanlış yerlerde bulmuşsunuz demektir. Geliştirme ortamına dönmek için:

php artisan config:clear

Bonus: peki şimdi?

Projenizdeki env( ifadesini config/ dışında aramak için bir grep çalıştırın. Eminim ki en az bir yerde, genellikle “her zaman çalışıyordu” diye düşündüğünüz bir hizmette gizlenmiş bir tane var.

Aynı zamanda, config/services.php dosyasını kontrol edin. Üçüncü taraf hizmetlerin kimlik bilgilerini saklamak için yapılmıştır ve birçok kişi bunun varlığını dikkate almaz.

Sekmeyi kapatmadan önce

env() yapılandırmanın dışındaysa, üretim ortamında ortaya çıkması zor bir hata olarak bekliyor.

Üretimde kaybolan bir değeri ararken bir gününüzü kaybettiğiniz oldu mu? Hangi değer kaybıyla karşılaştığınızı yorumlarda paylaşın — bunu yalnızca benim yaşayıp yaşamadığımı merak ediyorum. 👀

Laravel’deki bu tür tuzaklar size yardımcı oluyorsa, bu yazıyı kaydedin ve beni takip edin: burada daha fazlası var.