Laravel/structure

مقدمة

تهدف هيكلية تطبيق Laravel الافتراضية إلى توفير نقطة بداية رائعة لكل من التطبيقات الكبيرة والصغيرة. بالطبع، أنت حر في تنظيم تطبيقك كما تشاء. لا يفرض Laravel أي قيود تقريبًا على مكان وجود أي صنف من أصناف مشروعك، طالما أن Composer يمكنه تحميل الصنف تلقائيًا.

أين هو مجلّد النماذج؟

عند عملية البدء مع Laravel، يشوشّ العديد من المطورين بسبب عدم وجود المجلّد models. ومع ذلك، فإن عدم وجود مثل هذا المجلّد هو متعمد. نجد كلمة "نماذج" غامضة لأنها تعني الكثير من الأشياء المختلفة للعديد من الناس المختلفين. يشير بعض المطورين إلى "نموذج" للتطبيق على أنه إجمالي منطق الأعمال الخاص به، بينما يشير آخرون إلى "النماذج" باعتبارها فئات تتفاعل مع قاعدة بيانات علائقية.

لهذا السبب، اخترنا وضع نماذج Eloquent في المجلّد app بشكل افتراضي، والسماح للمطورين بوضعها في مكان آخر إذا اختاروا ذلك.

مجلّد الجذر

مجلّد التطبيق

يحتوي مجلّد app، كما تتوقع، على الشفرة الأساسية للتطبيق. سنستكشف هذا الدليل بمزيد من التفاصيل قريبًا؛ ومع ذلك، تقريبًا ستكون كافة الفئات في التطبيق الخاص بك موجودة في هذا المجلّد.

مجلّد Bootstrap

يحتوي مجلّد bootstrap على ملف app.php الذي يعمل على تمهيد الإطار. يحتوي هذا المجلّد أيضًا على مجلّد cache الذي يحتوي على ملفات إنشاء إطار لتحسين الأداء مثل ملفات التخزين المؤقت للطريق والخدمات.

مجلّد الضبط

يحتوي مجلّد config، كما يوحي الاسم، على جميع ملفات تهيئة التطبيق الخاص بك. من المستحسن قراءة جميع هذه الملفات والتعرف على جميع الخيارات المتاحة لك.

مجلّد قواعد البيانات

يحتوي المجلّد database على عمليات تهجير قاعدة البيانات (database migrations)، ومصانع النماذج (model factories)، والبذور (seeds). إذا كنت ترغب في ذلك، يمكنك أيضًا استخدام هذا الدليل لتخزين بقاعدة بيانات SQLite.

المجلّد العام

يحتوي المجلّد public على ملف index.php، والذي يعد نقطة الإدخال لكافة الطلبات التي تدخل التطبيق الخاص بك، ويضبط التحميل التلقائي. يضم هذا المجلّد أيضًا ملفات الوسائط مثل الصور وملفات JavaScript و CSS.

مجلّد الموارد

يحتوي المجلّد resources على وجهات نظرك وكذلك الملفات الخام مثل LESS أو SASS أو JavaScript. يضم هذا المجلّد أيضًا جميع ملفات اللغة الخاصة بك.

مجلّد المسارات

يحتوي مجلّد routes على جميع تعريفات مسارات تطبيقك. بشكل افتراضي، تُضمَّن مع Laravel عدة ملفات مسار : web.php ،api.php  ،console.php  ،channels.php.

يحتوي الملف web.php على توجيهات يضعها RouteServiceProvider في مجموعة web الوسيطة (middleware group)، والتي توفر حالة جلسة العمل (session state) وحماية CSRF وتشفير ملفات تعريف الارتباط (cookie encryption). إذا كان تطبيقك لا يقدم RESTful API، فمن المرجح أن يتم تعريف جميع مساراتك في ملف web.php.

يحتوي ملف api.php على مسارات يضعها RouteServiceProvider في مجموعة البرمجيات الوسيطة api، والتي توفر معدل محدد (rate limiting). تهدف هذه المسارات إلى أن تصبح بدون حالة (stateless)، لذلك فإن الطلبات التي تدخل التطبيق من خلال هذه المسارات تهدف إلى الاستيثاق باستخدام رمز (token) ولن تتمكن من الوصول إلى حالة الجلسة.

