پرش به مطلب اصلی

File Manager

FileManager سیستم مدیریت فایل در Doravel است که امکان آپلود، پردازش و مدیریت فایل‌ها را با پشتیبانی از درایورهای مختلف (local و S3 و SFTP) فراهم می‌کند.

مقدمه​

مدیریت فایل (File Manager) برای سهولت بیشتر در استفاده، دسترسی آسان‌تر، قابلیت‌های بیشتر و رعایت ساختار مشخص طراحی شده است.

این سرویس قابلیت‌های زیر را ارائه می‌دهد:

  • آپلود فایل‌ها
  • دریافت اطلاعات فایل‌ها
  • دریافت لینک فایل‌ها
  • بررسی وجود فایل‌ها
  • حذف فایل‌ها
  • حذف موقت و بازگردانی فایل‌ها

این عملیات ها در دو Disk Driver در حالت های LOCAL و DATABASE پشتیبانی می‌شوند.

برای سهولت استفاده، این سرویس با Facade ارائه شده است:

Dornica\Foundation\FileManager\Facade\FileManager

FileManager یک سرویس قدرتمند برای مدیریت فایل‌ها در Doravel است که به شما امکان می‌دهد:

  • آپلود فایل‌ها با درایورهای مختلف
  • تعیین دیسک و درایور مورد نظر
  • اتصال فایل‌ها به موجودیت‌های مختلف (Entity)
  • اعتبارسنجی فایل‌ها قبل از آپلود
  • پردازش و مدیریت فایل‌ها

درایورها​

کلید default_disk_driver در تنظیمات (dornica-app.file_manager) اضافه شده است که مقادیر database و local را می‌پذیرد.

درایور Local​

در این روش اطلاعات دیسک ها از دیسک های ثبت شده در لاراول در فایل filesystems.php خوانده می‌شود. در صورت عدم انتخاب دیسک، دیسک پیش‌فرض لاراول انتخاب می‌شود.

درایور Database​

در این روش اطلاعات دیسک ها از دیتابیس جدول file_disks خوانده می‌شود و دیسک به صورت موقت در لاراول ساخته می‌شود تا عملیات آپلود و مدیریت فایل‌ها انجام شود. در صورت عدم انتخاب دیسک، دیسک اولویت بالاتر انتخاب می‌شود.

جدول file_disks شامل فیلدهای زیر است:

فیلدنوعتوضیح
idintegerشناسه یکتا
titlestringعنوان دیسک
namestringنام دیسک (برای استفاده در کد)
hostnamestringآدرس hostname
portintegerپورت اتصال
driverintegerنوع درایور (local یا sftp یا s3)
base_pathstringمسیر پایه
priorityintegerاولویت دیسک
auth_typeintegerنوع احراز هویت (no auth یا basic یا ssh key based)
auth_fieldsjsonفیلدهای احراز هویت (مثال: username و password و private_key و passphrase)
optionsjsonگزینه‌های اضافی
started_atdatetimeزمان شروع استفاده از دیسک
expired_atdatetimeزمان پایان استفاده از دیسک
is_expiredbooleanمنقضی شدن دیسک
is_activebooleanفعال بودن دیسک
descriptionstringتوضیحات اضافی
اولویت دیسک

در صورت عدم مشخص کردن دیسک در هنگام آپلود، دیسک با اولویت بالاتر انتخاب می‌شود (عدد کمتر اولویت بالاتر است).

مدل‌ها​

در FileManager مدل (Model) هایی وجود دارد که هرکدام مسئولیت نگهداری اطلاعات بخش خاصی از سیستم مدیریت فایل را دارند.

این مدل‌ها در فایل کانفیگ dornica-app.php قابل مقداردهی و جایگزینی با مدل جدید خودتان هم هستند.

مدل‌های FileManager در فایل کانفیگ dornica-app.php
'models' => [
    'file' => \Dornica\Foundation\FileManager\Models\File::class,
    'file_disk' => \Dornica\Foundation\FileManager\Models\FileDisk::class,
    'file_type' => \Dornica\Foundation\FileManager\Models\FileType::class,
],

در ادامه، ویژگی‌ها، کاربرد و فیلدهای هریک را معرفی می‌کنیم:

File مدل فایل​

این مدل، اطلاعات مربوط به هر فایل آپلود شده (اعم از عکس، سند، ویدیو و ...) را در بانک اطلاعاتی نگه می‌دارد.

ویژگی‌های مهم:

  • id: کلید یکتا برای هر فایل
  • name: نام اصلی فایل در سیستم
  • uploader_type, uploader_id: اطلاعات مدل و کاربر آپلودکننده
  • file_type_id: شناسه نوع فایل (مثلاً قرارداد، کارت ملی و ...)
  • file_disk_id: شناسه دیسک نگهدارنده فایل (در صورتی که دیسک درایور database باشد)
  • file_disk_name: نام دیسک (درصورتی که دیسک درایور local باشد)
  • mime_type: نوع mime (مثلاً image/png)
  • extension: پسوند فایل
  • size: حجم فایل (بایت)
  • path: مسیر نگهداری فایل
  • full_month: ماه میلادی آپلود
  • original_name: نام اصلی فایل آپلود شده
  • is_private: خصوصی بودن فایل
  • is_deleted, deleted_at, deleted_by: اطلاعات حذف شدن
  • created_at, updated_at: تاریخ‌های ثبت و ویرایش

FileDisk مدل دیسک فایل ها​

مشخصات تمام دیسک‌ها و سرورهای ذخیره‌سازی (local, sftp, s3 و...) در این مدل ذخیره می‌شود.

