رفع الملفات وإدارتها في تطبيقات Laravel: دليل شامل ومفصل

يُعدّ رفع الملفات (File Uploading) وإدارتها من المهام الجوهرية في العديد من تطبيقات الويب، سواء أكانت مدونات، أنظمة إدارة محتوى، منصات تعليمية، أو متاجر إلكترونية. في إطار Laravel، الذي يُعدّ من أكثر أطر العمل PHP شيوعًا وموثوقية، تم توفير أدوات متقدمة ومبسطة تجعل من عملية رفع الملفات وتخزينها وإدارتها أمراً سهلاً وآمناً وفعّالاً. يوفر Laravel مجموعة من الوظائف المتكاملة التي تُعنى بمعالجة الملفات، من التحقق من نوع الملفات وحجمها، إلى التحكم في أماكن تخزينها، مروراً بتسميتها، وصولاً إلى حذفها وإدارتها عبر الواجهات الأمامية والخلفية.

أولاً: البنية التحتية لتخزين الملفات في Laravel

1. نظام الملفات (Filesystem)

Laravel يعتمد على مكتبة خارجية تُسمى Flysystem، التي توفر واجهة موحدة للتعامل مع أنظمة ملفات متعددة مثل:

• التخزين المحلي (Local Disk)

• التخزين السحابي مثل Amazon S3، Google Cloud Storage، وAzure

• بروتوكولات FTP وSFTP

تمكّنك هذه البنية من كتابة كود واحد يستخدم نفس API بغض النظر عن نوع التخزين.

2. ملفات الإعداد: config/filesystems.php

الملف الرئيسي الذي يحدد إعدادات أنظمة الملفات في Laravel. يحتوي على تعريف للأقراص (disks) مثل:

php
CopyEdit
'disks' => [

    'local' => [
        'driver' => 'local',
        'root' => storage_path('app'),
    ],

    'public' => [
        'driver' => 'local',
        'root' => storage_path('app/public'),
        'url' => env('APP_URL').'/storage',
        'visibility' => 'public',
    ],

    's3' => [
        'driver' => 's3',
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'region' => env('AWS_DEFAULT_REGION'),
        'bucket' => env('AWS_BUCKET'),
    ],

],

ثانياً: رفع الملفات من الواجهة الأمامية

1. إعداد النموذج (Form)

يجب إعداد النموذج ليستعمل enctype="multipart/form-data" ليسمح بإرسال ملفات.

html
CopyEdit
<form action="{{ route('upload') }}" method="POST" enctype="multipart/form-data">
    @csrf
    <input type="file" name="file">
    <button type="submit">رفع الملفbutton>
form>

2. إعداد المسار والكنترولر

ملف Routes/web.php

php
CopyEdit
Route::post('/upload', [FileUploadController::class, 'store'])->name('upload');

كنترولر FileUploadController

php
CopyEdit
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Storage;

class FileUploadController extends Controller
{
    public function store(Request $request)
    {
        $validated = $request->validate([
            'file' => 'required|file|max:2048|mimes:jpg,jpeg,png,pdf,docx',
        ]);

        $path = $request->file('file')->store('uploads', 'public');

        return response()->json(['path' => $path], 200);
    }
}

3. إعدادات صلاحية التخزين العام

يجب تنفيذ الأمر التالي لتفعيل صلاحية الوصول لملفات storage/app/public من الويب:

bash
CopyEdit
php artisan storage:link

ثالثاً: تسمية الملفات ومنع التكرار

Laravel يحفظ الملفات بأسماء مشفرة بشكل افتراضي لتجنب التكرار، ولكن يمكن تحديد اسم مخصص:

php
CopyEdit
$file = $request->file('file');
$filename = time().'_'.$file->getClientOriginalName();
$path = $file->storeAs('uploads', $filename, 'public');

رابعاً: حذف الملفات

لحذف ملف من التخزين العام أو أي قرص معرف:

php
CopyEdit
Storage::disk('public')->delete('uploads/example.jpg');

خامساً: عرض الملفات على المتصفح

لعرض صورة أو تحميل مستند:

php
CopyEdit
$url = Storage::disk('public')->url('uploads/example.jpg');

أو لعرضه مباشرة:

html
CopyEdit
<img src="{{ asset('storage/uploads/example.jpg') }}" alt="Uploaded File">

سادساً: إدارة الملفات باستخدام Storage Facade

سابعاً: حفظ البيانات في قاعدة البيانات مع الملف

يُعدّ من الممارسات الشائعة ربط الملف بسجل في قاعدة البيانات، كحفظ المسار واسم الملف وتاريخ الرفع:

php
CopyEdit
$file = $request->file('file');
$filename = time().'_'.$file->getClientOriginalName();
$path = $file->storeAs('documents', $filename, 'public');

Document::create([
    'user_id' => auth()->id(),
    'filename' => $filename,
    'path' => $path,
]);

ثامناً: رفع عدة ملفات دفعة واحدة

1. تعديل النموذج:

html
CopyEdit
<input type="file" name="files[]" multiple>

2. تعديل الكنترولر:

php
CopyEdit
foreach ($request->file('files') as $file) {
    $filename = time().'_'.$file->getClientOriginalName();
    $file->storeAs('multi', $filename, 'public');
}

تاسعاً: حماية الملفات والحد من الوصول

الملفات المرفوعة عبر قرص public يمكن الوصول إليها من أي شخص لديه الرابط. لضمان الحماية، يجب استخدام قرص private، ثم إنشاء روابط مؤقتة عند الطلب.

مثال على ذلك:

php
CopyEdit
$response = Storage::disk('local')->download('private/file.pdf');

أو لإنشاء رابط مؤقت مع Amazon S3:

php
CopyEdit
$url = Storage::disk('s3')->temporaryUrl(
    'file.pdf', now()->addMinutes(10)
);

عاشراً: التعامل مع رفع الملفات باستخدام Livewire

إذا كنت تستخدم Livewire، فإن رفع الملفات يصبح أكثر سلاسة:

php
CopyEdit
use Livewire\Component;
use Livewire\WithFileUploads;

class UploadComponent extends Component
{
    use WithFileUploads;

    public $file;

    public function save()
    {
        $this->validate([
            'file' => 'required|mimes:jpg,png,pdf|max:2048',
        ]);

        $this->file->store('livewire-files', 'public');
    }

    public function render()
    {
        return view('livewire.upload-component');
    }
}

حادي عشر: الجدول المقارن لأوضاع التخزين

ثاني عشر: استخدام التخزين في المهام المجدولة أو الأحداث

بفضل تكامل Laravel مع الأحداث (Events) والمهام المجدولة (Scheduled Tasks)، يمكن تحميل أو حذف الملفات تلقائيًا وفق شروط معينة، مثل:

• حذف الملفات القديمة كل أسبوع

• ضغط الصور بعد رفعها

• إرسال إشعار عند رفع ملف معين

مثال على حذف الملفات الأقدم من أسبوع:

php
CopyEdit
$files = Storage::files('uploads');

foreach ($files as $file) {
    if (Storage::lastModified($file) < now()->subWeek()->timestamp) {
        Storage::delete($file);
    }
}

ثالث عشر: إدارة الملفات في لوحة الإدارة

يمكن ربط واجهة المستخدم بـ Vue.js أو Blade أو Livewire لعرض الملفات المخزنة، مع خيارات حذف وتحميل. كما يمكن تفعيل خاصية preview للصور والمستندات وعرض جدول يحتوي على المعلومات التالية:

المراجع

• Laravel Documentation: https://laravel.com/docs/filesystem

• Flysystem Library: https://flysystem.thephpleague.com/