ساختار پروژه لاراول (دایرکتوری ها – پوشه ها – فایل ها)

طبیعتا هر فریمورک استانداردی که برای توسعه‌‌ی وب استفاده می‌شود، چه فریم‌ورک‌های عمومی و چه شخصی، دارای یک ساختار منظمی برای خود می‌باشند. یعنی مثلا فلان دایرکتوری‌ها یا پوشه‌ها، برای قرار گرفتن چه محتوایی هستند؛ یا فایل مربوط به تنظیمات، کانفیگ و … کدام است. در این میان، فریمورک قدرتمند لاراول نیز بدون شک، ساختار منظمی برای خود دارد که بهتر است اگر در حال شروع به یادگیری آن هستید، با این ساختار آشنا شوید. بنابراین در این مطلب، دایکتوری‌ها و فایل‌های پیشفرض یک پروژه‌ی لاراول را توضیح خواهیم داد.

فایل .env

اغلب، داشتن مقادیر پیکربندی مختلف براساس محیطی که اپلیکیشن در آن اجرا می‌‍شود، مفید می‌باشد. برای مثال، ممکن است بخواهید از درایور کشِ متفاوت از آنچه بر روی سرور اپلیکیشن خود دارید استفاده کنید؛ که در این حالت، داشتن پیکربندی تنظیماتِ محیلی برای انجام این کار، به کمک شما می‌آید.

لاراول برای انجام این کار، از کتابخانه پی اچ پی DotEnv که توسط Vance Lucas ایجاد شده است، استفاده می‌کند. لذا در یک پروژه‌ی خام لاراول و داخل دایرکتوری اصلی (ریشه) اپلیکیشن، فایلی به نام .env.example وجود خواهد داشت؛ که اگر لاراول را از طریق کامپوزر نصب کرده باشید، این فایل به طور خودکار به .env تغییر نام می‌دهد. در غیر‌این‌‌صورت، باید فایل را به صورت دستی به .env تغییرنام دهید. (البته ممکن است کامپوزر یک کپی ایجاد کرده و فایل .env.example نیز سر جای خود باقی بماند.)

همچنین، فایل .env نباید به محیط کنترل سورس اپلیکیشن شما وابسته باشد؛ چراکه هر توسعه‌دهنده یا سروری که از اپلیکیشن شما استفاده می‌کند، ممکن است به پیکربندی تنظیمات محیطی متفاوتی نیاز داشته باشد.

در مورد این فایل، بعدا در مطالب جدایی به طور مفصل‌تری حرف خواهیم زد.

دایرکتوری app

پوشه app، محلی برای قرار گرفتن کد یا قسمت‌های اصلی برنامه است و تمامی کلاس‌های برنامه و به عبارتی اکثریت برنامه، دراین دایرکتوری قرار می‌گیرند. همچنین این دایرکتوری، در فضای نامی App قرار داشته و به طور خودکار توسط کامپوزر و به کمک PSR-4 autoloading standard بارگزاری می‌شود.

داخل دایکرکتوری app نیز به بخش‌ها و قسمت‌های مختلفی تقسیم می‌شود؛ که برخی از آنها، به صورت پیشفرض وجود دارند و برخی دیگر بعدا ساخته خواهند شد. این دایرکتوری‌ها به شرح زیر می‌باشند:

• دایرکتوری Broadcasting (بطور پیشفرض وجود ندارد)
• دایرکتوری Console
• دایرکتوری Events (بطور پیشفرض وجود ندارد)
• دایرکتوری Exceptions
• دایرکتوری Http
• دایرکتوری Jobs (بطور پیشفرض وجود ندارد)
• دایرکتوری Listeners (بطور پیشفرض وجود ندارد)
• دایرکتوری Mail (بطور پیشفرض وجود ندارد)
• دایرکتوری Notifications (بطور پیشفرض وجود ندارد)
• دایرکتوری Policies (بطور پیشفرض وجود ندارد)
• دایرکتوری Providers
• دایرکتوری Rules (بطور پیشفرض وجود ندارد)

دایرکتوری‌هایی که وجود ندارند، با استفاده از دستور artisan make که برای تولید کلاس‌ها است، ایجاد می‌شوند. برای مثال، دستور آرتیزنِ make:job زیر، پوشه‌ی Jobs را ایجاد می‌کند:

php artisan make:job ClassName

دایرکتوری Broadcasting

پوشه Broadcasting، تمامی کلاس‌های کانال (یا broadcast channel) اپلیکیشن را شامل می‌شود؛ این کلاس‌ها را می‌توان با دستور آرتیزن زیر ایجاد کرد:

php artisan make:channel ClassName

در مورد کانال‌ها بعدا مطلبی منتشر خواهیم کرد.

دایرکتوری Console

