شروع کار با لاراول – ساختار دایرکتوری

ساختار دایرکتوری یا ساختار پوشه‌ها، به عنوان یکی از مهم‌ترین بخش‌های یک پروژه‌ی وب، می‌تواند برای ترتیب‌بخشی به فایل‌ها و پوشه‌ها و همچنین بهبود قابلیت نگه‌داری کدها و افزایش بهره‌وری در پروژه بسیار موثر باشد.
با ادامه ترجمه مستندات فارسی Laravel 10  بخش (شروع کار با لاراول – ساختار دایرکتوری)، در خدمت شما کاربران گرامی وب‌سایت آموزشی لاراول کارا هستیم. امیدواریم که این مطلب برای شما مفید واقع شده باشد. در صورت داشتن هرگونه سوال یا ابهام، لطفاً در قسمت نظرات با ما در ارتباط باشید.

# معرفی (Introduction)

ساختار پیش‌فرض برنامه Laravel برای اپلیکیشن‌های کوچک و بزرگ، نقطه شروعی خوبی برای شروع پروژه شماست. اما شما می‌توانید برنامه خود را به هر شکلی که می‌خواهید سازماندهی کنید. Laravel تقریباً هیچ محدودیتی در مورد محل قرارگیری هیچ کلاس خاصی ندارد، تنها شرط این است که کلاس توسط Composer autoload شود.

# دایرکتوری روت (The Root Directory)

# دایرکتوری اپ (The app Directory)

دایرکتوری “app” حاوی کد هسته‌ برنامه شما می‌باشد. به زودی، به صورت دقیق‌تر در مورد این دایرکتوری صحبت خواهیم کرد؛ اما تقریباً تمامی کلاس‌های برنامه شما در این دایرکتوری قرار خواهد گرفت.

# دایرکتوری بوت استرپ (The bootstrap Directory)

دایرکتوری “bootstrap” حاوی فایل “app.php” است که فریم‌ورک را راه‌اندازی می‌کند. این دایرکتوری همچنین دارای یک دایرکتوری “cache” می‌باشد که شامل فایل‌های تولید شده توسط فریم‌ورک برای بهبود عملکرد مانند فایل‌های کش روت و سرویس‌ها می‌باشد. شما به طور معمول نیازی به اصلاح هیچ فایل در این دایرکتوری ندارید.

# دایرکتوری کانفیگ (The config Directory)

دایرکتوری “config”، همانطور که از نامش پیداست، حاوی تمامی فایل‌های پیکربندی برنامه شماست. خواندن این فایل‌ها و آشنایی با تمامی گزینه‌های موجود در آنها، به شما کمک می‌کند تا با تنظیمات موجود در برنامه‌ی خود، بهتر آشنا شوید.

# دایرکتوری دیتابیس (The database Directory)

دایرکتوری “database”، شامل فایل‌های مهاجرت پایگاه داده، factories و داده‌های اولیه برنامه شماست. همچنین، در صورت تمایل، شما می‌توانید از این دایرکتوری برای نگهداری یک پایگاه داده SQLite استفاده کنید.

# دایرکتوری پابلیک (The public Directory)

دایرکتوری “public” شامل فایل “index.php” است، که نقطه ورودی برای تمام درخواست‌هایی است که به برنامه شما وارد می‌شوند و autoload را پیکربندی می‌کند. همچنین، این دایرکتوری، شامل منابعی مانند تصاویر، جاوااسکریپت و CSS برنامه شما نیز می‌باشد.

# دایرکتوری منابع (The resources Directory)

دایرکتوری “resources” شامل فایل‌های نمایش شما (views) و منابع نامنظم و بدون کامپایل شده‌ی شما مانند فایل‌های CSS و جاوا اسکریپت است.

# دایرکتوری مسیرها (The routes Directory)

دایرکتوری “routes” شامل تمامی تعاریف مسیر برنامه شما می‌باشد. در Laravel، چندین فایل مسیر به صورت پیش‌فرض در دسترس هستند، از جمله: web.php، api.php، console.php و channels.php.

فایل “web.php” حاوی مسیرهایی است که “RouteServiceProvider” آنها را در گروه middleware وب قرار می‌دهد و وضعیت جلسه، حفاظت CSRF و رمزنگاری کوکی را فراهم می‌کند. اگر برنامه شما یک API RESTful و به وضعیت قبلی درخواست‌ها وابستگی ندارند، بسیاری از مسیرهایتان به احتمال زیاد در فایل “web.php” تعریف شده‌اند.