ملف console.php هو المكان الذي يمكنك فيه تعريف كل النطاقات المغلقة (closure) التي تتعامل مع أوامر الطرفية. يرتبط كل نطاق مغلق بنسخة من الأمر مما يسمح بتبسيط للتفاعل مع توابع الإدخال والإخراج الخاصة بكل أمر. على الرغم من أن هذا الملف لا يعرف مسارات HTTP، فإنه يحدد نقاط الإدخال المستندة إلى وحدة التحكم (routes) في التطبيق الخاص بك.

ملف channels.php هو المكان الذي يمكنك فيه تسجيل جميع قنوات بث الأحداث التي يدعمها تطبيقك.

مجلّد التخزين

يحتوي المجلّد storage على قوالب Blade المجمّعة، والجلسات المستندة إلى الملفات، والملفات المخزنة مؤقتًا، وغيرها من الملفات التي تُنشَأ بواسطة إطار العمل. يُفصَل هذا المجلّد إلى مجلدات app و framework و logs. يمكن استخدام المجلّد app لتخزين أي ملفات تُنشَأ بواسطة التطبيق الخاص بك. يُستخدَم المجلّد framework لتخزين الملفات التي ولِّدَت من قبل الإطار والتخزين المؤقت. وأخيرًا، يحتوي مجلّد logs على ملفات سجل التطبيق الخاص بك.

يمكن استخدام المجلد storage/app/public لتخزين الملفات التي ينشئها المستخدم، مثل الصورة الرمزيّة، والتي يجب أن تكون متاحة للعموم. يجب إنشاء وصلة رمزية (symbolic link) في public/storage التي تُشير إلى هذا المجلد. يمكنك إنشاء الرابط باستخدام الأمر php artisan storage:link.

مجلّد الاختبارات

يحتوي المجلّد tests على اختباراتك الآلية. يتم توفير مثال PHPUnit نموذجي افتراضيًا. يجب أن يكون كل صنف اختبار ملحقًا بالكلمة 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 على وحدات التحكم والبرامج الوسيطة والطلبات.

ستُنشَأ مجموعة متنوعة من المجلّدات الأخرى داخل المجلّد app أثناء استخدام make في الأمر Artisan لتوليد الأصناف. لذلك، على سبيل المثال، لن يكون المجلّد app/Jobs موجودًا حتى تقوم بتنفيذ أمر  Artisan الآتي make:job لتوليد الصنف job..

يمكن إنشاء العديد من الأصناف في مجلّد app بواسطة Artisan عبر الأوامر. لمراجعة الأوامر المتاحة، قم بتشغيل الأمر php artisan list make في الطرفية.

مجلّد البث

يحتوي المجلّد Broadcasting على كافة فئات قناة البث للتطبيق الخاص بك. تُنشَأ هذه الأصناف باستخدام الأمر make:channel. هذا المجلّد غير موجود افتراضيًا، ولكن سيُنشَأ عند توليد أول قناة. لمعرفة المزيد عن القنوات، راجع صفحة بث الأحداث.

مجلّد التعامل مع Laravel باستخدام سطر الأوامر

يحتوي مجلّد Console على كافة أوامر Artisan المخصصة للتطبيق الخاص بك. قد تُنشَأ هذه الأوامر باستخدام الأمر make:command. يحتوي هذا المجلّد أيضاً على نواة وحدة التحكم الخاصة بك، حيث يتم تسجيل الأوامر المخصصة المخصصة الخاصة بك وتعيين المهام المجدولة الخاصة بك.

مجلّد الأحداث

هذا المجلّد غير موجود بشكل افتراضي، ولكن سيُنشَأ لك من قبل أوامر Artisan  event:generate و make:event. يحتوي المجلّد Events، كما تتوقع، على فئات الأحداث. يمكن استخدام الأحداث لتنبيه أجزاء أخرى من التطبيق الخاص بك أنَّ إجراءً معينًا قد حدث، وتوفير قدر كبير من المرونة والانفصال.

مجلّد الاستثناءات

يحتوي المجلّد Exceptions على معالجات الاستثناءات الخاص بالتطبيق وهو أيضًا مكان جيد لوضع أي استثناءات ترمى بواسطة التطبيق الخاص بك. إذا كنت ترغب في تخصيص كيفية تسجيل الاستثناءات أو تقديمها، فيجب تعديل فئة Handler في هذا الدليل.

مجلّد Http