پوشه Console، تمامی دستوراتِ سفارشیِ (cursomr) آرتیزنِ مربوط به اپلیکیشن شما را در برمی‌گیرد؛ این دستوراتِ سفارشی را می‌توان با دستور آرتیزن زیر ایجاد کرد:

php artisan make:command CommandName

همچنین  این دایرکتوری، هسته‌ی کرنل کنسول را نیز در برمی‌گیرد؛ جایی که دستورات سفارشی آرتیزنِ شما در آن رجیستر شده و وظایف زماندبندی‌شده (scheduled tasks) نیز تعریف می‌شوند. در مورد این وظایف زمانبندی شده، بعدا مطلبی را منتشر خواهیم کرد.

دایرکتوری Events

پوشه Events، تمامی کلاس‌های رویدادِ (Event) اپلیکیشن را دربرمی‌گیرد؛ این کلاس‌ها را می‌توان با دستور آرتیزن زیر ایجاد کرد:

php artisan make:event ClassName

رویدادها ممکن است برای اعلام چیزی به سایر قسمت‌های اپلیکیشن مورد استفاده قرار گیرند؛ که مثلا عمل خاصی اتفاق افتاده است. و در واقع رویدادها، قابلیت انعطاف‌پذیری و دگوپلری (decoupling) زیادی را برای اپلیکیشن شما فراهم می‌کنند.

دایرکتوری Exceptions

پوشه Exceptions، تمامی هندلر (مدیریت‌کننده)های مربوط به Exceptionهای اپلیکیشن را شامل می‌شود؛ و همچنین، مکان خوب و مناسبی برای هر نوع اکسپشتنِ پرتاب شده از اپلیکیشن می‌باشد. اگر می‌خواهید چگونگی ایجاد لاگ توسط اکسپشن‌ها و یا نحوه‌ی رندر آنها را شخصی سازی کنید، بایستی کلاس Handler موجود در این دایرکتوری را ویرایش و اصلاح نمایید(تغییر دهید).

دستور آرتیزن برای ایجاد کلاس اکسپشن هندلر، به صورت زیر می‌باشد:

php artisan make:exception ClassName

دایرکتوری Http

پوشه Http، شامل کنترلر (Controller)ها، Middleware (میان افزار)ها و درخواست‌های فرم (form request) می‌باشد. می‌توان گفت که تقریباً تمام منطق مدیریت (handle) درخواست‌های ورودی به اپلیکیشن، در این دایرکتوری قرار می‌گیرند.

دستورات آرتیزن برای ایجاد کنترلر، میان افزار و درخواست‌های فرم، به صورت نیز می‌باشند:

php artisan make:controller ClassName

php artisan make:middleware ClassName

php artisan make:request ClassName

دایرکتوری Jobs

پوشه Jobs، تمامی جاب‌های قابل صف‌بندی (queueable jobs) اپلیکیشن را شامل می‌شود؛ می‌توان با دستور آرتیزن زیر، یک کلاس جاب ایجاد کرد:

php artisan make:job ClassName

Jobها ممکن است توسط اپلیکیشن شما در صف قرار بگیرند (صف‌بندی شوند)؛ و یا بطور همزمان (synchronously)، در طول درخواست فعلی اجرا شوند؛ که اینگونه جاب‌ها، اغلب به «Commands» اشاره می‌کنند. چراکه آنها یک پیاده‌سازی از الگوی دستورات (command pattern) هستند.

در مورد queueable jobs و command pattern، بعدا مطالبی را منتشر خواهیم کرد.

دایرکتوری Listeners

پوشه Listeners، شامل تمامی کلاس‌هایی که رویداد (Event)ها را مدیریت می‌کنند می‌شود؛ و اصطلاحا به آنها، شنوندگان رویداد (event listeners) نیز می‌گویند؛ این کلاس‌ها، با دو دستور آرتیزن زیر می‌توانند ساخته تشوند:

php artisan make:listener ClassName

php artisan make:generate ClassName

شنوندگانه رویداد در واقع، یک نمونه از Event (رویداد) را دریافت کرده و سپس در پاسخ به رویداد ایجاد شده، منطق خاصی را اجرا می‌کنند. مثلا ممکن است یک رویدادی با نام UserRegistered (کاربر ثبت‌نام کرد)، توسط شنونده‌ی SendWelcomeEmail (ارسال ایمیل خوش‌آمد گویی) مدیریت شود.

دایرکتوری Mail

پوشه Mail، شامل تمامی کلاس‌هایی می‌باشد که ایمیل‌های ارسالی اپلیکیشن شما را نمایندگی می‌کنند. آبجکت‌های Mail، به شما اجازه‌ی محصورسازی (کپسوله‌کردن) تمامی منطقِ ایجادِ ایمیل را به صورت یکجا و در یک کلاس ساده و واحد می‌دهند؛ که  ممکن است با متد Mail::send ارسال شود.