ویژگی‌های مهم:

  • id: کلید یکتا
  • title: عنوان خوانا
  • name: نام لاتین یکتا برای دسترسی برنامه
  • hostname, port: اطلاعات اتصال
  • driver: نوع درایور (local، s3، sftp و ...)
  • base_path: مسیر پایه فایل‌ها
  • priority: اولویت نمایش/استفاده
  • auth_type: روش یا نوع احرازهویت
  • auth_fields: اطلاعات احراز هویت مورد نیاز (username، password یا کلید SSH و غیره)
  • options: گزینه‌ها تکمیلی دیسک
  • description: توضیحات تکمیلی
  • started_at, expired_at, is_expired: زمان و انقضا
  • سایر فیلدهای مدیریت و حذف منطقی

FileType مدل انواع فایل​

اطلاعات نوع فایل (مثلاً کارت ملی، تصویر پرسنلی، قرارداد و ...) را نگهداری می‌کند و قواعد و محدودیت‌های مربوط به نوع فایل مانند حجم، پسوند و الزامی بودن را دارد.

ویژگی‌های مهم:

  • id: کلید یکتا
  • name: نام قابل‌نمایش
  • code: کد یکتا
  • type: نوع فایل
  • gender: جنسیت‌محور بودن یا نبودن (در صورت نیاز)
  • max_size: بیشینه حجم مجاز
  • allowed_extensions: پسوندهای مجاز
  • is_required, is_private, is_active: قوانین و وضعیت
  • سایر فیلدهای مدیریتی و حذف
اطلاع

برای ستون type باید یک Enum با کپی کردن از Enum موجود در زیرساخت در پروژه ایجاد کنید و انواع فایل‌های خود را اضافه و با استفاده از این فیلد اقدام به دریافت انواع کنید.

برای ترجمه‌ی برچسب این Enum، بخش ترجمه‌ی نوع کاربرد فایل را ببینید.

ترجمه‌ی نوع کاربرد فایل​

نوع کاربرد فایل از یک Enum خوانده می‌شود که هر پروژه می‌تواند آن را با Enum خودش جایگزین کند. برچسب هر case از فایل ترجمه خوانده می‌شود و در چهار جا نمایش داده می‌شود: فرم درج، فرم ویرایش، فیلتر لیست و ستون جدول.

برچسب‌ها همیشه از ماژول ترجمه‌ی files خوانده می‌شوند. پروژه‌ای که case اضافه می‌کند، ترجمه‌ی caseهای خودش را در فایل ترجمه‌ی همان ماژول در پروژه می‌نویسد و لاراول آن را روی فایل زیرساخت ادغام می‌کند.

معرفی Enum پروژه​

config/dornica-app.php
'file_manager' => [
    'file_type_enum' => \Modules\YourModule\Enums\FileType::class,
],

افزودن ترجمه در پروژه​

ابتدا فایل ترجمه‌ی زیرساخت در پروژه منتشر می‌شود:

php artisan vendor:publish --tag=files-translations

تگ‌های files-lang، dornica-translations و dornica-lang هم همین کار را انجام می‌دهند.

هشدار

اگر فایل lang/vendor/files/fa/enum.php را از قبل دارید و در آن ترجمه نوشته‌اید، دستور بالا بدون --force آن را دست‌نخورده باقی می‌گذارد و از رویش رد می‌شود.

اما اجرای آن با --force فایل شما را کاملاً با نسخه‌ی زیرساخت جایگزین می‌کند و تمام کلیدهایی که پروژه اضافه کرده بود از بین می‌رود. پیش از استفاده از --force نسخه‌ی پشتیبان بگیرید.

سپس caseهای پروژه به فایل منتشرشده اضافه می‌شوند:

lang/vendor/files/fa/enum.php
return [
    'file_type' => [
        'product' => 'محصول',
        'blog_category' => 'دسته‌بندی مطلب',
    ],
];

کلید ترجمه به این شکل ساخته می‌شود:

files::enum.file_type.<نام case به حروف کوچک>

ادغام با ترجمه‌ی زیرساخت​

لاراول این فایل را روی فایل زیرساخت ادغام می‌کند، نه جایگزین. یعنی هر کلیدی که در فایل پروژه نباشد، از فایل زیرساخت خوانده می‌شود:

کلیدوضعیت در فایل پروژهمنبع نهایی
productهستفایل ترجمه‌ی پروژه
blog_categoryهستفایل ترجمه‌ی پروژه
generalحذف شدهفایل ترجمه‌ی زیرساخت
userحذف شدهفایل ترجمه‌ی زیرساخت
نکته

caseهای پایه‌ای که پس از انتشار در فایل کپی شده‌اند و قرار نیست متن‌شان در پروژه تغییر کند، می‌توانند از فایل حذف شوند تا از زیرساخت خوانده شوند. در غیر این صورت متن آن‌ها در پروژه ثابت می‌ماند و اصلاحات بعدی زیرساخت روی آن‌ها به پروژه نمی‌رسد.

نکته

اگر کلیدی ترجمه نشده باشد، کلید خام (مانند files::enum.file_type.product) نمایش داده می‌شود. این نشانه‌ی جاافتادن کلید در فایل ترجمه است.

رجیستری پسوندها​

برای تشخیص نوع پسوندها، زیرساخت یک رجیستری مرکزی دارد که همه‌ی پسوندها را در دسته‌های مشخص نگه می‌دارد.

این رجیستری برای این سناریوها استفاده می‌شود:

  • تشخیص نوع یک پسوند
  • گرفتن پسوندهای یک type خاص
  • تشخیص اینکه یک پسوند قابل preview هست یا نه
  • حذف لیست‌های پراکنده‌ی image و video از کدهای مختلف