فایل “api.php” حاوی مسیرهایی است که “RouteServiceProvider” آنها را در گروه middleware api قرار می‌دهد. این مسیرها برای استفاده در API‌های بی‌وضع (به وضعیت قبلی درخواست‌ها وابستگی ندارند) طراحی شده‌اند، بنابراین درخواست‌هایی که از طریق این مسیرها به برنامه وارد می‌شوند، باید از طریق توکن تأیید هویت شوند و به وضعیت جلسه دسترسی نداشته باشند.

فایل “console.php” محل تعریف دستورات کنسول مبتنی بر بسته‌بندی است. هر بسته‌بندی به یک نمونه دستور متصل است که اجازه برای برقراری ارتباط با روش‌های IO هر دستور را فراهم می‌کند. این فایل، علیرغم اینکه مسیرهای HTTP را تعریف نمی‌کند، نقاط ورودی مبتنی بر کنسول (مسیرها) را به برنامه‌ی شما تعریف می‌کند.

فایل “channels.php” محل ثبت تمام کانال‌های پخش رویدادهای برنامه شماست.

# دایرکتوری ذخیره‌سازی (The storage Directory)

دایرکتوری “storage” شامل فایل‌های گزارش‌های شما، قالب‌های Blade کامپایل شده، جلسات بر اساس فایل، حافظه‌های کش بر اساس فایل و سایر فایل‌های تولید شده توسط چارچوب است. این دایرکتوری به دو بخش app و framework تقسیم شده است. بخش app می‌تواند برای ذخیره‌ی هر فایل تولید شده توسط برنامه شما مورد استفاده قرار گیرد. بخش framework برای ذخیره‌ی فایل‌ها و کش‌های تولید شده توسط چارچوب استفاده می‌شود. در نهایت، بخش logs شامل فایل‌های گزارشات برنامه شماست.

دایرکتوری “storage/app/public” می‌تواند برای ذخیره‌ی فایل‌های تولید شده توسط کاربران، مانند آواتارهای پروفایل، که باید به صورت عمومی قابل دسترسی باشند، استفاده شود. برای این کار، باید یک لینک نمادین در مسیر “public/storage” ایجاد شود که به این دایرکتوری اشاره کند. شما می‌توانید این لینک را با استفاده از دستور “php artisan storage:link” ایجاد کنید.

# دایرکتوری تست‌ها (The tests Directory)

دایرکتوری “tests” شامل تست‌های خودکار شما است. در Laravel، تست‌های واحد PHPUnit و تست‌های ویژگی به طور پیش‌فرض در دسترس هستند. هر کلاس تست باید با کلمه “Test” به پایان برسد. شما می‌توانید تست‌های خود را با استفاده از دستور “phpunit” یا “php vendor/bin/phpunit” اجرا کنید. همچنین، اگر می‌خواهید نتایج تست خود را با جزئیات بیشتر و زیبا تر مشاهده کنید، می‌توانید تست‌های خود را با استفاده از دستور “php artisan test” اجرا کنید.

# دایرکتوری وندور (The vendor Directory)

دایرکتوری “vendor” شامل وابستگی‌های Composer شماست. در این دایرکتوری، فایل‌های ضروری برای اجرای پروژه شما از جمله کتابخانه‌های PHP و تنظیمات دیگر از طریق Composer نصب می‌شوند. این دایرکتوری به طور پیش‌فرض در مسیر اصلی پروژه شما قرار دارد.

# دایرکتوری App در لاراول (The App Directory)

بخش عمده‌ی برنامه‌ی شما در دایرکتوری “app” قرار دارد. به طور پیش‌فرض، این دایرکتوری تحت فضای‌نام “App” است و با استفاده از استاندارد autoload PSR-4، توسط Composer autoload اجرا می‌شود.

دایرکتوری app شامل چندین دایرکتوری اضافی مانند Console، Http و Providers است. دایرکتوری‌های Console و Http به عنوان یک رابط برای دسترسی به هسته برنامه‌ی شما عمل می‌کنند. پروتکل HTTP و CLI هر دو مکانیزمی هستند برای تعامل با برنامه‌ی شما، اما در واقع شامل منطق برنامه نیستند. به عبارت دیگر، آنها دو روش برای صدور دستورات به برنامه شما هستند. دایرکتوری Console شامل تمامی دستورات Artisan شماست، در حالی که دایرکتوری Http شامل کنترلرها، میان‌افزارها و درخواست‌های شماست.

