Laravel Class Not Found Hatası Nasıl Çözülür?

Laravel Class Not Found hatası, PHP'nin veya Laravel'in çağrılan bir sınıfı bulamadığı durumlarda ortaya çıkar. Genellikle yanlış namespace, eksik use bildirimi, hatalı dosya adı, Composer autoload sorunu veya sınıfın yanlış klasörde bulunması nedeniyle oluşur. Bu rehberde Laravel Class Not Found hatasının nedenlerini ve çözüm yöntemlerini adım adım inceleyeceğiz.

1. Laravel Class Not Found Hatası Nedir?

Laravel projesinde bir Controller, Model, Service, Middleware veya başka bir PHP sınıfı çağrıldığında PHP ilgili sınıfı bulamazsa Class Not Found hatası oluşabilir.
Örnek:
Class "App\Models\Product" not found
veya:
Class "App\Http\Controllers\ProductController" not found
Bu hata özellikle yeni oluşturulan veya taşınan sınıflarda sık görülür.

2. Sınıf Dosyasının Gerçekten Var Olduğunu Kontrol Edin

İlk olarak hata mesajında belirtilen sınıfın dosyasının mevcut olduğundan emin olun.
Örneğin:
app/Models/Product.php
Dosya gerçekten yoksa Model oluşturabilirsiniz:
php artisan make:model Product
Controller için:
php artisan make:controller ProductController

3. Namespace Kontrolü Yapın

PHP sınıfının namespace'i dosyanın bulunduğu klasörle uyumlu olmalıdır.
Örneğin Product Model:
namespace App\Models;
ve:
class Product extends Model
şeklinde olmalıdır.
Ardından sınıfı çağıran dosyada:
use App\Models\Product;
kullanılabilir.

4. use Satırını Kontrol Edin

Class Not Found hatalarının en yaygın nedenlerinden biri yanlış veya eksik use satırıdır.
Örneğin Controller içerisinde:
use App\Models\Product;
olması gerekirken farklı bir namespace kullanılmış olabilir.
Yanlış:
use App\Model\Product;
Doğru:
use App\Models\Product;
Namespace'in gerçek klasör yapısıyla aynı olduğundan emin olun.

5. Dosya Adı ile Class Adını Kontrol Edin

PHP sınıfının dosya adı ve class adı uyumlu olmalıdır.
Dosya:
Product.php
Class:
class Product extends Model
şeklinde olmalıdır.
Örneğin:
Products.php
dosyasında:
class Product
bulunması ileride autoload veya dosya yolu kaynaklı sorunlara neden olabilir.

6. Linux Sunucularda Büyük Küçük Harf Kontrolü

Windows ve Linux arasındaki önemli farklardan biri dosya sistemi davranışıdır.
Örneğin:
Product.php
ile:
product.php
Linux ortamında farklı dosyalar olarak değerlendirilebilir.
Aynı şekilde:
App\Models
ile:
App\models
arasında da sorun oluşabilir.
Bu nedenle dosya ve namespace isimlerinde büyük-küçük harf uyumunu kontrol edin.

7. Composer Autoload Yenileyin

Yeni sınıf oluşturduysanız veya sınıfın konumunu değiştirdiyseniz Composer autoload dosyalarını yenilemeniz gerekebilir.
composer dump-autoload
Ardından Laravel cache temizleyebilirsiniz:
php artisan optimize:clear
Sonrasında uygulamayı tekrar test edin.

8. Composer install Çalıştırın

Projeyi başka bir bilgisayardan veya sunucudan taşıdıysanız vendor klasörü eksik olabilir.
Bu durumda:
composer install
çalıştırabilirsiniz.
Ardından:
composer dump-autoload
komutunu kullanabilirsiniz.
Production ortamında composer install çalıştırırken projenin mevcut composer.lock dosyasını korumak önemlidir.

9. Model Namespace Kontrolü

Laravel Model'lerinde namespace hatası sık karşılaşılır.
Örneğin Model:
app/Models/Product.php
içerisinde:
namespace App\Models;
olmalıdır.
Controller:
use App\Models\Product;
şeklinde Model'i çağırabilir.
Eski Laravel projelerinde Model'lerin App altında bulunması mümkün olduğundan projenin mevcut yapısı dikkate alınmalıdır.