FileManagement اکنون به‌صورت یک ماژول مستقل در Dornica\FileManagement نگه‌داری می‌شود.
config پیش‌فرض آن در packages/dornica/doravel/src/Dornica/FileManagement/config/dornica-file-management.php است و می‌توانید همان مقادیر را در config/dornica-app.php زیر کلید file_management override کنید.

برای تنظیمات پایه فایل‌های Doravel، بخش پیکربندی برنامه را هم ببینید.

کلاس مرکزی تشخیص پسوند​

برای کار با پسوندها از کلاس استاتیک زیر استفاده کنید:

use Dornica\Foundation\FileManager\FileExtensionRegistry;
FileExtensionRegistry::registry();             // کل map دسته‌ها و پسوندها
FileExtensionRegistry::types();                // لیست نام type ها
FileExtensionRegistry::typeForExtension('pdf'); // FileExtensionType::DOCUMENT
FileExtensionRegistry::extensionsForType('image'); // پسوندهای image
FileExtensionRegistry::isType('png', 'image');     // true
FileExtensionRegistry::isPreviewable('mp4');       // true
FileExtensionRegistry::images();                // shortcut برای image
FileExtensionRegistry::videos();                // shortcut برای video
FileExtensionRegistry::documents();             // shortcut برای document

typeهای پشتیبانی‌شده​

typeتوضیح
imageتصویرها و فرمت‌های گرافیکی
videoویدیوها
audioفایل‌های صوتی
documentسندها مثل PDF و Word
spreadsheetفایل‌های جدولی
presentationفایل‌های ارائه
archiveفایل‌های فشرده
codeفایل‌های کد و سورس
fontفونت‌ها
ebookکتاب‌های الکترونیکی
databaseفایل‌های دیتابیس
executableفایل‌های اجرایی
disk_imageایمیج دیسک
vectorفایل‌های برداری
emailفایل‌های ایمیل
certificateفایل‌های گواهی
configفایل‌های تنظیمات
3dفایل‌های سه‌بعدی
textفایل‌های متنی
otherموارد ناشناخته
نکته

pdf در این ساختار زیر document قرار می‌گیرد، نه media.

نکته​

اگر قبلاً از helperهای قدیمی برای تشخیص extension استفاده می‌کردید، آن‌ها حذف شده‌اند و باید به FileExtensionRegistry مهاجرت کنید.

تزریق داده‌های پیش‌فرض FileType​

در زیرساخت دراول یک seeder پیش‌فرض برای FileType وجود دارد که ردیف‌های پایه و موردنیاز سیستم را به‌صورت خودکار در دیتابیس ایجاد می‌کند.
این داده‌ها مستقیماً توسط زیرساخت استفاده می‌شوند و نیازی به تعریف دستی آن‌ها نیست.

برای اجرای این seeder، دستور زیر را اجرا کنید:

php artisan db:seed --class="Dornica\UserManagement\Seeders\UserManagementFileTypeSeeder"

با اجرای این دستور، تمام FileType های موردنیاز زیرساخت در دیتابیس ثبت می‌شوند و سیستم آماده استفاده خواهد بود.

جمع‌بندی مدل‌ها و فیلدها​

جدول زیر نقش و هدف هریک از مدل‌های FileManager را نشان میدهد:

مدلوظیفه و کاربرد
Fileثبت جزئیات هر فایل آپلود شده
FileDiskاطلاعات و کانفیگ سرورهای ذخیره‌سازی و دیسک‌ها
FileTypeتعیین نوع فایل، محدودیت‌ها، دسته‌بندی و قوانین آن
نکته

می‌توانید در پروژه‌ی خود مدل‌ها را توسعه دهید و مقادیر مورد نیاز خود را به هریک اضافه کنید؛ کافی‌ست در dornica-app.php مسیر مدل را تغییر دهید.

آپلود فایل​

آپلود فایل یکی از قابلیت‌های اصلی FileManager است که به شما اجازه می‌دهد به‌سادگی فایل‌های مورد نیاز پروژه خود را ذخیره و مدیریت کنید. این سیستم به شما این امکان را می‌دهد که فایل‌ها را در دیسک‌های مختلف (مانند local، S3 یا SFTP) براساس تنظیمات موردنظر خود آپلود کنید. با استفاده از متدهای انعطاف‌پذیر و زنجیره‌ای، می‌توانید ویژگی‌هایی مانند مسیر ذخیره‌سازی، نوع فایل، مدل مرتبط و کاربر آپلود کننده را به دلخواه تعیین نمایید. در ادامه، با روش‌ها و سناریوهای مختلف آپلود فایل در FileManager آشنا خواهید شد.

ساده‌ترین و سریع‌ترین روش آپلود فایل​

FileManager::upload($request->file('bank_logo'));

آپلود پیشرفته و سفارشی‌سازی شده​

use Dornica\Foundation\FileManager\FileManager;
use Dornica\Foundation\FileManager\Models\FileDisk;
use Dornica\Foundation\FileManager\Enums\FileDiskDriver;
use Dornica\Foundation\FileManager\Models\FileType;

FileManager::driver('database') // تعیین نوع درایور دیسک
    ->disk(
        FileDisk::query()
            ->where('driver', FileDiskDriver::S3)
            ->first()
    ) // انتخاب دیسک مورد نظر برای ذخیره‌سازی فایل
    ->path('bank/logos') // تعیین مسیر دلخواه برای ذخیره فایل
    ->module('Bank') // تعیین نام ماژول
    ->name('logo_' . time()) // انتخاب نام سفارشی برای فایل
    ->fileType(
        FileType::query()
            ->where('slug', 'bank_logo')
            ->first()
    ) // تعیین نوع فایل
    ->uploader(User::find(2)) // تعیین کاربر آپلودکننده فایل
    ->entity(Bank::find(126), 'logo_file_id') // ارتباط فایل با یک مدل
    ->asPrivate() // تعیین فایل به عنوان فایل خصوصی (دسترسی محدود)
    ->upload($request->file('bank_logo')); // آپلود و ذخیره فایل دریافتی از درخواست

