إدارة الوسائط

يتضمن FORGE نظام رفع ملفات متعدد الأشكال يتيح لأي نموذج في تطبيقك امتلاك ملفات وصور مرتبطة. يدعم النظام التخزين المحلي وS3 وتوليد متغيرات الصور تلقائياً وواجهة رفع بالسحب والإفلات في لوحة الإدارة.

نظرة عامة

يتبع نظام الوسائط نمط الارتباط متعدد الأشكال على طريقة Spatie. بدلاً من إضافة أعمدة ملفات لكل جدول، يتم تخزين جميع الرفوعات في جدول media مركزي وربطها بالنموذج الأب عبر أعمدة model_type و model_id. يتيح حقل collection مجموعات ملفات متعددة مميزة لكل نموذج (على سبيل المثال، صورة "مميزة" ومجموعة "معرض").

مخطط قاعدة البيانات

يخزن جدول media جميع الملفات المرفوعة:

العمود	النوع	الوصف
id	UUID	المفتاح الأساسي
disk	VARCHAR(20)	واجهة التخزين: local أو s3
path	VARCHAR(500)	مسار الملف النسبي ضمن قرص التخزين
filename	VARCHAR(255)	اسم الملف الأصلي
mime_type	VARCHAR(100)	نوع MIME (مثل image/jpeg، application/pdf)
size	BIGINT	حجم الملف بالبايت
width	INTEGER	عرض الصورة بالبكسل (nullable لغير الصور)
height	INTEGER	ارتفاع الصورة بالبكسل (nullable لغير الصور)
variants	JSONB	متغيرات الصور المُولّدة (صور مصغرة، نسخ مُعاد حجمها)
alt_text	VARCHAR(255)	النص البديل لإمكانية الوصول
caption	VARCHAR(500)	تعليق أو وصف اختياري
metadata	JSONB	بيانات وصفية إضافية للملف
model_type	VARCHAR(100)	نوع النموذج الأب (مثل content، user)
model_id	UUID	المفتاح الأساسي للنموذج الأب
collection	VARCHAR(100)	مجموعة مُسماة (مثل featured، gallery، avatar)
created_at	TIMESTAMP	طابع زمني لإنشاء السجل
updated_at	TIMESTAMP	طابع زمني لآخر تحديث

الارتباط متعدد الأشكال

يتم ربط الملفات بأي نموذج باستخدام مزيج من model_type و model_id و collection:

┌──────────────┐       ┌───────────────────────────────────────┐
│   contents   │       │               media                   │
│──────────────│       │───────────────────────────────────────│
│ id: uuid-1   │◄──────│ model_type: "content"                 │
│ title: About │       │ model_id:   "uuid-1"                  │
│              │       │ collection: "featured"                 │
└──────────────┘       │ filename:   "hero.jpg"                 │
                       └───────────────────────────────────────┘

┌──────────────┐       ┌───────────────────────────────────────┐
│    users     │       │               media                   │
│──────────────│       │───────────────────────────────────────│
│ id: uuid-2   │◄──────│ model_type: "user"                    │
│ name: Jane   │       │ model_id:   "uuid-2"                  │
│              │       │ collection: "avatar"                   │
└──────────────┘       │ filename:   "profile.png"              │
                       └───────────────────────────────────────┘

بنية كائن المتغيرات

يتم توليد متغيرات الصور عند الرفع وتُخزّن كـ JSONB:

{
  "thumbnail": {
    "path": "media/content/uuid-1/thumb_hero.jpg",
    "width": 150,
    "height": 150
  },
  "medium": {
    "path": "media/content/uuid-1/med_hero.jpg",
    "width": 600,
    "height": 400
  },
  "large": {
    "path": "media/content/uuid-1/lg_hero.jpg",
    "width": 1200,
    "height": 800
  }
}

واجهة MediaService API

توفر MediaService دوال لإدارة ارتباطات الملفات:

attach()

رفع وربط ملف بنموذج:

let media = media_service.attach(
    file,          // uploaded file data
    "content",     // model_type
    content.id,    // model_id
    "featured"     // collection name
).await?;

detach()

إزالة ارتباط ملف وحذف الملف من التخزين:

media_service.detach(media_id).await?;

get_for_model()

استرجاع جميع ملفات الوسائط لنموذج ومجموعة محددة:

let images = media_service.get_for_model(
    "content",     // model_type
    content.id,    // model_id
    "gallery"      // collection name
).await?;

get_first_for_model()

استرجاع أول (أو الوحيد) ملف وسائط لنموذج ومجموعة:

let avatar = media_service.get_first_for_model(
    "user",        // model_type
    user.id,       // model_id
    "avatar"       // collection name
).await?;

مزودو التخزين

يدعم نظام الوسائط واجهتي تخزين:

المزود	الوصف
local	تخزين الملفات على نظام الملفات المحلي
s3	تخزين الملفات في Amazon S3 أو تخزين متوافق

تتم إدارة إعدادات التخزين من خلال نظام مزودي التخزين. راجع ذلك القسم لتعليمات الإعداد المفصلة.