همچنین، با استفاده از دستورهای Artisan، دایرکتوری‌های دیگری درون دایرکتوری app به صورت خودکار تولید می‌شوند. به عنوان مثال، دایرکتوری “app/Jobs” تا زمانی که دستور “make:job” را برای تولید یک کلاس job اجرا نکنید، وجود ندارد.

بسیاری از کلاس‌های موجود در دایرکتوری app می‌توانند با استفاده از دستورهای Artisan تولید شوند. برای مشاهده دستورهای موجود، دستور “php artisan list make” را در ترمینال خود اجرا کنید.

# دایرکتوری Broadcasting در لاراول (The Broadcasting Directory)

دایرکتوری “Broadcasting”، شامل تمامی کلاس‌های کانال پخش برای برنامه‌ی شما است. این کلاس‌ها با استفاده از دستور “make:channel” تولید می‌شوند. این دایرکتوری به طور پیش‌فرض وجود ندارد، اما هنگامی که اولین کانال شما را ایجاد می‌کنید، برای شما ایجاد می‌شود. برای یادگیری بیشتر در مورد کانال‌ها، می‌توانید مستندات پخش رویداد را مطالعه کنید.

# دایرکتوری کنسول (The Console Directory)

دایرکتوری “Console”، شامل تمامی دستورات سفارشی Artisan برای برنامه شما است. این دستورات می‌توانند با استفاده از دستور “make:command” تولید شوند. این دایرکتوری همچنین کرنل مطبوعاتی شما را نیز شامل می‌شود که در آن دستورات سفارشی Artisan شما ثبت شده و وظایف زمانبندی شده شما تعریف می‌شود.

# دایرکتوری رویدادها (The Events Directory)

این دایرکتوری به طور پیش‌فرض وجود ندارد، اما با استفاده از دستورهای Artisan event:generate و make:event برای شما ایجاد خواهد شد. دایرکتوری Events شامل کلاس‌های event است. رویدادها می‌توانند برای هشدار دادن به بخش‌های دیگر برنامه‌ی شما که یک عمل مشخص رخ داده، استفاده شوند و امکاناتی نظیر انعطاف‌پذیری و کاهش وابستگی را فراهم می‌کنند.

# دایرکتوری استثنائات (The Exceptions Directory)

دایرکتوری “Exceptions”، شامل مدیریت استثناء‌های برنامه شما است و همچنین می‌تواند مکان مناسبی برای قرار دادن هر استثناء پرتاب شده توسط برنامه شما باشد. اگر می‌خواهید نحوه ثبت و نمایش استثناء‌های خود را سفارشی کنید، باید کلاس Handler را در این دایرکتوری تغییر دهید.

# دایرکتوری HTTP در لاراول (The Http Directory)

دایرکتوری “Http”، شامل کنترلرها، middleware ها و درخواست‌های فرم شما است. تقریباً تمامی منطق برای پردازش درخواست‌های ورودی به برنامه شما در این دایرکتوری قرار خواهد گرفت.

# دایرکتوری کارها (The Jobs Directory)

این دایرکتوری به طور پیش‌فرض وجود ندارد، اما اگر دستور Artisan make:job را اجرا کنید، برای شما ایجاد خواهد شد. دایرکتوری Jobs، شامل کارهای قابل صف‌گذاری برای برنامه شما است. کارها می‌توانند توسط برنامه شما در صف قرار داده شوند یا به صورت همزمان در طول دوره عمر درخواست جاری اجرا شوند. کارهایی که درخواست جاری به صورت همزمان اجرا می‌شوند، گاهی به عنوان “فرمان‌ها” نامیده می‌شوند، زیرا پیاده‌سازی آنها یک پیاده‌سازی از الگوی command هستند.

# دایرکتوری گوش‌کنندگان (The Listeners Directory)

این دایرکتوری به طور پیش‌فرض وجود ندارد، اما اگر دستورهای Artisan event:generate و make:listener را اجرا کنید، برای شما ایجاد خواهد شد. دایرکتوری Listeners، شامل کلاس‌هایی است که رویدادهای شما را پردازش می‌کنند. گوش‌کنندگان رویداد یک نمونه رویداد دریافت کرده و پاسخی به رویداد ارسال شده ارائه می‌دهند. به عنوان مثال، یک رویداد UserRegistered ممکن است توسط یک گوش‌کننده SendWelcomeEmail پردازش شود.