آپلود فایل با لینک​

برای زمانی که فایل به صورت لینک در اختیار شماست (مثلاً در خروجی Import، فایل‌های ریموت یا داده‌هایی که از سرویس دیگری دریافت شده‌اند)، می‌توانید از متد uploadWithLink استفاده کنید. این متد لینک را دریافت می‌کند، فایل را به صورت موقت دانلود می‌کند و سپس همان فرآیند معمول upload را برای ذخیره فایل و ثبت اطلاعات آن در دیتابیس اجرا می‌کند.

آپلود فایل از روی لینک
$file = FileManager::diskDriver('local')
    ->path('bank/logos')
    ->module('Bank')
    ->name('logo_' . time())
    ->fileType('general')
    ->uploader(authenticator()->user())
    ->uploadWithLink($row['file']);
آپلود لوگو بانک از لینک مستقیم
$logo = FileManager::diskDriver('database')
    ->disk('uploads')
    ->path('bank/logos')
    ->module('Bank')
    ->name('bank_logo_' . now()->timestamp)
    ->fileType('general')
    ->entity($bank, 'logo_file_id')
    ->uploader(auth()->user())
    ->asPublic()
    ->uploadWithLink('https://example.com/files/bank-logo.png');
نکته

ورودی uploadWithLink باید یک URL معتبر باشد. در صورت دانلود نشدن فایل یا ناموفق بودن پاسخ لینک، خطای UploadFailedException پرتاب می‌شود. زمان انتظار دانلود نیز از تنظیمات dornica-app.file_manager.remote_fetch_timeout خوانده می‌شود.

متدهای زنجیره‌ای برای آپلود فایل​

برای آپلود می‌توانید از متدهای زنجیره‌ای (Fluent Methods) استفاده کنید که این امکان را برایتان فراهم می‌کند تا فرآیند آپلود فایل را به‌صورت کاملاً سفارشی و مدیریت‌شده انجام دهید. هر یک از این متدها بخش خاصی از عملیات آپلود را کنترل می‌کند و می‌توانید آن‌ها را بر اساس نیاز و به هر ترتیبی فراخوانی نمایید.

متدتوضیحمقدار/نوع ورودی
driverتعیین درایور دیسک برای جستجوی Disk موردنظرlocal یا database
diskتعیین دیسک مشخص جهت ذخیره‌سازی فایلنمونه مدل FileDisk یا نام دیسک
nameانتخاب نام سفارشی برای فایلنام فایل مورد نظر (String)
fileTypeثبت نوع فایلنمونه مدل FileType
entityمرتبط کردن فایل با یک مدل؛ پارامتر دوم (اختیاری) نام فیلدی است که شناسه فایل در آن ذخیره می‌شودپارامتر اول: مدل مربوطه (Eloquent Model)، پارامتر دوم (اختیاری): نام فیلد شناسه فایل
moduleثبت ماژول (مختص پروژه‌های ماژولار)نام ماژول
uploaderمشخص کردن کاربر آپلودکننده فایلمدل کاربر (User Model)
pathتعیین مسیر اضافی جهت ذخیره فایلرشته مسیر سفارشی (String)
asPrivateتعیین فایل به عنوان فایل خصوصی (دسترسی محدود)-
asPublicتعیین فایل به عنوان فایل عمومی (دسترسی آزاد)-
uploadبارگذاری (آپلود) فایل و ذخیره در سیستمUploadedFile (از Body درخواست)
uploadWithLinkدانلود فایل از لینک و ذخیره آن با همان فرآیند آپلودURL فایل (String)
نکته

هر متد را می‌توانید بر اساس نیاز خود استفاده کنید و همه متدها اجباری نیستند. به عنوان مثال اگر تنها مسیر آپلود برایتان اهمیت دارد، فقط کافیست path را مقداردهی کنید و سایر متدها را استفاده نکنید.

مدیریت سطح دسترسی فایل‌ها​

FileManager امکان کنترل سطح دسترسی فایل‌ها را از طریق دو متد asPrivate و asPublic فراهم می‌کند. این ویژگی به شما اجازه می‌دهد مشخص کنید فایل‌های آپلود شده به صورت خصوصی (دارای محدودیت) یا عمومی (دسترسی آزاد) ذخیره شوند.

asPrivate - فایل خصوصی​

این متد فایل را به صورت خصوصی تنظیم می‌کند. فایل‌های خصوصی:

  • با لینک‌های موقت (temporary URLs) قابل دسترسی هستند
  • مدت زمان دسترسی محدود دارند
  • برای فایل‌های محرمانه مانند مدارک شخصی، قراردادها و اسناد داخلی مناسب هستند

asPublic - فایل عمومی​

این متد فایل را به صورت عمومی تنظیم می‌کند. فایل‌های عمومی:

  • بدون نیاز به احراز هویت قابل دسترسی هستند
  • با لینک‌های مستقیم (direct URLs) سرو می‌شوند
  • برای فایل‌های عمومی مانند لوگو، تصاویر محصولات و فایل‌های دانلودی مناسب هستند

مثال‌های کاربردی​

