Laravel route cache, uygulamanın rota kayıtlarını önceden derleyerek üretim isteklerinde rota tanımlama maliyetini azaltır. Özellikle yüzlerce yol içeren projede dağıtımın yararlı bir adımı olabilir. Ancak yeni route ekledikten sonra önbelleği yenilemezseniz eski rota haritası çalışmaya devam eder. Ayrıca route cache, yavaş veritabanı sorgusunu veya ağır controller kodunu kendiliğinden hızlandırmaz. Bu rehberde route:cache, route:clear, route:list ve dağıtım sonrası doğrulamayı güncel Laravel belgelerine dayanarak açıklıyoruz.
Laravel route cache nedir?
Laravel uygulaması normalde rota dosyalarını okuyup kayıtları hazırlar. Route cache, bu kayıtları önceden oluşturulmuş dosyadan yükleyerek her istekte rota tanımlama işini azaltır. Laravel’in güncel dağıtım belgesi, çok sayıda rota bulunan uygulamalarda php artisan route:cache komutunu önerir ve kazancın rota kayıt aşamasında olduğunu açıklar. Bu, bütün HTTP yanıtının otomatik olarak önbelleğe alındığı anlamına gelmez. Kullanıcıya özel içerik, controller işlemi ve veritabanı sorguları normal çalışır.
Route cache’i sayfa önbelleğiyle karıştırmayın. Sayfa önbelleği hazır HTML veya yanıtı saklayabilir; rota önbelleği hangi isteğin hangi uygulama koduna gideceğini hazırlama işini kolaylaştırır. Bu yüzden bir sayfa 2 saniyede açılıyorsa yalnızca route cache komutunun onu belirgin biçimde hızlandıracağını varsaymayın. Önce toplam süreyi, veritabanı sorgularını ve rota kayıt payını ölçün. Küçük projede kazanım sınırlı olabilir; dağıtım karmaşıklığına değip değmediğini test edin.
Route cache nasıl oluşturulur?
Projenin kök dizininde, doğru PHP ve bağımlılık sürümleriyle php artisan route:cache çalıştırılır. Komut rota tanımlarının o dağıtımdaki durumuna göre önbellek üretir. Üretimde bunu elle arada sırada değil, sürüm yayımlama sürecinin bir parçası olarak çalıştırmak daha güvenilirdir. Yerel geliştirmede her yeni route denemesi sonrası önbellek yenilemek gerekeceği için sürekli açık tutmak zorunlu değildir. Komut hata verirse tam hata mesajını okuyun; rastgele framework dosyalarını silmeyin.
php artisan route:cache
php artisan route:list
php artisan route:clearBu üç komutun görevleri farklıdır. route:cache derlenmiş rota haritasını oluşturur. route:list kayıtlı yolları, yöntemleri, adları ve eylemleri incelemeye yardım eder. route:clear rota önbelleğini temizler; kodu silmez. Komutların çalışması, kullanıcı açısından tüm kritik yolların doğru yanıt verdiğini ispatlamaz. Komuttan sonra gerçek HTTP testleri yapın.
Yeni rota neden görünmüyor?
Dağıtımdan sonra yeni URL 404 veriyor ama rota dosyasında tanım mevcutsa, eski route cache ilk kontrol noktasıdır. Laravel’in rota belgesi, yeni rotaların görünmesi için önbelleğin yeniden üretilmesi gerektiğini belirtir. Önce doğru sürümün sunucuda çalıştığını ve kodun beklendiği gibi dağıtıldığını doğrulayın. Ardından rota listesini ve önbellek oluşturma adımının sonuçlarını inceleyin. Eski cache’i temizlemek geçici tanı olabilir; kalıcı çözüm dağıtım sürecinde yeni cache’i doğru sürümle oluşturup doğrulamaktır.
Dağıtım sırası nasıl kurulmalı?
Önbellek, oluşturulduğu kod sürümünün rota tanımlarını temsil etmelidir. Bu nedenle önce yeni kod ve bağımlılıklar hedef ortama hazırlanır; gerekli ortam ayarları ve veritabanı değişiklikleri denetlenir; ardından o sürümün dizininde route:cache çalıştırılır. Son adımda trafik alan uygulamada birkaç kritik URL denenir. Sürüm klasörleriyle çalışan dağıtımlarda komutu eski canlı dizinde çalıştırıp ardından yeni sürüme geçmek yanlış rota haritası bırakabilir. Container kullanan ekipler de önbelleğin imaj hazırlanırken mi yoksa çalışma ortamında mı üretildiğini açıkça belirlemelidir.
Dağıtımı otomatikleştiriyorsanız komutun başarısız çıkış kodunu yok saymayın. Hatalı önbellekle trafiği yeni sürüme aktarmak yerine yayını durdurup hatayı inceleyin. Birden fazla uygulama düğümü varsa hepsinin aynı sürüm ve aynı önbellekle çalıştığını doğrulayın. Yalnızca bir sunucuda komut çalıştırmak diğer sunuculardaki eski cache’i değiştirmez. Paylaşılan dosya sistemi kullansanız bile dağıtım mimarinizi test ederek hangi dosyanın ne zaman okunduğunu belirleyin.
Geri alma planını da önceden yazın. Önceki sürüme dönüldüğünde yeni sürümün rota önbelleği eski kodla eşleşmeyebilir. Geri alınan sürüm için önbelleğin yeniden üretilmesi veya o sürüme ait hazır cache’in geri yüklenmesi gerekir. Bu adımı uygulama sağlık kontrolleriyle birlikte denemek, acil durumda el yordamıyla komut çalıştırma riskini azaltır.
Route list ile ne kontrol edilir?
php artisan route:list komutu uygulamanın gördüğü yolları incelemek için ilk araçtır. Beklenen URI’yi, HTTP yöntemini, rota adını ve bağlı eylemi karşılaştırın. Aynı yolun farklı GET ve POST yöntemleriyle kayıtlı olması normal olabilir; hangi yöntemi denediğinizi not edin. Laravel belgelerinde liste çıktısını daraltan seçenekler de vardır. Kullandığınız sürümün php artisan route:list --help çıktısını okuyarak uygun filtreyi seçin. Liste, isteğin middleware ve uygulama mantığından geçip başarılı yanıt verdiğinin kanıtı değildir.
Örneğin yönetim panelindeki bir POST endpoint’i listede görünüyor olabilir ama CSRF, kimlik doğrulama veya yetki kontrolü nedeniyle gerçek istekte reddedilebilir. Benzer şekilde isimli rota doğru adla kayıtlıyken bir controller içinde yanlış parametreyle URL oluşturulması ayrı bir hatadır. Bu yüzden rota listesi ile uçtan uca istek testini birlikte kullanın. Önbellek hatası ile uygulama hatasını ayırmak gereksiz silme ve yeniden dağıtımı önler.
404 ve 405 hatasını nasıl ayırırsınız?
Yeni bir URL 404 dönüyorsa rota kaydının mevcut sürümde bulunup bulunmadığını kontrol edin. 405 Method Not Allowed yanıtı ise yolun var olup denenen HTTP yöntemini kabul etmediğine işaret edebilir. Örneğin yalnızca POST olarak tanımlanmış bir yola tarayıcı adres çubuğundan GET isteği göndermek bu durumu doğurur. Önbelleği tekrar tekrar temizlemek yerine istek yöntemini, rota tanımını ve formun hedefini karşılaştırın. Gerçek yanıtın web sunucusu, proxy veya Laravel katmanından geldiğini de günlüklerle teyit edin.
Bir başka olasılık, benzer kalıpların beklenmeyen sırayla eşleşmesidir. Sabit bir yol ile geniş parametreli bir yol birbirini etkiliyorsa Laravel’in rota sıralaması ve kısıtlarını inceleyin. Önbellek eski tanımı saklayarak belirtiyi görünür kılabilir ama yanlış eşleşmenin kök nedeni rota tasarımı olabilir. Değişiklik sonrası hem sabit URL’yi hem parametreli örnekleri yeniden test edin.
Route cache diğer önbelleklerden nasıl ayrılır?
config:cache yapılandırma dosyalarını, view:cache Blade görünümlerini, event:cache ise olay dinleyicisi eşlemelerini hazırlar. Her birinin yenilenme nedeni farklıdır. Ortam değişkeni değiştiğinde rota önbelleğini temizlemek tek başına yapılandırma önbelleğini güncellemez. Blade şablonundaki bir sorunu rota cache’e bağlamak da tanıyı geciktirir. Laravel’in dağıtım belgesi bu optimizasyonları ayrı komutlar olarak tanımlar; hangisini uygulayacağınızı değişen kaynağa göre seçin.
php artisan optimize birden fazla optimizasyonu tek adımda uygulamak için kullanılabilir. Fakat optimize:clear komutunu üretimde gelişigüzel çalıştırmayın. Güncel Laravel dağıtım belgesi, bu komutun optimize ile üretilen dosyalar yanında varsayılan cache sürücüsündeki anahtarları da temizlediğini belirtir. Uygulamanız aynı sürücüyü iş verisi, geçici durum veya hızlandırma için kullanıyorsa beklenmedik etkiler görülebilir. Sadece rota önbelleğini tanılamak istiyorsanız kapsamı daha dar olan route:clear ile başlayın; hangi cache sürücüsünü kullandığınızı yine de bilin.
Closure rotaları hakkında sürüm farkı
İnternetteki eski Laravel rehberlerinde “closure kullanan rota asla cache’lenemez” gibi kesin cümleler görebilirsiniz. Bu davranış Laravel sürümüne ve kullanılan derleme mekanizmasına bağlıdır; eski bir hata mesajını bütün sürümlere taşımayın. Güncel Laravel rota belgesinde closure ile rota tanımı örnekleri ve rota önbelleği anlatımı birlikte bulunur. Projenizdeki sürümü php artisan --version ile öğrenin, o sürümün resmi belgesine bakın ve route:cache komutunu test ortamında gerçekten çalıştırın.
Komut belirli bir rota nedeniyle başarısız olursa hata mesajında gösterilen dosya ve satıra odaklanın. Rotayı sırf bir blog yazısı öyle dedi diye controller’a taşımak zorunda değilsiniz; fakat uygulamanızın sürümü, serileştirilemeyen bağımlılık veya kullanılan paket böyle bir dönüşüm gerektirebilir. Çözüm, testle doğrulanmış proje bağlamına dayanmalıdır. Framework yükseltmesi yaparken önbellek davranışını tekrar test etmek de yerindedir.
Üretime çıkmadan önce test listesi
Önce beklenen rota sayısını ve kritik rota adlarını kayıt altına alın. Ardından yeni sürümün test ortamında cache üretimini çalıştırın. Ana sayfa gibi herkese açık GET yollarını, form gönderimi gibi POST yollarını, oturum açmayı gerektiren yolları ve API endpoint’lerini örnekleyin. Parametre alan bir rotada hem geçerli hem geçersiz değer deneyin. Dil veya alan adı bazlı rota grupları varsa her birinden örnek seçin. Bu yaklaşım, “komut başarılı” sonucunun ardında kalan davranış hatalarını yakalar.
Test isteğinin sonucunda yalnızca durum koduna bakmayın. 200 yanıtı yanlış sayfanın açıldığı durumda da dönebilir. Beklenen controller çıktısını, yönlendirme hedefini, yetki sınırını ve gerekli yanıt başlıklarını kontrol edin. POST testlerinde test verisini temiz tutun; ödeme veya gerçek kullanıcı işlemlerini deneme amacıyla tetiklemeyin. Otomatik test varsa dağıtımdan önce ve sonra aynı kritik senaryoları çalıştırın. Sağlık kontrolü, route cache’in güncelliğine dolaylı güvence verebilir ama ayrıntılı testin yerini tutmaz.
Cache dosyasının oluşturulma zamanını körlemesine başarı ölçütü saymayın. Saat ayarı veya dosya taşıma işlemi yanıltıcı olabilir. Dağıtım günlüğünde hangi kod revizyonunun çalıştığı, komutun çıkış durumu ve canlı isteğin hangi sunucuya gittiği daha güçlü kanıttır. Çok sunuculu bir sistemde her düğümü ayrı test etmek veya yük dengeleyici üzerinden tekrarlı örnek istemek gerekir. Hata yalnızca aralıklı görülüyorsa farklı düğümlerde eski ve yeni önbelleklerin karışması olasıdır.
Performans kazancı nasıl ölçülür?
Önce karşılaştırılabilir bir başlangıç ölçümü alın. Aynı kod ve veriyle, route cache kapalı ve açık durumları benzer yük altında test edin. İlk istek, PHP opcode önbelleği ve uygulama ısınması yüzünden sonraki isteklerden farklı olabilir. Birkaç kez ölçüp medyan veya yüzdelik süreleri karşılaştırmak daha anlamlıdır. Sunucunun CPU kullanımı ve eşzamanlı istek sayısını da kaydedin. Ölçüm sırasında CDN, tam sayfa önbelleği veya farklı veri seti sonucu örtüyorsa route cache’e ait katkıyı ayıramazsınız.
Uygulamanın toplam gecikmesinin çoğu dış API veya veritabanından geliyorsa rota kayıt süresindeki azalma kullanıcıya çok küçük yansır. Böyle bir durumda sorgu profillemesi, indeksler ve yanıt önbelleği daha büyük kazanç sağlayabilir. Öte yandan rota sayısı yüksek ve istek başına framework başlatma maliyeti belirginse route cache faydalı olabilir. Tek bir evrensel yüzde veya milisaniye kazancı vaat etmeyin. Sonuç Laravel sürümü, rota sayısı, PHP sürümü, sunucu ve trafik düzenine bağlıdır.
Hata halinde güvenli teşhis sırası
Önce semptomu yazın: Hangi URL, hangi yöntem, hangi ortam, hangi saat ve hangi yanıt? Son dağıtımda rota dosyası, servis sağlayıcı veya paket rotaları değişti mi? Sonra doğru uygulama dizininde php artisan --version ve php artisan route:list çıktılarını inceleyin. Komutun hata metnini saklayın; özellikle dosya yolu ve ilgili rota adına bakın. Önceki çalışan sürümün davranışıyla karşılaştırın. Her şeyi aynı anda temizleyip tekrar oluşturmak, asıl nedeni görünmez kılabilir.
Rota listesi beklenen yolu göstermiyorsa dağıtımın doğru kodu içerdiğini kontrol edin. Yol listede var ama HTTP isteği başarısızsa middleware, yetki, web sunucusu yönlendirmesi ve controller günlüklerine geçin. Yalnızca cache açıkken sorun yaşanıyorsa test ortamında route:clear ile farkı gözlemleyin; ardından route:cache ile yeniden üretin. Üretimde cache temizleme kararını trafik ve geri alma planıyla birlikte verin. Başarısızlık sürüyorsa paketlerin rota kayıt adımlarını ve sürüm uyumluluğunu inceleyin.
Container ve çok sunuculu dağıtım
Container imajında derlenmiş rota önbelleği tutuyorsanız imajın oluşturulduğu kod ile çalışan kodun aynı olduğundan emin olun. Çalışma anında bağlanan farklı bir uygulama dizini imajdaki cache’i eski bırakabilir. Ortam ayarları rota kayıtlarını etkiliyorsa hangi değişkenlerin derleme anında, hangilerinin çalışırken mevcut olduğunu belirleyin. Her sürüm için önbelleği tutarlı biçimde üretin. Yeni ve eski imajları aynı anda trafik altında çalıştırıyorsanız davranış farklarının kademeli yayımlama boyunca görülebileceğini hesaba katın.
Birden çok sunucunun her birinde yerel dosya sistemi varsa tek sunucudaki Artisan komutu diğerlerini değiştirmez. Dağıtım otomasyonu komutu her hedefte çalıştırmalı ya da önceden hazırlanmış aynı sürüm dosyalarını güvenle dağıtmalıdır. Paylaşılan önbellek çözümü kullanılsa bile dosya ve uygulama kodu arasında sürüm uyuşmazlığı yaratmayın. Özellikle aralıklı 404’lerde isteğin hangi düğüme gittiğini kaydetmek teşhisi hızlandırır.
Sık sorulan sorular
Route cache her Laravel projesinde zorunlu mu?
Hayır. Laravel üretim dağıtımında yararlı bir optimizasyon olarak sunar; fayda rota sayısı ve uygulamanın özelliklerine göre değişir. Küçük projede bakım ve dağıtım adımının maliyetini de hesaba katın. Performans kararı ölçüme dayanmalıdır.
Yeni rota ekledim, neden 404 görüyorum?
Önce doğru kod sürümünü ve HTTP yöntemini doğrulayın. Route cache etkinse yeni tanımların görünmesi için önbelleği yeniden oluşturun. Ardından route:list ve canlı istekle sonucu kontrol edin. 404’ün web sunucusundan gelme ihtimalini de göz ardı etmeyin.
Route clear kalıcı çözüm mü?
Tek başına değildir. Eski önbelleğin etkisini tanılamaya yardımcı olur; dağıtım süreciniz yeni sürüm için cache üretmiyorsa sorun tekrar eder. Cache’i kullanmaya devam edecekseniz route:cache adımını doğru sürümde otomatikleştirin.
Route cache veritabanı sorgularını hızlandırır mı?
Hayır. Rota kayıt maliyetine yöneliktir. Yavaş sorgu için sorgu günlüğü, indeks, veri erişimi ve uygun uygulama önbelleği incelenmelidir. Kullanıcıya görünen performansı ölçerken bu katmanları ayrı değerlendirin.
Optimize clear komutunu ne zaman kullanmalıyım?
Kapsamını bilerek ve uygulamanızın varsayılan cache sürücüsündeki veriyi hesaba katarak kullanın. Yalnızca rota cache’i hedefliyorsanız daha dar route:clear komutu uygundur. Komut davranışını projenizin Laravel sürümü belgeleriyle karşılaştırın.
Sonuç
Laravel route cache, doğru sürümün rota tanımlarını üretim ortamında hızlı yüklemek için kullanılır. En kritik ilke cache’i kodla birlikte dağıtmak ve her değişiklik sonrası yeniden oluşturmaktır. route:list ile kayıtları, gerçek HTTP testleriyle davranışı, ölçümle performans etkisini doğrulayın. Böylece önbellek dağıtımın öngörülebilir bir parçası olur ve eski rota haritası yüzünden oluşan hatalar daha hızlı ayırt edilir.
Kaynaklar: Laravel Routing ve Laravel Deployment belgeleri. Komut ve sürüm davranışı için projenizin kurulu sürümüne ait resmi belgelere bakın.
Örnek yayımlama kontrolü
Pratik bir kontrol kaydı hazırlayın: sürüm kimliği, dağıtım saati, route:cache komutunun sonucu, örneklenen rota adları, GET ve POST testlerinin durumu, hata günlüğü ve geri alma sorumlusu. Bu kayıt bir sonraki dağıtımda karşılaştırma imkânı verir. Küçük bir ekipte bile komutun hangi dizinde ve hangi PHP çalıştırıcısıyla yürütüldüğünün yazılması yararlıdır. CI ortamındaki başarılı sonuç ile canlı sunucudaki sonuç farklıysa ortam ve dosya yolu farkını hızla bulursunuz. Değişiklik sonrası birkaç dakika izleme yapmak, yalnızca ilk sayfa yüklemesine bakmaktan daha güvenilirdir.
Komutların gerçek çıktısını saklamak, hata raporunda hassas ortam bilgileri bulunabileceği için erişim sınırlarıyla yapılmalıdır. Genel bir blog yazısına gerçek sunucu yolu, erişim anahtarı veya üretim günlüklerini yapıştırmayın. Ekip içi kayıtlar da sırların paylaşılmadığı bir yerde tutulmalıdır.
