برای رفع Class not found در پروژهٔ مبتنی بر Composer، سه چیز را به ترتیب بررسی کنید. نقطهٔ ورود باید autoload.php را بار کند، پیشوند namespace باید به پوشهٔ درست نگاشت شده باشد و نام کلاس، فایل و مسیر باید با هم بخوانند.
۱. از نام کامل کلاس به مسیر فایل برسید
نمونهٔ زیر یک نگاشت PSR-۴ در composer.json است. در رشتهٔ JSON هر بکاسلش با بکاسلش دیگری escape شده است.
{
"autoload": {
"psr-4": {
"Demo\\App\\": "src/"
}
}
}
با نگاشت بالا، Demo\App\Report به src/Report.php و Demo\App\Export\Report به src/Export/Report.php میرسد. بخش باقیمانده پس از پیشوند، پوشه و نام فایل را تعیین میکند. حروف بزرگ و کوچک نام مسیر و فایل را دقیق تطبیق دهید.
۲. نمونهٔ حداقلی را در پروژهٔ تمرینی بسازید
فایل src/Report.php در کپی آزمایشی:
<?php
namespace Demo\App;
class Report {}
فایل check.php کنار composer.json:
<?php
require __DIR__ . '/vendor/autoload.php';
echo class_exists(\Demo\App\Report::class) ? 'loaded' : 'missing';
از ریشهٔ همان پروژه و پس از بررسی تنظیمات بستهها، نگاشت را تولید و آزمون را اجرا کنید.
composer dump-autoload --no-plugins --no-scripts
php check.php
در آزمون محلی، وقتی فایل به اشتباه namespace دیگری اعلام میکرد، نتیجه missing بود. پس از اصلاح namespace، همان نگاشت نتیجهٔ loaded داد. آزمایش روی ویندوز اجرا شد. رفتار تفاوت حروف فایل را در فایلسیستم محیط مقصد نیز کنترل کنید.
۳. علت را بر اساس نشانه پیدا کنید
| نشانه | بررسی |
|---|---|
| vendor/autoload.php پیدا نمیشود | مسیر نسبت به فایل نقطهٔ ورود، artifact استقرار و کاملبودن نصب را بررسی کنید. |
| فایل هست ولی کلاس بار نمیشود | نام کامل در خطا را با namespace و نام کلاس داخل فایل مقایسه کنید. |
| روی ویندوز کار میکند و در محیط دیگر خطا دارد | حروف مسیر و نام فایل را با نسخهٔ ثبتشده در Git تطبیق دهید. |
| پس از استقرار حالت بهینه خطا ظاهر شده | حالت classmap و زمان تولید فایلهای autoload را بررسی کنید. نقشه باید از همان کد و وابستگیها ساخته شده باشد. |
۴. تولید مجدد نقشه چه زمانی لازم است؟
بعد از تغییر نگاشت composer.json یا در فرایندی که classmap را از پیش میسازد، فایلهای autoload را دوباره در محیط ساخت تولید کنید. برای یک کلاس PSR-۴ عادی که با نگاشت موجود و حالت عادی autoloader سازگار است، افزودن فایل لزوماً به تولید مجدد نیاز ندارد.
فایل تولیدی داخل vendor/composer را دستی ویرایش نکنید. اصلاح را روی منبع یا نگاشت در کپی آزمایشی انجام دهید، سپس نقطهٔ ورود واقعی برنامه را بررسی کنید.
اگر پوشهٔ vendor یا فایل autoload.php وجود ندارد، ابتدا روش نصب وابستگیها از composer.lock را بررسی کنید؛ خطای نبودن وابستگی با خطای نگاشت PSR-۴ یکسان نیست.
۵. مطالعهٔ مرتبط
- PHP و MySQL چیست و چه ربطی به سایت من دارند؟
- رفع خطای Cannot find module در Node.js؛ مسیر یا وابستگی؟
۶. منابع و روش بررسی
منابع در ۱۳ نوامبر ۲۰۲۶ بررسی شدند. مثال در پوشهٔ محلی ویندوز با PHP ۸.۵.۱۲ و Composer ۲.۱۱.۲ اجرا شد. مخزن تمرینی بستهٔ واقعی دانلود نمیکند و اجرای اسکریپت و افزونه در آزمایش غیرفعال بود.