آپلود فایل خصوصی
// آپلود قرارداد کاری به صورت خصوصی
FileManager::module('Contract')
    ->asPrivate()
    ->upload($request->file('contract_file'));
آپلود فایل عمومی
// آپلود لوگو شرکت به صورت عمومی
FileManager::module('Company')
    ->asPublic()
    ->upload($request->file('logo'));
استفاده در کنار سایر متدها
FileManager::entity($user)
    ->asPrivate() // تصویر پروفایل خصوصی باشد
    ->upload($request->file('avatar'));
تغییر وضعیت دسترسی بر اساس شرایط
$isPublicFile = $request->input('is_public', false);

$fileManager = FileManager::module('Document');

if ($isPublicFile) {
    $fileManager->asPublic();
} else {
    $fileManager->asPrivate();
}

$file = $fileManager->upload($request->file('document'));

نکات مهم​

مقدار پیش‌فرض​

اگر متد asPrivate یا asPublic فراخوانی نشود، وضعیت دسترسی از تنظیمات FileType مربوطه استفاده می‌کند.

اعتبارسنجی​

سیستم به صورت خودکار بررسی می‌کند که فایل‌های با FileType خصوصی نتوانند به صورت عمومی آپلود شوند. در صورت تلاش برای این کار، خطای InvalidPrivacyForFileType پرتاب می‌شود.

تاثیر بر URL​

  • فایل‌های خصوصی: لینک‌های موقت با تاریخ انقضا
  • فایل‌های عمومی: لینک‌های مستقیم و دائمی

ترتیب فراخوانی​

این متدها را می‌توان در هر جای زنجیره متدها قبل از upload فراخوانی کرد.

توجه

اگر FileType مربوطه به صورت خصوصی تنظیم شده باشد is_private = true، نمی‌توان فایل را به صورت عمومی آپلود کرد. این یک محدودیت امنیتی است.

درخواست و پردازش فایل​

برای مدیریت خودکار فایل‌ها در زمان ارسال و پردازش فرم (مانند آپلود، حذف یا جایگزینی فایل) پیشنهاد می‌شود از روش زیر استفاده کنید:

در این روش، کافی است مراحل ساده زیر را دنبال کنید تا عملیات مربوط به حذف، جایگزینی یا نگهداری فایل قبلی با حداقل کدنویسی و بدون پیچیدگی انجام شود:

  • اگر کاربر فایل جدیدی بارگذاری کند، فایل قبلی به طور خودکار حذف شده و فایل جدید جایگزین می‌شود.
  • اگر کاربر فایل را حذف کند (یعنی فیلد فایل خالی باشد یا درخواست حذف ارسال شود)، فایل قبلی پاک می‌گردد.
  • اگر هیچ تغییری اتفاق نیافتد، فایل قبلی بدون تغییر باقی می‌ماند و اقدامی انجام نمی‌شود.

این روش پیاده‌سازی ساده، تمام فرآیندهای مدیریت فایل را یکجا و به صورت سریع برای شما انجام می‌دهد.

نکته

با استفاده از این شیوه، دیگر نیازی به بررسی دستی وضعیت فایل قبلی و نوشتن کد اضافی ندارید؛ کافی است از این رویکرد بهره ببرید تا همه مراحل حذف، جایگزینی و آپلود جدید به‌طور خودکار انجام شود.

ساختار کلی​

نمونه کامل استفاده
FileManager::request('profile_picture')
    ->driver('s3') // تعیین نوع درایور دیسک
    ->disk(
        FileDisk::query()
            ->where('name', 'avatars_s3')
            ->first()
    ) // انتخاب دیسک مورد نظر برای ذخیره‌سازی فایل
    ->path('profiles/2024') // تعیین مسیر دلخواه برای ذخیره فایل
    ->module('User') // تعیین نام ماژول
    ->fileType(
        FileType::query()
            ->where('slug', 'profile_picture')
            ->first()
    ) // تعیین نوع فایل
    ->uploader(User::find(5)) // تعیین کاربر آپلودکننده فایل
    ->entity(User::find(5), 'profile_picture_file_id') // ارتباط فایل با یک مدل
    ->asPrivate() // تنظیم فایل به صورت خصوصی
    ->process();
مثال ساده آپلود فایل
$file = FileManager::request('file')->process();

متدهای اصلی FileManager​

متدورودی/مقدار مجازتوضیح
requestنام فیلد فایل در درخواست (file یا avatar یا ...)مشخص می‌کند کدام فیلد از فرم/درخواست باید بررسی و پردازش شود
diskDriverlocal یا database یا s3نوع درایور دیسک (مطابق مثال‌ها)؛ اگر مشخص نشود، مقدار پیش‌فرض سیستم استفاده می‌شود
diskنام دیسک (مثال: public یا uploads یا ...)انتخاب دیسک ذخیره‌سازی مورد نظر؛ بر اساس دیسک‌های تنظیم‌شده در سیستم
pathمسیر دلخواه برای ذخیره‌سازی فایل (مثلاً: profiles/2024)تعیین پوشه/مسیر خاص برای آپلود فایل
entityمدل مرتبط (مثل Object مدل User یا Post)اتصال فایل به یک موجودیت (مطابق مثال حتی می‌توان ستون فایل را مشخص کرد)
asPrivate-تنظیم فایل به صورت خصوصی (دسترسی محدود)
asPublic-تنظیم فایل به صورت عمومی (دسترسی آزاد)
process-عملیات نهایی پردازش شامل آپلود، حذف و جایگزینی بر اساس درخواست
نکته

این متدها مطابق نمونه کدهای بالا قابل استفاده و ترکیب هستند؛ می‌توانید تنها از متدهایی استفاده کنید که برای نیاز شما مناسب است.