يحتوي المجلّد Http على وحدات التحكم (controllers)، والبرامج الوسيطة (middleware)، وطلبات النموذج (form requests). توضع كل البنى المنطقية للتعامل مع الطلبات التي تدخل التطبيق الخاص بك في هذا المجلّد تقريبًا.

مجلّد الوظائف

هذا المجلّد غير موجود بشكل افتراضي، ولكن سيُنشَأ لك إذا نفّذتَ الأمر make:job Artisan. يحتوي المجلّد Jobs على طابور يضمّ المهام الخاصة بتطبيقك. قد يتم وضع المهام في قائمة الانتظار بواسطة التطبيق الخاص بك أو تعمل بشكل متزامن في دورة حياة الطلب الحالية. يشار أحيانًا إلى المهام التي تعمل بشكل متزامن أثناء الطلب الحالي باسم "الأوامر" نظرًا لأنها تنفيذ (implementation) لنمط التصميم command.

مجلّد المستمعين

هذا المجلّد غير موجود بشكل افتراضي، ولكن سيُنشَأ لك إذا نفَّذت أوامر Artistan وهي event:generate أو make:listener للمستمع. يحتوي المجلّد Listeners على الأصناف التي تتعامل مع الأحداث الخاصة بك. يتلقى مستمعو الطلب نسخة الحدث ويقومون بتنفيذ منطق استجابة للحدث الذي يتم تشغيله. على سبيل المثال، قد تتم معالجة الحدث UserRegistered بواسطة المستمع SendWelcomeEmail.

مجلّد البريد

هذا المجلّد غير موجود بشكل افتراضي، ولكن سيُتَأ لك إذا قمت بتنفيذ أمر make:mail Artisan. يحتوي المجلّد Mail على جميع المتغيرات  الخاصة بك التي تمثل رسائل البريد الإلكتروني المرسلة من تطبيقك. تسمح لك كائنات البريد بتغليف كل منطق بناء بريد إلكتروني في صنف واحد بسيط ومن ثم يمكن إرسال الرسائل باستخدام التابع Mail::send.

مجلّد الإشعارات

هذا المجلّد غير موجود بشكل افتراضي، ولكن سيُنشَأ لك إذا قمت بتنفيذ أمر make:notification Artisan. يحتوي المجلّد Notifications على جميع إشعارات "واجهة المستخدم وقاعدة البيانات القياسية" التي تُرسَل بواسطة التطبيق الخاص بك، مثل الإشعارات البسيطة حول الأحداث التي تحدث داخل التطبيق الخاص بك. يتضمّن إعلام Laravel مستخلصات ترسل إشعارات عبر مجموعة متنوعة من برامج التشغيل مثل البريد الإلكتروني أو Slack أو SMS أو مخزنة في قاعدة بيانات.

مجلّد السياسات

هذا المجلّد غير موجود بشكل افتراضي، ولكن سيتم إنشاؤه لك إذا قمت بتنفيذ أمر make:policy Artisan. يحتوي مجلّد Policies على أصناف الاستيثاق التابعة للتطبيق الخاص بك. تُستخدَم السياسات لتحديد ما إذا كان يمكن للمستخدم تنفيذ إجراء معين على مورد ما. لمزيد من المعلومات، راجع وثائق الاستيثاق.

مجلّد مقدّمي الخدمات

يحتوي مجلّد Providers على جميع مقدّمي خدمات التطبيق. يقوم مقدمو الخدمات بتمهيد التطبيق الخاص بك عن طريق ربط الخدمات في حاوية الخدمة، أو تسجيل الأحداث، أو القيام بأية مهام أخرى لإعداد طلبك للطلبات الواردة.

في تطبيق Laravel جديد، سيحتوي هذا المجلّد بالفعل على العديد من مقدّمي الخدمات. أنت حر في إضافة مزوديك الخاصين إلى هذا الدليل حسب المجلّد.

مجلّد القواعد

هذا المجلّد غير موجود بشكل افتراضي، ولكن سيُنشَأ لك إذا قمت بتنفيذ أمر make:rule Artisan. يحتوي المجلّد Rules على كائنات التحقق من القواعد (validation rule objects) المخصصة للتطبيق الخاص بك. يتم استخدام القواعد لتغليف منطق التحقق المعقد في كائن بسيط. لمزيد من المعلومات، راجع صفحة التحقق من الصحة.

مصادر

• صفحة Directory Structure في توثيق Laravel الرسمي.