دستور آرتیزن برای ایجاد کلاس نماینده ایمیل، به صورت زیر می‌باشد:

php artisan make:mail ClassName

دایرکتوری Notifications

پوشه Notifications، دربرگینده‌ی تمامی نوتیفیکیشن‌ها یا اعلان‌های transactional می‌باشد؛ که توسط اپلیکیشن شما ارسال می‌شوند. مانند نوتیفیکیشن ساده‌ای در مورد رویدادهایی که در اپلیکیشن اتفاق می‌افتد. در واقع خلاصه‌ی امکانات نوتفیکیشن لاراول، ارسال اعلان‌ها برروی انواع درایورهایی مانند ایمیل، Slack , SMS یا موارد ذخیره شده دریک دیتابیس است.

دستور آرتیزن برای ایجاد کلاس نوتیفیکیشن، به صورت زیر می‌باشد:

php artisan make:notification ClassName

دایرکتوری Policies

پوشه Policies،شامل کلاس‌های مربوط به سیاست‌های مجوزدهی (authorization policy) برای اپلیکیشن شما می‌باشد. سیاست‌ها (Policies)، به منظور تعیین مجوز برای کاربر، جهت انجام عمل خاصی روی یک منبع به کار می‌روند.

دستور آرتیزن برای ایجاد کلاس سیاست، به صورت زیر می‌باشد:

php artisan make:policy ClassName

دایرکتوری Providers

پوشه Rules، دربرگیرنده‌ی تمامی ارائه‌دندگان خدماتِ ( service providers) اپلیکیشن شما می‌باشد. ارائه‌دهندگان خدمات، اپلیکیشن شما راه‌اندازی می‌کنند؛ و این راه‌اندازی، بویسله‌ی بیند (bind) کردن سرویس‌ها در ظرفِ سرویس (service container)، ثبت رویدادها، یا آماده کردن اپلیکیشن شما برای درخواست‌های دریافتی، صورت می‌گیرد.

در یک پروژه خام لاراول (اپلیکیشن لاراول جدید)، این دایرکتوری از قبل شامل چندین ارائه‌دهنده یا provider است. شما مجازید ارائه‌دهنده‌های موردنیاز خود را به این دایرکتوری اضافه کنید.

دستور آرتیزن برای ایجاد کلاس ارائه‌دهنده، به صورت زیر می‌باشد:

php artisan make:provider ClassName

دایرکتوری Rules

پوشه Rules، شامل اشیاء سفارشی برای اعتبارسنجی قوانین اپلیکیشن شما است. قوانین (rules)، برای کپسوله‌سازی (محصور کردن و ایجاد کردن) منطقِ اعتبارسنجیِ پیچیده، در یک شئ ساده مورد استفاده قرار می‌گیرند. بعدا در این مورد، مطالبی را منتشر خواهیم کرد.

دستور آرتیزن برای ایجاد کلاس قوانین، به صورت زیر می‌باشد:

php artisan make:rule ClassName

دایرکتوری bootstrap

پوشه bootstrap، شامل فایل app.php جهت راه‌اندازی فریمورک لاراول است. داخل آن، دایکرکتوری دیگری به نام cahce وجود دارد که شامل فایل‌های تولید شده توسط فریمورک برای بهینه‌سازی اپلیکیشن می‌باشد؛ مانند فایل‌های کشِ مسیر (route) و سرویس‌ها (services).

دایرکتوری config

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

دایرکتوری database

پوشه database هم طبیعتا به دیتابیس یا پایگاه‌داده ارتباط دارد. شامل سه دایرکتوری زیر می‌باشد:

• factories
• migrations
• seeds

هرکدام از اینها نیز کلاس‌های مختص خود را در برمی‌گیرند؛ و همچنین توسط آرتیزن می‌توان آنها را ایجاد کرد؛ به صورت زیر:

php artisan make:factory ClassName

php artisan make:migration ClassName

php artisan make:seeder ClassName

همچنین اگر بخواهید، می‌توانید از این دایرکتوری برای نگه داشتن یک SQLite از پایگاه داده هم استفاده کنید.

دایرکتوری public

پوشه public، شامل فایل index.php می‌شود؛ که نقطه‌ی ورودی برای تمامی درخواست‌های وارد شده به اپلیکیشنن شما و پیکربندی autoloading است. این دایرکتوری همچنین assetهای برنامه، مانند تصاویر، فایل‌های جاوااسکریپت و CSS را هم دربر‌می‌گیرد.

دایرکتوری resources

پوشه resources، شامل view‌ها و همچنین منابع خام و کامپال نشده، مانند SASS, LESS یا جاوا اسکریپت است. این دایرکتوری، همچنین تمامی فایل‌های زبان شما را نیز شامل می‌شود. دایرکتوری‌های موجود در داخل آن به صورت زیر می‌باشند:

