#P1539
DELETE /media/s3
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| DELETE | /api/v2/media/s3 | S3Controller@deleteMedia | authWithJwt | حذف فایل(ها) از Liara S3 و پاک کردن رکورد در پایگاه داده media |
منطق عملکرد تابع
تابع deleteMedia به منظور حذف فایلهای ذخیرهشده در فضای S3‑Compatible (Liara) و پاکسازی رکوردهای مرتبط از جدول media طراحی شده است.
- بررسی وجود پارامترهای
related_id،idوpathدر درخواست. - جستجوی مدیاهای مطابق با یکی از شرایط:
- بر اساس
path - بر اساس
id - بر اساس
related_categoryوrelated_id(همراه باrelated_type)
- بر اساس
- بررسی وجود فایل در Storage (
disk:liara)، در صورت وجود حذف فیزیکی. - ثبت پیام برای هر فایل حذف شده یا یافت نشده در آرایه
deleted. - حذف رکورد مدیا از جدول
media. - برگرداندن نتیجه عملیات به همراه زمان و آرایه جزئیات حذف.
پارامترهای ورودی
| نام | محل | نوع | الزامی | توضیح |
| id | Query/Body | integer | خیر* | شناسه مدیا (در صورت عدم ارسال path یا related_id) |
| path | Query/Body | string | خیر* | مسیر کامل فایل در S3 (در صورت عدم ارسال id یا related_id) |
| related_id | Query/Body | integer | خیر* | شناسه شیء مرتبط (در صورت عدم ارسال id یا path) |
| related_type | Query/Body | string | خیر | نوع آیتم مرتبط (جهت استفاده با related_id) |
* حداقل یکی از پارامترهای id، path یا related_id باید ارسال شود.
ساختار خروجی
{
"status": true,
"time": 1732365500,
"deleted": [
"12 - uploads/profile/images/2025/11/img123.jpg - File deleted successfully",
"15 - uploads/profile/images/2025/11/img999.jpg - File not found"
]
}
نکات امنیتی
- دسترسی به مسیر محدود به کاربران Authenticate با توکن JWT معتبر است.
- اطلاعات ورودی باید در سطح تأیید کاربر (Authorization) کنترل شود تا امکان حذف فایلهای غیرمرتبط نباشد.
- از آنجا که نام فایل/مسیر ورودی میتواند دلخواه ارسال شود، جلوگیری از Directory Traversal ضروری است.
عملکرد
- چک وجود فایل (
Storage::exists) قبل از حذف، تا حدود ۱–۲ میلیثانیه هزینه دارد. - حذف فایلهای زیاد به صورت Loop انجام میشود و برای Batch های بالا، ممکن است زمان پاسخ افزایش یابد.
Dependencies
- use Illuminate\Support\Facades\Storage;
- use Illuminate\Support\Facades\DB;
کدهای خطا
| کد | شرح | منبع |
| 400 | عدم ارسال پارامترهای الزامی | Validation |
| 401 | توکن JWT نامعتبر یا منقضی | Authentication |
پیشنهادهای امنیتی
- بررسی مالکیت فایل (Owner Check) قبل از حذف.
- لاگ کامل حذف در جدول Audit Logs به همراه IP، UserID و زمان.
- غیرفعالسازی حذف مستقیم از S3 برای کاربر نهایی، تنها از طریق API Server.
پیشنهادهای توسعهای
- ایجاد قابلیت حذف گروهی (بر اساس لیست IDها یا مسیرها) با یک درخواست.
- امکان Soft‑Delete (فقط علامتگذاری به عنوان حذف شده در DB، بدون حذف فیزیکی).
- نمایش پیشنمایش فایلهای موجود و تأیید حذف از سمت کلاینت.
ممیزی و ثبت وقایع
- پیشنهاد ثبت هر حذف در جدول
media_deletion_logsبا جزئیات پارامترهای ارسالی.
جمعبندی
deleteMedia یک مسیر حذف ایمن برای مدیریت فایلهای فضای S3 در سامانه است که هم حذف فیزیکی فایل را انجام میدهد و هم پاکسازی بانک اطلاعاتی را؛ در صورت پیادهسازی لاگ و کنترل مالکیت، این فرایند میتواند ضدگلوله شود.