# دایرکتوری ایمیل (The Mail Directory)

این دایرکتوری به طور پیش‌فرض وجود ندارد، اما اگر دستور Artisan make:mail را اجرا کنید، برای شما ایجاد خواهد شد. دایرکتوری Mail، شامل تمامی کلاس‌هایی است که نماینده ایمیل‌های ارسالی توسط برنامه شما هستند. اشیاء Mail به شما اجازه می‌دهند تا تمام منطق ساخت یک ایمیل را در یک کلاس ساده واحد تعبیه کنید که با استفاده از متد Mail::send قابل ارسال هستند.

# دایرکتوری مدل‌ها (The Models Directory)

دایرکتوری “Models”، شامل تمامی کلاس‌های مدل Eloquent شما است. ORM Eloquent که با Laravel همراه است، پیاده‌سازی ساده و زیبای ActiveRecord را برای کار با پایگاه داده‌های شما فراهم می‌کند. هر جدول پایگاه داده، مدل مربوطه را دارد که برای ارتباط با آن جدول استفاده می‌شود. مدل‌ها به شما اجازه می‌دهند تا در جداول خود جستجو کنید و همچنین رکوردهای جدید را در جدول اضافه کنید.

# دایرکتوری اعلان‌ها (The Notifications Directory)

این دایرکتوری به طور پیش‌فرض در لاراول وجود ندارد، اما اگر دستور Artisan make:notification را اجرا کنید، برای شما ایجاد خواهد شد. دایرکتوری Notifications، شامل تمامی اعلان‌های “تراکنشی” است که توسط برنامه شما ارسال می‌شوند، مانند اعلان‌های ساده در مورد رویدادهایی که در برنامه شما رخ می‌دهند. ویژگی اعلان Laravel، ارسال اعلان‌ها را از طریق driver های مختلفی مانند ایمیل، Slack، پیامک یا ذخیره شده در پایگاه داده، فراهم می‌کند.

# دایرکتوری سیاست‌ها (The Policies Directory)

دایرکتوری Policies، شامل کلاس‌های سیاست مجوزدهی برای برنامه شماست. این دایرکتوری به طور پیش‌فرض وجود ندارد، اما اگر دستور Artisan make:policy را اجرا کنید، برای شما ایجاد خواهد شد. سیاست‌ها برای تعیین اینکه آیا یک کاربر می‌تواند یک عمل خاص را بر روی یک منبع انجام دهد یا خیر، استفاده می‌شوند.

# دایرکتوری تأمین‌کنندگان (The Providers Directory)

دایرکتوری Providers، شامل تمامی ارائه‌دهندگان سرویس برای برنامه شماست. ارائه‌دهندگان سرویس، با بایند کردن سرویس‌ها در کانتینر سرویس، ثبت رویدادها و یا انجام هرگونه وظیفه دیگر، برنامه شما را bootstrap می‌کنند تا برای درخواست‌های ورودی آماده شود.

در یک برنامه Laravel تازه، این دایرکتوری در حالت پیش‌فرض شامل چندین ارائه‌دهنده خواهد بود. شما آزاد هستید تا به دلخواه خود ارائه‌دهنده‌های جدید را در این دایرکتوری اضافه کنید.

عبارت “bootstrap your application” به معنی آماده‌سازی برنامه است. عبارت “بوت‌استراب کردن” هم به معنی اجرای عملیات‌های مورد نیاز برای آماده‌سازی برنامه در مرحله اولیه است. در اینجا، “service providers” که در دایرکتوری Providers قرار دارند، با بایند کردن سرویس‌ها، ثبت رویدادها و اجرای سایر وظایف مرتبط، برای آماده‌سازی برنامه در مرحله اولیه کاربرد دارند.

# دایرکتوری قوانین (The Rules Directory)

دایرکتوری Rules، شامل اشیای سفارشی برای اعتبارسنجی در برنامه شماست. این دایرکتوری به طور پیش‌فرض در لاراول وجود ندارد، اما اگر دستور Artisan make:rule را در ترمینال اجرا کنید، برای شما ایجاد خواهد شد. قوانین، برای تعبیه منطق اعتبارسنجی در یک شی ساده استفاده می‌شوند. برای اطلاعات بیشتر، به مستندات اعتبارسنجی مراجعه کنید.