نصيحة

يمكنك المزج بين مزودي التخزين عبر المجموعات. على سبيل المثال، تخزين صور المستخدمين الشخصية محلياً للوصول السريع وصور المعرض الكبيرة على S3.

واجهة الإدارة

توفر لوحة الإدارة تجربة إدارة وسائط غنية من خلال صفحة مدير الوسائط المخصصة على /media.

صفحة مدير الوسائط

يوفر مدير الوسائط واجهة مركزية لرفع وإدارة ملفات الوسائط المستقلة (الملفات غير المرتبطة بأي نموذج محدد):

┌─────────────────────────────────────────────────────────┐
│                    مدير الوسائط                          │
├─────────────────────────────────────────────────────────┤
│  ┌───────────────────────────────────────────────────┐  │
│  │         منطقة الرفع (سحب وإفلات)                  │  │
│  │  [أيقونة] انقر للرفع أو اسحب الملفات هنا          │  │
│  │         يدعم ملفات متعددة                         │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │                  جدول البيانات                     │  │
│  │  [ ] │ معاينة │ اسم الملف │ النوع │ الحجم │ إجراءات│  │
│  │  [ ] │ [صورة] │ logo.png  │ صورة  │156KB │ [...]  │  │
│  │  [ ] │ [أيقونة]│ doc.pdf  │ PDF   │2.4MB │ [...]  │  │
│  │  [ ] │ [أيقونة]│ data.csv │ ملف   │ 89KB │ [...]  │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

الميزات

الميزة	الوصف
الرفع بالسحب والإفلات	إسقاط الملفات مباشرة على منطقة الرفع للرفع الفوري
رفع ملفات متعددة	اختيار أو إسقاط عدة ملفات دفعة واحدة
صور مصغرة للمعاينة	معاينة الصور مباشرة في الجدول
أيقونات أنواع الملفات	أيقونات مرئية لملفات PDF والمستندات والفيديو وأنواع الملفات الأخرى
نسخ الرابط	نقرة واحدة لنسخ رابط الملف الكامل للحافظة
فتح في تبويب جديد	رابط سريع لعرض الملف في تبويب متصفح جديد
البحث والفلترة	فلترة الملفات حسب اسم الملف أو النوع أو المجموعة
أعمدة قابلة للترتيب	ترتيب حسب اسم الملف أو الحجم أو تاريخ الرفع

الصلاحيات

يحترم مدير الوسائط الصلاحيات التالية:

الصلاحية	الإجراء
media.view	عرض قائمة الوسائط والوصول لصفحة مدير الوسائط
media.upload	رفع ملفات جديدة (إظهار/إخفاء منطقة الرفع)
media.delete	حذف الملفات (إظهار/إخفاء إجراء الحذف)

تعريفات الأعمدة

يعرض جدول البيانات الأعمدة التالية:

العمود	المحتوى
تحديد	مربع اختيار للتحديد الجماعي
معاينة	صورة مصغرة للصور، أيقونة نوع الملف للآخرين
اسم الملف	اسم الملف الأصلي مع نوع MIME
النوع	شارة تشير لنوع الملف (صورة، فيديو، PDF، مستند، ملف)
الحجم	حجم الملف بصيغة مقروءة (KB/MB)
المجموعة	المجموعة التي ينتمي إليها الملف
تاريخ الرفع	تاريخ الرفع
الإجراءات	نسخ الرابط، فتح في تبويب جديد، حذف

الوسائط المستقلة مقابل المرتبطة

يعرض مدير الوسائط جميع ملفات الوسائط بغض النظر عما إذا كانت مرتبطة بنموذج:

• الوسائط المستقلة: الملفات المرفوعة مباشرة عبر مدير الوسائط (بدون model_type أو model_id)
• الوسائط المرتبطة: الملفات المرتبطة بنموذج (مثل صور المستخدمين الشخصية، صور المحتوى)

كلا النوعين يظهران في مدير الوسائط للإدارة المركزية.

تحذير

حذف سجل النموذج الأب لا يحذف تلقائياً ملفات الوسائط المرتبطة. تأكد من أن معالجات الحذف تستدعي media_service.detach() لجميع الوسائط المرتبطة لتجنب الملفات اليتيمة في التخزين.

توليد متغيرات الصور

عند رفع ملف صورة، يُولّد النظام تلقائياً المتغيرات المُعدّة (thumbnail، medium، large). يتم تحديد أبعاد المتغيرات وإعدادات الجودة بواسطة إعدادات التطبيق.

# forge.yaml
media:
  variants:
    thumbnail:
      width: 150
      height: 150
      fit: cover
    medium:
      width: 600
      height: 400
      fit: contain
    large:
      width: 1200
      height: 800
      fit: contain

نصيحة

ينطبق توليد المتغيرات فقط على ملفات الصور (JPEG، PNG، WebP، GIF). الرفوعات غير الصور مثل PDFs أو المستندات تُخزّن كما هي بدون معالجة متغيرات.