• js
• lang
• sass
• views

دایرکتوری routes

پوشه routes، همانطور که از نامش پیداست، بایستی برای موارد مربوط به مسیردهی و مسیریابی باشد. در واقع این دایرکتوری، شامل تمامی مسیرهای (routeهای) تعریف شده برای اپلیکیشن شما است. بصورت پیشفرض چندین فایل مسیر، توسط خود لاراول مشمول شده و داخل این دایرکتوری قرار گرفته است؛ که به شرح زیر می‌باشند وو هرکدام برای خود کاربری جدا دارند:

• api.php
• channels.php
• console.php
• web.php

فایل api.php: مسیردهی API مثلا برای ساخت اپلیکیشن اندرویدی

این فایل، شامل مسیرها (route)هایی می‌باشد که RouteServiceProvider، در گروه میان‌افزار api قرار می‌دهد؛ که باعث ایجاد محدودیت در سرعت می‌شود. ین مسیرهای در نظر گرفته شده به صورت غیر مستقیم (stateless) هستند. بنابراین، درخواست‌های ورودی اپلیکیشن، از طریق این مسیرها ارائه می‌شوند تا از طریق توکن‌ها تایید شوند (authenticated) و به وضعیت session هم دسترسی نداشته باشند.

فایل channels.php: مسیردهی کانال‌ها

این فایل، جایی است که می‌توانید تمام کانال‌های پخش رویداد (event) که اپلیکیشن شما از آن پشتیبانی می‌کند، را ثبت کنید. (در واقع محلی برای مسیردهی کانال‌‎ها می‌باشد)

فایل console.php: مسیردهی دستورات آرتیسان

این فایل، جایی است که می‌توانید تمامی دستورات کنسول مبتنیبر Closure خود را در آن تعریف کنید. هر Closureای، به یک نمونه دستور متصل است؛ که یک رویکرد ساده برای تعامل با متد‌های IO هر دستوری را ارائه می‌دهد. هرچند این فایل، مسیرهای HTTP را تعریف نمی‌کند؛ اما نقاط ورود (مسیرهای) مبتنی بر کنسول را برای اپلیکیشن شما تعریف می‌کند.

فایل web.php: مسیردهی نسخه تحت وب (مهم‌ترین فایل مسیر)

این فایل، شامل مسیر (route)هایی است که RouteServiceProvider، در گروه میان‌‍افزار web قرار می‌دهد؛ که وضعیت session، حفاظت از CSRF و رمزگزاری کوکی‌ها را ایجاد می‌کند. اگر اپلیکیشن شما یک API RESTful را ارائه نکند، تمامی مسیرهای اپلیکیشن، به احتمال زیاد در فایل web.php تعریف می‌شوند.

دایرکتوری storage

پوشه storage، شامل تمامی قاب‌های بلدِ (Blade) کامپایل شده (همان ویوهای موجود در resources که نسخه خام است)،نشست (session)های مبتنی بر فایل، فایل‌های کش و و سایر فایل‌های تولید شده توسط فریم ورک می‌شود. دایرکتوری‌های زیر، داخل این دایرکتوری قرار دارند:

• app
• framework
• logs

دایرکتوری app:

این پوشه، می‌تواند برای ذخیره‌ی هر فایل تولید شده توسط اپلیکیشن شما مورد استفاده قرار گیرد.

همچنین داخل آن نیز یک دایرکتوری دیگری به نام public قرار دارد؛ که می‌تواند برای ذخیره فایل‌های تولید شده توسط کاربر، مانند آواتارهای پروفایل، که باید در دسترس عموم قرار گیرند، استفاده می‌شود. شما بایستی یک لینک نمادین (symbolic) به public/storage ایجاد کنید؛ که به این دایرکتوری اشاره کند. می‌توانید این لینک را با استفاده از دستور آرتیزن زیر ایجاد نمایید:

php artisan storage:link

دایرکتوری framework:

این پوشه، برای ذخیره فایل‌ها و کش‌های تولید شده در فریم ورک استفاده می‌شود.

دایرکتوری logs:

پوشه logs، فایل‌های لاگ اپلیکیشن شما را شامل می‌شود.

دایرکتوری tests

پوشه tests، شامل تست‌های اتوماتیک است. بیک مثال تست PHPUnit، درون پکیج پروژه‌ی لاراول ارائه شده است. هر کلاس تست بایستی پسوند Test داشته باشد. می‌توانید تست‌های خود را با استفاده از دستورات زیر اجرا کنید:

phpunit

php vendor/bin/phpunit

دستور آرتیزن برای ایجاد کلاس تست، به صورت زیر می‌باشد:

php artisan make:test ClassName

دایرکتوری vendor

پوشه vendor،وابستگی‌ها یا پکیج‌های کامپوزر را شامل می‌شود.