بنية تطبيق لارافال المبدئية تهدف إلى توفير نقطة بداية للتطبيقات الكبيرة والصغيرة. بالطبع أنت حر في تنظيم تطبيقك كما تشاء. لارافال لا يفرض تقريبا أي قيود على مكان وضع أي صنف (class) معين مادام Composer يستطيع تحميله آليا.
عند البدء مع لارافال، العديد من المطورين يقعون في حيرة جراء عدم وجود مجلد Models. لكن ذلك أمر مقصود. وجدنا أن كلمة النماذج - models غامضة، فهي تعني العديد من الأشياء المختلفة للعديد من الأشخاص المختلفين. بعض المطورين يشير بـنموذج - model التطبيق إلى مجمل منطق العمل، بينما يشير آخرون بـالنماذج - models إلى الأصناف التي تتعامل مع قاعدة البيانات الارتباطية (relational database).
لهذا السبب، اخترنا وضع نماذج Eloquent في مجلد app مبدئيا، وتمكين المطوِّر من وضعها أينما يشاء.
مجلد app، كما تتوقع، يحوي الشفرة الرئيسة لتطبيقك. سنتَـطَـرَّق للحديث عن هذا المجلد بالتفصيل قريبا. لكن -تقريبا- جميع الأصناف (classes) في تطبيقك ستكون داخل هذا المجلد.
مجلد bootstrap يَضُـمُّ الملفات المُـمَـهِدة لتشغيل إطار العمل وإعداد التحميل التلقائي. هذا المجلد يَحْـوي كذلك مجلد cache الذي يضُـمُّ بدوره الملفات التي أنشأها إطار العمل لتحسين الأداء مثل ملفات ذاكرة التخزين المؤقت (cache files) للمُوَجِّـه (route) وللخدمات (services).
مجلد config، كما يوحي اسمه، يحوي ملفات الإعدادت الخاصة بتطبيقك. من الجيد الاطلاع على هذه الملفات والتعرف على الخيارات المتاحة.
مجلد database يحوي ملفات الترحيل والبذور (migration and seeds) لقاعدة بياناتك. إذا شئت يمكنك استعمال المجلد لاحتواء قاعدة بيانات SQLite.
مجلد public يحوي ملف index.php، الذي يمثل نقطة دخول كل الطلبات (requests) إلى تطبيقك. هذا المجلد يحوي أيضا ممتلكاتك (assets) مثل الصور، ملفات جافاسكريبت وCSS.
مجلد resources يحوي ملفات العروض (views) والخامات (raw) الخاصة بك والممتلكات الغير مُجَمَّـعة (un-compiled assets) مثل LESS، SASS أو جافاسكريبت. هذا المجلد يحوي أيضا ملفات اللغة.
مجلد routes يحوي كل تعريفات التوجيه (route definitions) لتطبيقك. افتراضيا، بعض ملفات التوجيه مُدرَجة مع لارافال: web.php وapi.php وconsole.php وchannels.php.
ملف web.php يحتوي على الموجهات التي يضعها RouteServiceProvider في مجموعة الوسيط (middleware group) web، الذي يقدم حالة الجلسة، حماية CSRF، وتشفير الكعكات (cookies). إذا كان تطبيقك لا يوفر واجهة برمجة تطبيقات (API) عديمة الحالة وRESTful، على الأرجح سيتم تعريف الموجهات الخاصة بك في ملف web.php.
ملف api.php يحوي الموجهات التي يضعها RouteServiceProvider في مجموعة الوسيط api، الذي يقدم معدَّل الحد. هذه الموجهات يتم إعدادها لتكون عديمة الحالة، لذا الطلبات عبر هذه الموجهات يتم إعدادها لتكون مُعَرَّفة عبر رموز (tokens) ولن يتم تمكينها من دخول حالة الجلسة.
يمكنك تعريف أوامر المعراض القائمة على الإغلاق (Closure based console commands) الخاص بك في ملف console.php. كل إغلاق مُقَيَّـد بمثيل أمر يمَكِّـن مقاربة سهلة من التعامل مع كل طرق مدخلات ومخرجات الأمر. بالرغم من أن هذا الملف لا يُعَرِّف طلبات HTTP، فهو يعرف نقاط الدخول القائمة على المعراض (موجهات) في تطبيقك.
يمكنك تسجيل كل قنوات بث الأحداث التي يدعمها تطبيقك في ملف channels.php.
مجلد storage يحوي قوالب Blade المترجمة، الجلسات القائمة على الملف، ملف ذاكرة التخزين المؤقتة (cache)، وملفات أخرى قام بإنشائها إطار العمل. هذا المجلد ينقسم إلى مجلدات app وframework وlogs. يمكن استخدام مجلد app لحفظ أي ملفات منشأة من قبل تطبيقك. يمكن استخدام مجلد framework لحفظ الملفات المنشأة وملفات ذاكرة التخزين المؤقتة. وأخيرا، يحوي مجلد logs ملفات السجل الخاصة بتطبيقك.
يمكن استخدام مجلد storage/app/public لحفظ الملفات المنشأة من طرف المستخدمين، مثل الصور الرمزية للملف الشخصي، التي ينبغي أن تكون متاحة للجميع. يجب عليك إنشاء رابط رمزي في public/storage يشير إلى هذا المجلد. يمكنك إنشاء الرابط باستعمال الأمر php artisan storage:link.
مجلد tests يحوي اختباراتك الأوتوماتيكية. مثلا PHPUnit متوفر افتراضيا. كل صنف (class) اختبار يجب أن يبدأ بكلمة Test. يمكنك تشغيل اختباراتك عبر الأمر phpunit أو الأمر php vendor/bin/phpunit.
مجلد vendor يحتوي تبعيات composer الخاصة بك.
يضم مجلد app معظم (ملفات) تطبيقك. بشكل افتراضي، مساحة اسم هذا المجلد هي App ويتم تحميلها آليا بواسطة composer باستعمال معيار PSR-4 للتحميل الآلي.
يحوي مجلد app عدة مجلدات أخرى منها Console وHttp وProviders. يمكنك اعتبار المجلدين ِConsole وHttp موفرين لواجهة برمجة تطبيقات (API) داخل تطبيقك. كل من بروتوكول HTTP وCLI آليات للتفاعل مع تطبيقك، لكنهما لا يحويان منطق التطبيق. بعبارة أخرى، هما طريقان لإصدار الأموار بسهولة إلى تطبيقك. يحوي مجلد Console كل أوامر Artisan الخاصة بك، بينما يحوي مجلد Http المتحكمات (controllers) الخاصة بك، الوسائط (middlewares)، والطلبات (requests).
عدة مجلدات أخرى يتم توليدها داخل مجلد app وذلك كلما قمت باستعمال أمر Artisan make لتوليد الأصناف. مثلا مجلد app/Jobs لن يكون موجودا حتى يتم تنفيذ الأمر make:job لتوليد صنف مهمة (job class).
{تلميح} العديد من الأصناف من مجلد
appيتم توليدها بواسطة Artisan عبر الأوامر. لرؤية الأوامر المتاحة، قم يتنفيذ الأمرphp artisan list makeفي الطرفية.
يحوي مجلد ِConsole أوامر Artisan المعدَّلة لتطبيقك. يمكن توليد تلك الأوامر عبر تنفيذ الأمر make:command. يحوي هذا المجلد أيضا نواة console الخاص بك، أين يتم تسجيل أوامر Artisan ويتم تعريف المهام المجدولة الخاصة بك.
هذا المجلد غير موجود بشكل افتراضي، لكن سيتم إضافته من أجلك عبر تنفيذ أوامرevent:generateوmake:event Artisan. يحوي مجلد Events، كما تتوقع، أصناف الأحداث. يمكن استعمال الأحداث لتنبيه أجزاء أخرى من تطبيقك أن نشاطا ما قد حدث، مما يوفر قدرا كبير من المرونة والفصل (decoupling).
يحوي مجلد Exceptions معالج الاستثناءات الخاص بتطبيقك وهو مكان مناسب لوضع أي استثناءات لتطبيقك. إذا كنت تريد تخصيص كيفية تسجيل وعرض الاستثناءات الخاصة بك، عليك تعديل صنف Handler في هذا المجلد.
يحوي مجلد Http المتحكمات الخاصة بك، الوسائط، وطلبات النماذج. تقريبا كل المنطق الذي سيعالج الطلبات الداخلة لتطبيقك سيتم وضعها في هذا المجلد.
افتراضيا هذا المجلد غير موجود، لكن سيتم إنشاؤه من أجلك عند تنفيذك أمر Artisan make:job. يحوي مجلد Jobs المهام القابلة للتصفيف الخاصة بتطبيقك. المهام يمكن تصفيفها من قِبَـل تطبيقك عبر تشغيلها بصفة متزامنة ضمن دورة حياة الطلب الحالي. المهام التي يتم تشغيلها بصفة متزامنة خلال الطلب الحالي يتم الإشارة إليها أحيانا بـ"أوامر" نظرا لأنها تطبيق لـنمط الأمر
افتراضيا هذا المجلد غير موجود، لكن سيتم إنشاؤه من أجلك عند تنفيذك للأوامر Artisan event:generate أو make:listener. يحوي مجلد Listeners الأصناف المسؤولة عن معالجة الأحداث الخاصة بك. يستقبل مستمعو الأحداث (Event listeners) حدثا ويقومون بتنفيذ المنطق ردا على الحدث الذي تم إطلاقه. مثلا، حدث UserRegistered يمكن معالجته عن طريق مستمع SendWelcomeEmail.
افتراضيا هذا المجلد غير موجود، لكن سيتم إنشاؤه من أجلك عند تنفيذك لأمر Artisan make:mail. يحوي مجلد Mail كل الأصناف الخاصة بك التي تمثل رسائل البريد الالكتروني التي تم إرسالها بواسطة تطبيقك. تُمكنك كائنات Mail من تغليف منطق إنشاء بريد إلكتروني في صنف واحد يمكن إرساله عبر الدالة Mail::send.
افتراضيا هذا المجلد غير موجود، لكن سيتم إنشاؤه من أجلك عند تنفيذك لأمر Artisan make:notification. يحوي مجلد Notifications تنبيهات الإعلامات ("transactional" notifications) التي يتم إرسالها عبر تطبيقك، مثل تنبيهات الأحداث التي تحدث داخل تطبيقك. ميزات تنبيه لارافال تجريد لإرسال تنبيهات عبر مجموعة متنوعة من التعريفات (drivers) مثل البريد الإلكتروني وSlack والإرساليات القصيرة SMS أو حفظها في قاعدة بيانات.
افتراضيا هذا المجلد غير موجود، لكن سيتم إنشاؤه من أجلك عند تنفيذك لأمر Artisan make:policy. يحوي مجلد Policies أصناف سياسة التصريح الخاصة بتطبيقك. السياسات تُستخدم لتحديد إمكانية تنفيذ إجراء معين لمورد معين بواسطة مستخدم معين. لمزيد من المعلومات، ألق نظرة على توثيق التصريح.
يحوي مجلد Providers كل مزَوِّدي الخدمة لتطبيقك. يُمَهِّـد مزوِّدو الخدمة تطبيقك عبر ربط الخدمات في حاوية الخدمة (service container)، تسجيل الأحداث، أو تنفيذ أي مهام أخرى ليكون تطبيقك على استعداد للطلبات الواردة.
في تطبيق لارافال جديد، يحوي هذا المجلد بعضا من المزوِّدين. يمكن إضافة مزودين داخل هذا الملف عند الحاجة.