هيكل مجلدات مشروع Laravel 11 — وظيفة كل ملف ومجلد

1. النظرة الشاملة على هيكل مشروع Laravel

عند إنشاء مشروع Laravel جديد، ستجد هذا الهيكل في مجلد مشروعك. لا تنصدم من عدد الملفات — معظمها لن تحتاج لتعديله أبداً في البداية. ركّز على ما سنشرحه:

my-first-app/
│
├── app/                   ← 🟥 هنا تكتب معظم كودك
│   ├── Http/
│   │   ├── Controllers/   ← المتحكمات
│   │   └── Middleware/    ← طبقات الفحص
│   ├── Models/            ← نماذج قاعدة البيانات
│   └── Providers/         ← Service Providers
│
├── bootstrap/             ← إعداد التطبيق عند التشغيل (لا تعدّله)
├── config/                ← ملفات الإعداد (قاعدة بيانات، بريد، ...)
├── database/              ← 🟥 Migrations وSeeders والـ Factories
│   ├── migrations/        ← بناء جداول قاعدة البيانات
│   ├── seeders/           ← شحن بيانات تجريبية
│   └── factories/         ← توليد بيانات وهمية للاختبار
│
├── public/                ← 🟥 الوحيد المكشوف للإنترنت
│   └── index.php          ← نقطة الدخول الوحيدة
│
├── resources/             ← 🟥 الواجهات وملفات CSS/JS الأصلية
│   ├── views/             ← صفحات Blade
│   ├── css/               ← ملفات CSS قبل المعالجة
│   └── js/                ← ملفات JS قبل المعالجة
│
├── routes/                ← 🟥 تعريف روابط موقعك
│   ├── web.php            ← روابط الموقع العادي
│   └── api.php            ← روابط الـ API
│
├── storage/               ← ملفات مرفوعة، logs، cache
├── tests/                 ← اختبارات تلقائية
├── vendor/                ← مكتبات Composer (لا تعدّلها أبداً)
│
├── .env                   ← 🟥 كلمات المرور والمفاتيح السرية
├── .env.example           ← نموذج .env للمشاركة مع الفريق
├── composer.json          ← تبعيات PHP
├── package.json           ← تبعيات JavaScript (Node.js)
└── vite.config.js         ← إعداد Vite لتجميع CSS/JS

2. مجلد app/ — قلب تطبيقك

هذا هو المجلد الذي ستقضي فيه 70% من وقتك. كل منطق تطبيقك يعيش هنا. لنشرح أهم مجلداته:

app/Models/ — العلاقة مع قاعدة البيانات

كل جدول في قاعدة بياناتك له Model مقابل له هنا. Model هو الكلاس الذي يمثّل الجدول ويسمح لك بالتعامل معه بكود PHP أنيق عوضاً عن كتابة استعلامات SQL يدوياً.

class Article extends Model
{
    // الأعمدة التي يمكن ملؤها عبر النماذج (Forms)
    protected $fillable = ['title', 'content', 'user_id'];

    // علاقة: كل مقال ينتمي لمستخدم واحد
    public function user()
    {
        return $this->belongsTo(User::class);
    }
}

لإنشاء Model جديد بدون كتابة الكود يدوياً، استخدم Artisan:

app/Http/Controllers/ — المتحكمات

Controllers هي الوسيط بين الطلب (Request) وقاعدة البيانات والعرض (View). عندما يطلب مستخدم /articles، Router يوجّه الطلب لـ Controller الذي يجلب البيانات ويرسلها للعرض.

class ArticleController extends Controller
{
    // عرض قائمة المقالات
    public function index()
    {
        $articles = Article::latest()->paginate(10);
        return view('articles.index', compact('articles'));
    }

    // عرض مقال واحد
    public function show(Article $article)
    {
        return view('articles.show', compact('article'));
    }
}

app/Http/Middleware/ — طبقات الفحص

شرحناها في الدرس السابق. هنا ستجد Middleware مدمجة مع لارافيل مثل Authenticate.php وهنا أيضاً ستضع Middleware تنشئها بنفسك لاحقاً.

