Skip to main content
#P1723

RESOURCE /v2/media

Media Management (File Storage)

این ماژول وظیفه مدیریت فایل‌ها و رسانه‌های سیستم را بر عهده دارد.
برخلاف ذخیره‌سازی محلی، این کنترلر مستقیماً با فضای ذخیره‌سازی ابری (Liara Object Storage) در ارتباط است. فایل‌ها بر اساس نوع، شعبه، سال و ماه در پوشه‌بندی‌های منظم ذخیره شده و متادیتای آن‌ها (شامل سایز، مسیر و ارتباط با سایر موجودیت‌ها) در دیتابیس نگهداری می‌شود.

1. Upload File (Store)

URL: /v2/media
Method: POST
Controller: MediaController@store
Content-Type: multipart/form-data

Body Parameters

Field Type Description
file File (الزامی) فایل باینری جهت آپلود (تصویر، سند و...).
branch integer (الزامی) شناسه شعبه (جهت ساختار پوشه‌بندی).
type string (الزامی) نوع فایل (مثلاً `slider`, `avatar`, `document`) که نام پوشه اصلی را تعیین می‌کند.
path string (اختیاری) پیشوند مسیر ذخیره‌سازی. اگر ارسال نشود، پیش‌فرض uploads در نظر گرفته می‌شود.
related_id integer (اختیاری) شناسه رکورد مرتبط (مثلاً ID هتل یا مقاله).
related_category string (اختیاری) دسته‌بندی رکورد مرتبط (مثلاً `articles`).
operator object (تزریق سیستمی) آبجکت اپراتور (از طریق میدل‌ور Auth) برای ثبت در فیلد operator_id.

Upload Logic Details

  1. دریافت و آماده‌سازی فایل:
    • استخراج پسوند (Extension) و نام اصلی فایل.
    • نام فایل در دیتابیس بدون پسوند ذخیره می‌شود.
  2. ساخت مسیر ذخیره‌سازی (Path Generation):
    مسیر فایل به صورت دینامیک بر اساس تاریخ جاری و ورودی‌ها ساخته می‌شود:
    {base_path}/{branch}/{type}/{Year}/{Month}/{ext}/
    • اگر پارامتر path ارسال شود، به عنوان base_path استفاده می‌شود.
    • در غیر این صورت، uploads به عنوان پیش‌فرض قرار می‌گیرد.
  3. ذخیره‌سازی فیزیکی (Liara Disk):
    • استفاده از Storage::disk('liara')->putFileAs(...).
    • فایل با نام اصلی + پسوند در مسیر ساخته شده آپلود می‌شود.
    • سپس سایز واقعی فایل آپلود شده از دیسک ابری استعلام می‌شود (size()).
  4. ثبت در دیتابیس:
    • رکورد جدید با اطلاعات کامل (شامل مسیر کامل path، سایز، نوع و ارتباطات) در جدول media ایجاد می‌شود.

Flowchart (Upload Process)

Start Request
↓
Extract File info
(Ext, Name)
↓
Has Custom Path?
Yes
Base = $request->path
No
Base = 'uploads'
↓
Generate Path Structure
base/branch/type/Y/m/ext/
↓
Liara Storage Upload
putFileAs() & get Size()
↓
Create DB Record & Return

2. List Media (Index)

URL: /v2/media
Method: GET
Controller: MediaController@index

لیست فایل‌های آپلود شده به صورت صفحه‌بندی شده (۱۵ تایی).

فیلترهای جستجو (Query Params)

  • operator_id: شناسه آپلود کننده.
  • related_id: شناسه رکورد مرتبط.
  • related_category: دسته‌بندی مرتبط.
  • type: نوع فایل.
  • branch: شعبه.
  • status: وضعیت فایل.
  • sortById: اگر ارسال شود (true)، مرتب‌سازی نزولی (جدیدترین‌ها) اعمال می‌شود.

3. Update Media Status

URL: /v2/media/{id}
Method: PUT/PATCH
Controller: MediaController@update

توجه: در متد آپدیت، فایل فیزیکی یا مسیر آن تغییر نمی‌کند. تنها می‌توان وضعیت (Status) فایل را تغییر داد.

{
  "status": 0 // غیرفعال کردن فایل
}

4. Delete Media

URL: /v2/media/{id}
Method: DELETE
Controller: MediaController@destroy

عملیات حذف دومرحله‌ای:

  1. ابتدا با استفاده از مسیر ذخیره شده در دیتابیس (`path`)، فایل فیزیکی از دیسک Liara حذف می‌شود (`Storage::disk('liara')->delete`).
  2. سپس رکورد از دیتابیس پاک می‌شود.
Back to top