مثال‌های کابردی و حرفه‌ای مدیریت فایل​

آپلود ساده فایل (مثال پایه ای - فرم پروفایل)
// فرض: کاربر عکسی را از طریق فرم خود ارسال می‌کند
$file = FileManager::request('profile_image')->process();
آپلود فایل در مسیر و دیسک سفارشی (مثال برای آپلود مدرک)
// فرض: ادمین می‌خواهد مدرک کاربر را ذخیره کند
$file = FileManager::request('document')
    ->diskDriver('s3')
    ->disk('documents_s3')
    ->path('users/'.$user->id.'/docs')
    ->asPrivate() // مدارک به صورت خصوصی ذخیره شوند
    ->process();
آپلود و اتصال مستقیم به مدل (مثال برای آپدیت عکس کاربر موجود)
$user = User::findOrFail(23);

$file = FileManager::request('avatar')
    ->diskDriver('database')
    ->disk('avatars')
    ->entity($user, 'avatar_file_id') // اتصال به ستون دلخواه فایل
    ->asPrivate() // تصاویر پروفایل خصوصی باشند
    ->process();
افزودن نوع فایل و آپلودر جهت مدیریت پیشرفته‌تر (کامل‌ترین حالت)
$file = FileManager::request('contract')
    ->diskDriver('local')
    ->disk('contracts')
    ->path('company/contracts')
    ->fileType(
        FileType::query()
            ->where('type', FileType::USER_CONTRACT)
            ->first()
    )
    ->uploader(auth()->user())
    ->entity($company, 'contract_file_id')
    ->asPrivate() // قراردادها خصوصی باشند
    ->process();
استفاده در Controller با مدیریت خطا و بازخورد کاربر
public function uploadProfile(Request $request)
{
    try {
        $user = $request->user();

        $file = FileManager::request('profile')
            ->disk('profiles')
            ->entity($user, 'profile_picture_file_id')
            ->asPrivate()
            ->process();

        return Response::success(
            message: 'تصویر پروفایل باموفقیت ذخیره شد',
            data: [
                'file_id' => $file->id,
                'file_url' => $file->url,
            ]
        );
    } catch (Exception $e) {
        return Response::error(
            code: SystemMessage::FAIL,
            message: 'خطایی رخ داده است'
        );
    }
}
نکات کاربردی و حرفه‌ای
  • می‌توانید با استفاد‌ه از متد path، فولدرهای پویا متناسب با هر کاربر یا ماژول بسازید (مثلاً users/{$user->id}).
  • فیلد entity هم اتصال ساده (فقط مدل) و هم اتصال به یک ستون خاص فایل (مثلاً avatar_file_id) را می‌پذیرد.
  • متد fileType برای تعیین دسته‌بندی یا نوع فایل (امنیت، سطح دسترسی و ...) بسیار مفید است.
  • متد uploader را برای ذخیره اطلاعات کاربر بارگذارنده (جهت لاگ، سطح دسترسی، شفافیت و...) فراموش نکنید.
  • متدهای asPrivate و asPublic برای کنترل سطح دسترسی فایل‌ها حیاتی هستند.
  • اگر هیچکدام از متدهای diskDriver یا disk را مشخص نکنید، FileManager از مقادیر پیش فرض سیستم بهره می‌گیرد.
  • فراخوانی فقط متد process لازم است؛ اگر نیازی به بقیه گزینه‌ها ندارید، ساده‌ترین حالت را استفاده کنید!

متدهای دریافت و مدیریت فایل​

get دریافت فایل​

متد get برای دریافت فایل‌های موجود در storage استفاده می‌شود.

ورودی​

  • می‌تواند id فایل در جدول files باشد
  • می‌تواند object خروجی مدل File تعریف شده در کانفیگ
  • به صورت تکی یا آرایه‌ای از موارد گفته شده

خروجی​

  • یک یا چند File DTO
اطلاع

به صورت خودکار disk و storage را پیدا می‌کند و اقدام به یافتن فایل می‌کند.

هشدار

در صورت عدم وجود فایل خطای FileNotFoundException می‌دهد.

مثال‌ها​

دریافت فایل تکی - با ID
$file = FileManager::get(172); // by id
دریافت فایل تکی - با Model Instance
$file = FileManager::get(
    File::find(172)
); // by model instance
دریافت فایل‌های گروهی - با IDs
$files = FileManager::get([141, 122, 172]); // by ids
دریافت فایل‌های گروهی - با Model Instances
$files = FileManager::get([
    File::find(141),
    File::find(172)
]); // by model instances
دریافت فایل‌های گروهی - با Model Instances از کوئری
$files = FileManager::get(
    File::query()
        ->whereIn('id', [141, 172])
        ->get()
); // by model instances from query

delete حذف فایل​

متد delete فایل موجود در storage را هم از storage و هم از database حذف می‌کند.

ورودی​

  • مشابه متد get (id یا model instance، تکی یا آرایه‌ای)

خروجی​

  • خروجی این متد در هر صورت void است
اطلاع

به ازای هر فایل ورودی تراکنش دیتابیس اتفاق می‌افتد.

مثال‌ها​

حذف فایل تکی - با ID
FileManager::delete(155); // by id
حذف فایل تکی - با Model Instance
FileManager::delete(
    File::find(279)
); // by model instance
حذف فایل‌های گروهی
FileManager::delete([155, 156, 157]); // by ids

softDelete حذف موقت فایل​

متد softDelete فایل را به سطل زباله می‌برد: رکورد دیتابیس علامت حذف می‌خورد اما هم رکورد و هم فایل روی دیسک سر جای خود می‌مانند. بنابراین هر چیزی که هنوز به فایل اشاره می‌کند نمی‌شکند و بعداً می‌توان با restore فایل را برگرداند.

توجه

دقت کنید که delete فایل را برای همیشه حذف می‌کند — برخلاف معنای delete روی مدل‌های Eloquent. هر جا احتمال می‌دهید فایل هنوز ارجاعی دارد (مثلاً صاحب آن soft delete شده)، از softDelete استفاده کنید.

ورودی​

  • مشابه متد delete (id یا model instance، تکی، آرایه‌ای یا Collection)

خروجی​

  • خروجی این متد در هر صورت void است
اطلاع

فراخوانی دوباره روی فایلی که از قبل حذف موقت شده بی‌اثر است و خطا نمی‌دهد.

مثال‌ها​

حذف موقت فایل تکی - با ID
FileManager::softDelete(155); // by id
حذف موقت فایل تکی - با Model Instance
FileManager::softDelete(
    File::find(279)
); // by model instance
حذف موقت فایل‌های گروهی
FileManager::softDelete([155, 156, 157]); // by ids

FileManager::softDelete(
    File::whereIn('id', [155, 156, 157])->get()
); // by collection

restore بازگردانی فایل​

متد restore فایل‌هایی را که با softDelete به سطل زباله رفته‌اند برمی‌گرداند.

ورودی​

  • مشابه متد softDelete (id یا model instance، تکی، آرایه‌ای یا Collection)

خروجی​

  • خروجی این متد در هر صورت void است
اطلاع

این متد فایل‌های حذف موقت شده را با عبور از global scope پیدا می‌کند، بنابراین نیازی به withTrashed در سمت شما نیست.

مثال‌ها​

بازگردانی فایل تکی - با ID
FileManager::restore(155); // by id
بازگردانی فایل‌های گروهی
FileManager::restore([155, 156, 157]); // by ids
توجه

برای اینکه این دو متد درست کار کنند، اگر جدول files به‌جای ستون deleted_by از رابطه‌ی چندریختی deletable_id و deletable_type استفاده می‌کند، باید جدول را در تنظیمات dornica-app زیر کلید user_activity_polymorphic ثبت کنید:

config/dornica-app.php
'user_activity_polymorphic' => [
    'tables' => [
        'files' => ['deleted_by'],
    ],
],

در غیر این صورت هنگام حذف موقت یا بازگردانی با خطای Unknown column 'deleted_by' مواجه می‌شوید.

url دریافت لینک فایل​

متد url برای دریافت لینک فایل استفاده می‌شود.

ورودی​

  • مشابه متدهای get و delete

خروجی​

  • در صورت وجود فایل به صورت sftp، لینک فایل به sftp
  • در صورت local بودن، لینک مربوط به local در خروجی می‌آید
  • در صورت S3 بودن، لینک مربوط به S3 در خروجی می‌آید
  • در صورت تکی بودن، یک لینک باز می‌گرداند
  • در صورت گروهی بودن، آرایه‌ای از لینک‌ها باز می‌گرداند
هشدار

در صورت یافت نشدن FileNotFoundException می‌دهد.

مثال‌ها​

دریافت لینک تکی - با ID
$url = FileManager::url(198); // by id
// خروجی: http://127.0.0.1:8000/admin/file/eyJpdiI6...
دریافت لینک تکی - با Model Instance
$url = FileManager::url(
    File::find(721)
); // by instance
دریافت لینک‌های گروهی - با IDs
$urls = FileManager::url([198, 193]); // by ids
دریافت لینک‌های گروهی - با Model Instances
$urls = FileManager::url([
    File::find(821),
    File::find(146)
]); // by instances

exists بررسی وجود فایل​

متد exists وجود داشتن فایل بر روی storage مربوطه را به صورت boolean مشخص می‌کند.

ورودی​

  • مشابه متدهای get، delete و url

خروجی​

  • true در صورت وجود فایل
  • false در صورت عدم وجود فایل

مثال‌ها​

بررسی وجود فایل تکی - با ID
$exists = FileManager::exists(1000000); // by id
// result => false
بررسی وجود فایل تکی - با Model Instance
$exists = FileManager::exists(
    File::find(327)
); // by instance
// result => true
بررسی وجود فایل‌های گروهی - با IDs
$results = FileManager::exists([1000000, 211, 180, 124]); // by ids
// خروجی: array:4 [
//     180 => true,
//     1000000 => false,
//     211 => false,
//     124 => false,
// ]
بررسی وجود فایل‌های گروهی - با Model Instances
$results = FileManager::exists([
    File::find(614),
    File::find(431)
]); // by instances
نکته مهم

توجه شود که در متدهای get و delete و exists و url قابلیت تعریف disk قبل از آن‌ها وجود ندارد، به این دلیل که این متدها به صورت اتوماتیک disk مورد نظر فایل را پیدا می‌کنند.

اعتبارسنجی فایل‌ها​

برای اعتبارسنجی فایل‌ها قبل از آپلود، از متد validation ترجیها در FormRequest استفاده کنید:

ساختار کلی​

$fileRules = FileManager::validation()
    ->key('file')
    ->required()
    ->rules([
        "file",
        "mimes:xlsx,png,jpeg,jpg,svg,mp4,webp",
        "max:2048",
    ])
    ->make();

در خروجی یک آرایه قوانین اعتبارسنجی Laravel دریافت می‌کنید که می‌توانید در متد rules فرم ریکوئست خود استفاده کنید.

نکته

اگر در FormRequest خود علاوه بر فایل قوانین اعتبارسنجی دیگری نیز دارید، باید قوانین فایل و دیگر قوانین خود را با هم ادغام کنید.