10. Controller Namespace Kontrolü

Controller dosyası:
app/Http/Controllers/ProductController.php
konumundaysa namespace genellikle:
namespace App\Http\Controllers;
şeklindedir.
Route dosyasında:
use App\Http\Controllers\ProductController;
kullanabilirsiniz.
Controller farklı bir klasöre taşındıysa namespace'in de buna göre değiştirilmesi gerekir.

11. Alt Klasörlerdeki Sınıfları Kontrol Edin

Örneğin Controller:
app/Http/Controllers/Admin/ProductController.php
konumundaysa namespace:
namespace App\Http\Controllers\Admin;
olmalıdır.
Route:
use App\Http\Controllers\Admin\ProductController;
şeklinde çağrılmalıdır.
Klasör yapısı ile namespace birbirinden farklıysa Class Not Found hatası oluşabilir.

12. Composer PSR-4 Autoload Yapısını Kontrol Edin

Laravel projelerinde Composer sınıfları PSR-4 autoload standardı üzerinden yükler.
composer.json içerisinde genellikle:
"autoload": { "psr-4": { "App\\": "app/" } }
yapısı bulunur.
Bu yapı değiştirildiyse veya sınıflar farklı bir klasöre taşındıysa autoload sorunu oluşabilir.
Değişiklik sonrasında:
composer dump-autoload
çalıştırılmalıdır.

13. Class Adında Yazım Hatası Var mı?

Sınıf adındaki tek bir karakter bile hataya neden olabilir.
Örneğin:
ProductController
ile:
ProductsController
aynı sınıf değildir.
Benzer şekilde:
PaymentService
ile:
PaymentsService
farklı isimlerdir.
Hata mesajındaki sınıf adını dosyadaki class adıyla birebir karşılaştırın.

14. Interface ve Trait Dosyalarını Kontrol Edin

Class Not Found yalnızca normal class dosyalarında görülmez.
Interface:
PaymentGatewayInterface
veya Trait:
HasApiTokens
gibi yapılarda da sınıf bulunamazsa benzer hatalar oluşabilir.
Dosyanın mevcut olduğunu, namespace'inin doğru olduğunu ve use satırının doğru yazıldığını kontrol edin.

15. Cache Temizleme İşlemini Yapın

Sınıf dosyasını veya namespace'i değiştirdikten sonra Laravel cache'lerini temizlemek faydalı olabilir.
php artisan optimize:clear
Ardından:
composer dump-autoload
çalıştırabilirsiniz.
Sonrasında uygulamayı yeniden test edin.

16. Route İçerisindeki Controller'ı Kontrol Edin

Route dosyasında:
use App\Http\Controllers\ProductController;
ve:
Route::get('/products', [ProductController::class, 'index']);
kullanılıyorsa ProductController dosyasının gerçekten bu namespace altında bulunduğundan emin olun.
Yanlış namespace Class Not Found hatasına neden olabilir.

17. Service Sınıflarında Class Not Found

Laravel projelerinde Service sınıfları genellikle:
app/Services
klasöründe bulunur.
Örneğin:
app/Services/PaymentService.php
içerisinde:
namespace App\Services;
kullanılmalıdır.
Controller içerisinde:
use App\Services\PaymentService;
ile çağrılabilir.

18. Proje Taşındıktan Sonra Class Not Found

Laravel projesini cPanel veya başka bir sunucuya taşıdıysanız şu işlemleri kontrol edin:
composer install
composer dump-autoload
php artisan optimize:clear
Ayrıca dosya isimlerinde büyük-küçük harf farklılıklarını kontrol edin.
Özellikle Windows'tan Linux sunucuya yapılan taşımalarda bu sorun daha belirgin olabilir.

19. vendor Klasörünü Kontrol Edin

Laravel uygulamasının Composer bağımlılıkları vendor klasöründe bulunur.
Klasör yoksa:
composer install
çalıştırılmalıdır.
Composer kurulumu mümkün değilse hosting ortamının Composer desteği veya yerel bilgisayarda oluşturulan vendor klasörünün deployment yöntemi kontrol edilmelidir.

