ساختار پوشههای Laravel 12 — راهنمای کامل app، routes، config و بقیه
بعد از نصب Laravel، اولین سوال معمولاً این است: «این همه پوشه برای چیست؟» جواب کوتاه: هر پوشه یک مرز مسئولیت است. وقتی ساختار را بشناسید، نه فایلها را گم میکنید، نه منطق کسبوکار را در Controller گیر میاندازید. در Laravel 12 ساختار کلی شبیه نسخههای ۱۰ و ۱۱ است؛ تغییرات جزئی در bootstrap و config را در مستندات رسمی ببینید.
چرا شناخت ساختار پوشهها مهم است؟
در پروژههای واقعی — فروشگاه، پورتال شرکتی، API — بدون conventions تیم دچار آشوب میشود: یکی Service میسازد، دیگری همه چیز را در Controller مینویسد. Laravel conventions را پیشنهاد میدهد؛ شما با دانستن نقش هر پوشه میتوانید همان روز اول تصمیم درست بگیرید.
نمای کلی — درخت اصلی
my-project/
├── app/
├── bootstrap/
├── config/
├── database/
├── public/
├── resources/
├── routes/
├── storage/
├── tests/
├── vendor/
├── .env
├── artisan
└── composer.jsonپوشه app/ — قلب اپلیکیشن
کدهای اختصاصی شما اینجاست:
- Http/Controllers — دریافت request و برگرداندن response. نازک نگه دارید.
- Models — Eloquent و ارتباط با دیتابیس.
- Http/Middleware — فیلتر قبل/بعد از request (auth، throttle).
- Http/Requests — validation ورودی.
- Providers — bootstrap سرویسها، binding در container.
- Services / Actions — در پروژههای تمیز خودتان میسازید؛ پیشفرض Laravel پوشه Service ندارد.
در معماری لایهای توضیح دادهام چرا منطق کسبوکار نباید در Model یا Controller انباشته شود.
پوشههای جدیدتر در app/
Laravel 11+ ساختار app را streamlining کرد — برخی فایلهایی که قبلاً در root app بودند حذف یا منتقل شدند. Kernelها در bootstrap/app.php مدیریت میشوند.
bootstrap/ — راهاندازی فریمورک
فایل bootstrap/app.php نقطه تنظیم routing، middleware و exception handling است. فایلهای bootstrap/cache/ برای کش config و routes در production — معمولاً commit نمیشوند.
config/ — تنظیمات
هر فایل یک domain: database.php، cache.php، queue.php. مقدار واقعی اغلب از .env خوانده میشود. جزئیات env در مقاله تنظیمات .env.
database/ — migrations، seeders، factories
migrations/ تاریخچه تغییرات schema. seeders/ داده اولیه. factories/ برای تست و fake data. در production فقط migrate اجرا میشود؛ seed معمولاً یکبار در setup.
public/ — تنها درگاه وب
index.php front controller است. assetهای build شده (css/js) و favicon اینجا. Document Root سرور باید همین پوشه باشد — نه root پروژه.
resources/ — view و asset خام
views/ فایلهای Blade. css/ و js/ برای Vite. ترجمهها در lang/ (در نسخههای جدید ممکن است lang در root باشد).
routes/ — نقشه URL
web.php برای session و CSRF. api.php برای API stateless. console.php برای scheduled commands. مقاله بعدی: اولین Route و Controller.
storage/ — فایلهای موقت و آپلود
logs/، framework/cache، app/public برای فایلهای آپلودی. symlink از public/storage به storage/app/public با php artisan storage:link.
tests/ — Pest یا PHPUnit
Feature tests شبیه HTTP request واقعی؛ Unit tests برای کلاسهای ایزوله.
vendor/ — وابستگیهای Composer
هرگز دستی edit نکنید. در gitignore است. با composer install ساخته میشود.
اشتباهات رایج مبتدیان
قرار دادن logic سنگین در Controller. نوشتن query خام در Blade. commit کردن storage/logs. تغییر فایلهای vendor. ساخت پوشههای random بدون convention (مثلاً app/Helpers با ۵۰ تابع global).
بهترین شیوهها
Feature جدید = migration + model + controller نازک + service + test. از namespace و PSR-4 پیروی کنید. برای پنل ادمین Filament یا resource controller. از اصول طلایی Laravel پیروی کنید.
جمعبندی
ساختار Laravel 12 برای scale طراحی شده — اگر از اول جای درست هر فایل را رعایت کنید، refactor بعدی دردناک نخواهد بود. قدم بعد: .env و اولین route.
پروژه Laravel دارید؟ مشاوره معماری بگیرید.