3. مجلد routes/ — خارطة روابط موقعك

هذا المجلد هو "دليل الهاتف" لموقعك — يربط كل رابط بالكود الذي يعالجه. في Laravel 11 ستجد بشكل أساسي ملفين:

routes/web.php — روابط الموقع العادي

كل رابط تراه في متصفحك ويُرجع صفحة HTML، يُعرَّف هنا. هذه الروابط تدعم الجلسات (Sessions) وحماية CSRF تلقائياً.

use App\Http\Controllers\ArticleController;

// صفحة المقالات — يتطلب تسجيل الدخول
Route::middleware('auth')->group(function () {
    Route::resource('articles', ArticleController::class);
});

// الصفحة الرئيسية — متاحة للجميع
Route::get('/', function () {
    return view('welcome');
});

routes/api.php — روابط الـ API

عندما تبني API لتطبيق موبايل أو Single Page Application (Vue/React)، تضع روابطه هنا. هذه الروابط لا تستخدم الجلسات — تعتمد على Tokens للمصادقة. كل رابط هنا يُضاف تلقائياً قبله /api/.

// هذا الرابط يعني: GET /api/articles
Route::get('/articles', [ArticleController::class, 'index']);

// مجموعة روابط محمية بـ Sanctum token
Route::middleware('auth:sanctum')->group(function () {
    Route::post('/articles', [ArticleController::class, 'store']);
});

4. مجلد database/ — بناء قاعدة البيانات بكود

هذا أحد أروع مفاهيم Laravel: لا تبني جداول قاعدة البيانات بيدك في phpMyAdmin. بدلاً من ذلك، تكتب كوداً PHP يصف شكل الجدول — وLaravel ينشئه وينظّمه تلقائياً. هذا يسمى Database Migrations.

database/migrations/ — تاريخ قاعدة بياناتك

كل Migration هو ملف PHP يصف تعديلاً على قاعدة البيانات في لحظة زمنية معينة. مثلاً: "أنشئ جدول articles يوم 2026-02-20". فائدة هذا النهج أن أي شخص في الفريق يستطيع تشغيل php artisan migrate ويحصل على نفس قاعدة البيانات تماماً.

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('articles', function (Blueprint $table) {
            $table->id();                          // عمود id تلقائي
            $table->string('title');               // عنوان المقال
            $table->longText('content');           // محتوى المقال
            $table->boolean('published')->default(false);
            $table->foreignId('user_id')->constrained(); // مفتاح خارجي
            $table->timestamps();                  // created_at و updated_at
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('articles');          // للتراجع عن التغيير
    }
};

لإنشاء Migration جديد:

لتطبيق كل Migrations على قاعدة البيانات:

للتراجع عن آخر Migration مطبّق:

database/seeders/ — شحن بيانات تجريبية

Seeders تسمح لك بملء قاعدة البيانات ببيانات تجريبية بأمر واحد. مفيد جداً أثناء التطوير — بدلاً من إدخال بيانات يدوياً في كل مرة تُعيد فيها قاعدة البيانات.

database/factories/ — توليد بيانات وهمية ذكية

Factories تعمل مع Seeders لتوليد بيانات وهمية ولكن واقعية المظهر (أسماء حقيقية، جمل منطقية). مثلاً: إنشاء 100 مستخدم وهمي لاختبار أداء الموقع تحت الضغط.

5. مجلد resources/ — واجهاتك وتنسيقاتها

كل ما يراه المستخدم على الشاشة يأتي من هنا.

resources/views/ — صفحات Blade HTML

هنا تضع ملفات الـ HTML الخاصة بموقعك، لكن بصيغة Laravel الخاصة (Blade). الملفات تنتهي بـ .blade.php. Blade يسمح لك بوضع متغيرات PHP داخل HTML بطريقة نظيفة جداً.

@extends('layouts.app')