20. Class Not Found Hatası İçin Hızlı Kontrol Listesi

Sorunu hızlı şekilde çözmek için şu sırayla ilerleyebilirsiniz:
ls -la app
ls -la app/Models
ls -la app/Http/Controllers
composer dump-autoload
php artisan optimize:clear
Ardından hata mesajındaki namespace ile dosyanın namespace'ini, class adıyla dosya adını karşılaştırın.

Sık Sorulan Sorular

1. Laravel Class Not Found hatası neden oluşur? PHP veya Laravel çağrılan sınıfı bulamadığında oluşur.
2. Laravel Class Not Found nasıl çözülür? Dosya yolu, namespace, class adı, use satırı ve Composer autoload kontrol edilmelidir.
3. composer dump-autoload ne işe yarar? Composer'ın PHP sınıflarını otomatik yüklemek için kullandığı autoload kayıtlarını yeniler.
4. Laravel'de namespace neden önemlidir? PHP sınıfın tam adını namespace üzerinden belirlediği için yanlış namespace sınıfın bulunamamasına neden olabilir.
5. Laravel Model bulunamıyor, ne yapmalıyım? Model dosyasının varlığını, namespace'ini ve Controller içerisindeki use satırını kontrol edin.
6. Laravel Controller Class Not Found neden verir? Controller'ın yanlış namespace ile çağrılması, dosyanın eksik olması veya class adının yanlış yazılması nedeniyle oluşabilir.
7. Laravel'de use satırı neden gereklidir? Başka bir namespace altında bulunan sınıfı bulunduğunuz PHP dosyasında doğru şekilde çağırmanızı sağlar.
8. Windows'ta çalışan Laravel Linux'ta neden Class Not Found verir? Linux dosya sistemlerinde büyük-küçük harf farkları sorun oluşturabilir.
9. Laravel'de dosya adı ile class adı aynı olmalı mı? PSR-4 autoload yapısının düzgün çalışması için sınıf ve dosya isimlerinin uyumlu olması gerekir.
10. Laravel Class Not Found Composer kaynaklı olabilir mi? Evet. Autoload kayıtları güncel değilse Composer kaynaklı olabilir.
11. Laravel composer install Class Not Found sorununu çözer mi? Eksik vendor bağımlılıkları varsa çözebilir. Ancak namespace veya dosya yolu hatalarını tek başına çözmez.
12. Laravel optimize:clear Class Not Found sorununu çözer mi? Eski cache kaynaklı sorunlarda yardımcı olabilir ancak gerçek namespace veya dosya hatasını düzeltmez.
13. Laravel alt klasördeki Controller neden bulunamıyor? Namespace ve use bildirimi alt klasör yapısına göre güncellenmemiş olabilir.
14. Laravel Service sınıfı neden bulunamıyor? Service dosyasının namespace'i, dosya konumu ve use bildirimi kontrol edilmelidir.
15. Laravel Interface Class Not Found hatası verir mi? Evet. Interface dosyası bulunamadığında veya namespace yanlış olduğunda benzer hata oluşabilir.
16. Laravel Trait bulunamıyor, neden? Trait dosyası eksik olabilir veya namespace ve use bildirimi yanlış olabilir.
17. Laravel vendor klasörü neden önemlidir? Composer tarafından yüklenen bağımlılıkların bulunduğu temel klasördür.
18. Laravel projesini cPanel'e taşıdıktan sonra Class Not Found neden oluşur? Eksik Composer bağımlılıkları, autoload sorunları veya Linux'taki büyük-küçük harf farklılıkları sebep olabilir.
19. Laravel PSR-4 nedir? Composer'ın sınıfları namespace ve dosya yolu arasındaki kurala göre otomatik yüklemesini sağlayan standartlardan biridir.
20. Laravel Class Not Found hatasında ilk ne kontrol edilmeli? Hata mesajındaki sınıf adı, dosya yolu, namespace, class adı ve use satırı kontrol edilmelidir.