پارامترها​

متدنوعتوضیح
validation-شروع ساخت قوانین اعتبارسنجی
keystringنام فیلد فایل در درخواست
required-اجباری بودن فایل
rulesarrayآرایه قوانین اعتبارسنجی Laravel
make-ساخت و بازگرداندن قوانین اعتبارسنجی

مثال‌های کاربردی​

اعتبارسنجی ساده
use Dornica\Foundation\FileManager\FileManager;

$fileRules = FileManager::validation()
    ->key('file')
    ->required()
    ->rules([
        "file",
        "mimes:xlsx,png,jpeg,jpg,svg,mp4,webp",
    ])
    ->make();
اعتبارسنجی با محدودیت حجم
use Dornica\Foundation\FileManager\FileManager;
use Dornica\Foundation\FileManager\Rules\FileSizeCheck;

$fileRules = FileManager::validation()
    ->key('file')
    ->required()
    ->rules([
        "file",
        "mimes:xlsx,png,jpeg,jpg,svg,mp4,webp",
        "max:2048", // حداکثر حجم 2 مگابایت
    ])
    ->make();
استفاده در FormRequest
use Illuminate\Foundation\Http\FormRequest;
use Dornica\Foundation\FileManager\FileManager;

class UploadFileRequest extends FormRequest
{
    public function rules()
    {
        return [
            ...FileManager::validation()
                ->key('file')
                ->required()
                ->rules([
                    "file",
                    "mimes:xlsx,png,jpeg,jpg,svg,mp4,webp",
                ])
                ->make(),
        ];
    }
}
اعتبارسنجی اختیاری
$fileRules = FileManager::validation()
    ->key('file')
    ->rules([
        "file",
        "mimes:pdf,doc,docx",
    ])
    ->make();
اعتبارسنجی با الزامی بودن Dynamic
$fileRules = FileManager::validation()

    // metod 1
    ->required(function () {
        return 1 == 1;
    })
    
    // metod 2
    ->required(false)
    
    ->key('file')
    ->rules([
        "file",
        "mimes:pdf,doc,docx",
    ])
    ->make();
قوانین اعتبارسنجی

می‌توانید از تمام قوانین اعتبارسنجی Laravel استفاده کنید:

  • file بررسی اینکه فایل معتبر است
  • mimes بررسی پسوند فایل
  • max حداکثر حجم فایل (کیلوبایت)
  • min حداقل حجم فایل (کیلوبایت)
  • dimensions ابعاد تصویر (برای تصاویر)

نکات و بهترین روش‌ها​

استفاده از Entity

استفاده از متد entity برای اتصال فایل‌ها به موجودیت‌ها توصیه می‌شود. این کار به شما کمک می‌کند:

  • مدیریت بهتر فایل‌ها
  • حذف خودکار فایل‌های مرتبط هنگام حذف موجودیت
  • دسترسی بهتر به فایل‌های مرتبط با یک موجودیت
محدودیت حجم فایل
  • حداکثر حجم فایل را در تنظیمات file_manager.max_file_size تعیین کنید.
  • همچنین می‌توانید از FileSizeCheck برای اعتبارسنجی حجم فایل استفاده کنید.
درایورهای پشتیبانی شده

FileManager از درایورهای زیر پشتیبانی می‌کند:

  • local: ذخیره‌سازی محلی
  • database: ذخیره‌سازی با اطلاعات در دیتابیس
  • s3: Amazon S3
  • sftp: SFTP

مثال‌های پیشرفته​

آپلود چند فایل
public function uploadMultipleFiles(Request $request)
{
    $files = FileManager::request('files')
        ->diskDriver('database')
        ->disk('uploads')
        ->entity($request->user())
        ->asPrivate() // همه فایل‌ها خصوصی باشند
        ->process();
}
آپلود با اعتبارسنجی سفارشی
public function uploadWithCustomValidation(Request $request)
{
    $request->validate([
        ...FileManager::validation()
            ->key('avatar')
            ->required()
            ->rules([
                "file",
                "mimes:jpeg,jpg,png",
                "max:1024",
                "dimensions:min_width=100,min_height=100"
            ])
            ->make(),
    ]);
    
    $avatar = FileManager::request('avatar')
        ->entity($request->user(), 'avatar_id')
        ->asPrivate() // تصویر پروفایل خصوصی باشد
        ->process();
}

جمع‌بندی​

متدهای اصلی​

متدتوضیح
requestدرخواست و پردازش فایل
validationساخت قوانین اعتبارسنجی فایل
getدریافت فایل‌های موجود در storage
deleteحذف فایل از storage و database (جدول files)
softDeleteانتقال فایل به سطل زباله بدون حذف رکورد و فایل
restoreبازگردانی فایل حذف موقت شده
urlدریافت لینک فایل
existsبررسی وجود فایل در storage و database
asPrivateتنظیم فایل به صورت خصوصی (دسترسی محدود)
asPublicتنظیم فایل به صورت عمومی (دسترسی آزاد)

درایورها​

درایورتوضیح
DATABASEخواندن اطلاعات disk از جدول file_disks
LOCALخواندن اطلاعات disk از filesystems.php

دیسک‌ درایورها​

نوعتوضیح
LOCALذخیره‌سازی محلی
SFTPذخیره‌سازی از طریق SFTP
S3ذخیره‌سازی در Amazon S3

انواع احراز هویت (auth_type)​

مقدارنوعفیلدهای مورد استفاده
0No authبدون احراز هویت
1Basicusername و password
2SSH key basedprivate_key و passphrase

منابع مرتبط​