@section('content')
    <h1>كل المقالات</h1>

    @foreach ($articles as $article)
        <div>
            <h2>{{ $article->title }}</h2>
            <p>{{ $article->content }}</p>
        </div>
    @endforeach

    {{ $articles->links() }}  {{-- ترقيم الصفحات --}}
@endsection

لاحظ أن @foreach و@extends و@section هي بناء Blade — أنيق وواضح بدون خلط PHP وHTML بطريقة الفوضوية القديمة.

resources/css/ و resources/js/

هنا تضع ملفات CSS وJavaScript الأصلية قبل المعالجة. أداة Vite تأخذها، تدمجها، تضغطها، وتضعها في مجلد public/build/ جاهزة للمتصفح.

هذا الأمر يشغّل Vite في وضع التطوير ويراقب التغييرات تلقائياً.

6. مجلد public/ — الواجهة المكشوفة للعالم

هذا مهم جداً من ناحية الأمان. مجلد public/ هو الوحيد الذي يستطيع أي شخص على الإنترنت الوصول إليه مباشرةً. باقي مجلدات المشروع (بما فيها app/ و.env) خارج نطاق الوصول العام.

ماذا يوجد في public/؟

• index.php — نقطة الدخول الوحيدة (شرحناها في الدرس السابق)
• build/ — ملفات CSS وJS بعد معالجة Vite
• صور، أيقونات، وأي ملف تريد أن يكون متاحاً للعموم مباشرةً

7. مجلد storage/ — التخزين الداخلي

هذا المجلد للتخزين الداخلي الذي لا يصل إليه المستخدمون مباشرةً:

• storage/logs/ — سجلات الأخطاء. أول مكان تنظر فيه عند حدوث مشكلة.
• storage/app/ — الملفات التي يرفعها المستخدمون (صور، وثائق). تحتاج إنشاء رابط رمزي لإتاحتها.
• storage/framework/cache/ — ملفات الكاش لتسريع التطبيق.

لإتاحة الملفات المرفوعة في storage/app/public/ للعموم:

هذا الأمر ينشئ رابطاً رمزياً (Symlink) من public/storage → storage/app/public.

8. ملف .env — أسرار مشروعك

هذا الملف في جذر المشروع (خارج كل المجلدات) وهو من أهم الملفات في Laravel. يحتوي على كل المعلومات الحساسة التي تختلف من بيئة لأخرى: كلمات مرور قاعدة البيانات، مفاتيح API، إعدادات البريد الإلكتروني.

APP_NAME=Laravel
APP_ENV=local          # local أو production
APP_KEY=base64:...     ← مفتاح التشفير الفريد لمشروعك
APP_DEBUG=true         # true في التطوير، false في الإنتاج ⚠️
APP_URL=http://localhost

DB_CONNECTION=sqlite   # أو mysql أو pgsql
DB_HOST=127.0.0.1
DB_DATABASE=my_database
DB_USERNAME=root
DB_PASSWORD=

MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587

من أي مكان في الكود، تستطيع الوصول لقيم .env هكذا:

// قراءة قيمة مباشرة
$appName = env('APP_NAME');

// قراءة من ملفات config (الأفضل)
$appName = config('app.name');
$dbConnection = config('database.default');

9. مجلد vendor/ وملف composer.json

مجلد vendor/

هذا المجلد ينشئه Composer تلقائياً عند تثبيت المشروع. يحتوي على كل مكتبات PHP التي يعتمد عليها Laravel (وهي مئات المكتبات من آلاف المساهمين).

ملف composer.json

هذا الملف يشبه قائمة التسوق — يحدد اسم المكتبات التي يحتاجها مشروعك وإصداراتها. Composer يقرأ هذا الملف ويحمّل كل المكتبات المطلوبة.

لأول تثبيت بعد سحب مشروع من GitHub.

لإضافة مكتبة جديدة للمشروع (مثال: مكتبة إدارة الصلاحيات).

10. ملخص — ماذا تكتب أين؟

جدول مرجعي للرجوع إليه في أي وقت: