الفرق بين المراجعتين ل"Laravel/filesystem"

من موسوعة حسوب
اذهب إلى التنقل اذهب إلى البحث
 
(12 مراجعة متوسطة بواسطة نفس المستخدم غير معروضة)
سطر 1: سطر 1:
<noinclude>{{DISPLAYTITLE:تخزين الملفات في Laravel}}</noinclude>
+
<noinclude>{{DISPLAYTITLE:تخزين الملفات (File storage) في Laravel}}</noinclude>
[[تصنيف:Laravel]]
+
[[تصنيف:Laravel|{{SUBPAGENAME}}]]
[[تصنيف:Laravel Digging deeper]]
+
[[تصنيف:Laravel Digging deeper|{{SUBPAGENAME}}]]
= مقدمة =
+
== مقدمة ==
 
يوفّر [[Laravel]] تجريدًا قويًا لنظام الملفات بفضل الحزمة Flysystem. يوفّر تضمين أنظمة الملفات في [[Laravel]] مشغّلات سهلة الاستعمال للتعامل مع الأنظمة المحلية و Amazon S3 والتخزين السحابي Rackspace، بل من السهل جدًا تغيير خيارات التخزين إذ تبقى وصلة API نفسها مع كل الأنظمة.
 
يوفّر [[Laravel]] تجريدًا قويًا لنظام الملفات بفضل الحزمة Flysystem. يوفّر تضمين أنظمة الملفات في [[Laravel]] مشغّلات سهلة الاستعمال للتعامل مع الأنظمة المحلية و Amazon S3 والتخزين السحابي Rackspace، بل من السهل جدًا تغيير خيارات التخزين إذ تبقى وصلة API نفسها مع كل الأنظمة.
  
= الضبط =
+
== الضبط ==
 
يوجد ملف ضبط نظام الملفات في <code>config/filesystems.php</code>. يمكنك في هذا الملف ضبط كل الأقراص "disks". يمثّل كل قرص مشغّل تخزين ومكان تخزين خاص. يحتوي الملف على أمثلة ضبط لكل مشغّل مدعوم. لذا غيّر الملف حسب خياراتك ومعلوماتك الخاصة.
 
يوجد ملف ضبط نظام الملفات في <code>config/filesystems.php</code>. يمكنك في هذا الملف ضبط كل الأقراص "disks". يمثّل كل قرص مشغّل تخزين ومكان تخزين خاص. يحتوي الملف على أمثلة ضبط لكل مشغّل مدعوم. لذا غيّر الملف حسب خياراتك ومعلوماتك الخاصة.
  
 
طبعًا، يمكنك ضبط أي عدد من الأقراص تريد أو حتى أقراص عديدة تستعمل نفس المشغّل.
 
طبعًا، يمكنك ضبط أي عدد من الأقراص تريد أو حتى أقراص عديدة تستعمل نفس المشغّل.
  
== القرص الصلب العام ==
+
=== القرص الصلب العام ===
 
القرص العام public مُعدٌّ للملفات التي سيكون ولوجها عامًّا. في العادة، يستخدم القرص public المشغل local ويُخزِّن الملفات في <code>storage/app/public</code>. لإتاحة إمكانية ولوجهم من الويب، يجب إنشاء وصلة رمزية من <code>public/storage</code> إلى <code>storage/app/public</code>. تُبقي هذه الطريقة كل الملفات العمومية في مكان واحد يمكن مشاركته بسهولة عند استعمال تقنية نشر دون وقت إيقاف مثل Envoyer.
 
القرص العام public مُعدٌّ للملفات التي سيكون ولوجها عامًّا. في العادة، يستخدم القرص public المشغل local ويُخزِّن الملفات في <code>storage/app/public</code>. لإتاحة إمكانية ولوجهم من الويب، يجب إنشاء وصلة رمزية من <code>public/storage</code> إلى <code>storage/app/public</code>. تُبقي هذه الطريقة كل الملفات العمومية في مكان واحد يمكن مشاركته بسهولة عند استعمال تقنية نشر دون وقت إيقاف مثل Envoyer.
  
سطر 19: سطر 19:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== برنامج التشغيل المحلي ==
+
=== برنامج التشغيل المحلي ===
 
عند استخدام المشغّل المحلي local، كل الأعمال على الملفات موجودة في المجلد الجذر (root) المعرّف في ملف الضبط. في العادة، قيمته هي المجلد <code>storage/app</code>. لذا، الأمر الآتي سيُسجّل ملفًا في <code>storage/app/file.txt</code>:<syntaxhighlight lang="php">
 
عند استخدام المشغّل المحلي local، كل الأعمال على الملفات موجودة في المجلد الجذر (root) المعرّف في ملف الضبط. في العادة، قيمته هي المجلد <code>storage/app</code>. لذا، الأمر الآتي سيُسجّل ملفًا في <code>storage/app/file.txt</code>:<syntaxhighlight lang="php">
 
Storage::disk('local')->put('file.txt', 'Contents');
 
Storage::disk('local')->put('file.txt', 'Contents');
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== متطلبات برنامج التشغيل ==
+
=== متطلبات برنامج التشغيل ===
  
=== حزم Composer ===
+
==== حزم Composer ====
 
قبل استخدام مشغّلات S3 أو SFTP أو Rackspace، ستحتاج أولا لتثبيت الحزم الملائمة عبر Composer:
 
قبل استخدام مشغّلات S3 أو SFTP أو Rackspace، ستحتاج أولا لتثبيت الحزم الملائمة عبر Composer:
 
* league/flysystem-sftp ~1.0 :SFTP
 
* league/flysystem-sftp ~1.0 :SFTP
سطر 34: سطر 34:
 
* league/flysystem-cached-adapter ~1.0 : CachedAdapter
 
* league/flysystem-cached-adapter ~1.0 : CachedAdapter
  
=== ضبط مشغّل S3 ===
+
==== ضبط مشغّل S3 ====
 
توجد معلومات ضبط المشغّل S3 في الملف <code>config/filesystems.php</code>. يحتوي هذا الملف على مثال لمصفوفة ضبط لمشغل S3. لك حرية تغيير هذه المصفوفة بضبتك ومعلوماتك الخاصة. للتسهيل، يستعمل متغيرات البيئة أسماء مطابقة لطريقة التسمية  المتبعة في واجهة سطر الأوامر لخدمات AWS.
 
توجد معلومات ضبط المشغّل S3 في الملف <code>config/filesystems.php</code>. يحتوي هذا الملف على مثال لمصفوفة ضبط لمشغل S3. لك حرية تغيير هذه المصفوفة بضبتك ومعلوماتك الخاصة. للتسهيل، يستعمل متغيرات البيئة أسماء مطابقة لطريقة التسمية  المتبعة في واجهة سطر الأوامر لخدمات AWS.
  
=== ضبط مشغّل FTP ===
+
==== ضبط مشغّل FTP ====
 
يعمل مضمِّن نظام الملفات جيدًا مع FTP. لكن الملف <code>filesystems.php</code> لا يتضمن مثالًا عن الضبط. إن احتجت لضبط FTP يمكنك استعمال المثال التالي:<syntaxhighlight lang="php">
 
يعمل مضمِّن نظام الملفات جيدًا مع FTP. لكن الملف <code>filesystems.php</code> لا يتضمن مثالًا عن الضبط. إن احتجت لضبط FTP يمكنك استعمال المثال التالي:<syntaxhighlight lang="php">
 
'ftp' => [
 
'ftp' => [
سطر 59: سطر 59:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
=== ضبط مشغّل SFTP ===
+
==== ضبط مشغّل SFTP ====
 
يعمل مضمِّن نظام الملفات جيدًا مع SFTP. لكن الملف <code>filesystems.php</code> لا يتضمن مثالًا عن الضبط. إن احتجت لضبط FTP يمكنك استعمال المثال التالي:<syntaxhighlight lang="php">
 
يعمل مضمِّن نظام الملفات جيدًا مع SFTP. لكن الملف <code>filesystems.php</code> لا يتضمن مثالًا عن الضبط. إن احتجت لضبط FTP يمكنك استعمال المثال التالي:<syntaxhighlight lang="php">
 
'sftp' => [
 
'sftp' => [
سطر 81: سطر 81:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
=== ضبط مشغّل Rackspace ===
+
==== ضبط مشغّل Rackspace ====
 
يعمل مضمِّن نظام الملفات جيدًا مع Rackspace. لكن الملف <code>filesystems.php</code> لا يتضمن مثالًا عن الضبط. إن احتجت لضبط FTP يمكنك استعمال المثال التالي:<syntaxhighlight lang="php">
 
يعمل مضمِّن نظام الملفات جيدًا مع Rackspace. لكن الملف <code>filesystems.php</code> لا يتضمن مثالًا عن الضبط. إن احتجت لضبط FTP يمكنك استعمال المثال التالي:<syntaxhighlight lang="php">
 
'rackspace' => [
 
'rackspace' => [
سطر 98: سطر 98:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== التخزين المؤقت ==
+
=== التخزين المؤقت ===
لتمكين قرص ما من استخدام التخزين المؤقت، تضاف التعليمة cache لخيارات ضبط القرص. يجب أن يكون الخيار cache مصفوفة من خيارات التخزين تحتوي الاسم disk وتاريخ انتهاء الصلاحية expire إضافة إلى سابقة prefix:
+
لتمكين قرص ما من استخدام التخزين المؤقت، تضاف التعليمة cache لخيارات ضبط القرص. يجب أن يكون الخيار <code>cache</code> مصفوفة من خيارات التخزين تحتوي الاسم <code>disk</code><syntaxhighlight lang="php">
 
 
 
's3' => [
 
's3' => [
  
 
   'driver' => 's3',
 
   'driver' => 's3',
 
 
  // خيارات أخرى
 
  // خيارات أخرى
  
سطر 110: سطر 108:
  
 
       'store' => 'memcached',
 
       'store' => 'memcached',
 
 
       'expire' => 600,
 
       'expire' => 600,
 
 
       'prefix' => 'cache-prefix',
 
       'prefix' => 'cache-prefix',
  
 
   ],
 
   ],
 +
],
  
],
 
  
= الحصول على نسخة من كائن القرص =
+
</syntaxhighlight>وتاريخ انتهاء الصلاحية <code>expire</code> إضافة إلى سابقة <code>prefix</code>:
تُستعمل الواجهة الساكنة Storage للتفاعل مع عدّة أقراص مضبوطة. مثلًا، يٌستعمل التابع put من الواجهة لتخزين نسخة avatar في القرص الرئيسي. إذا ناديت التابع put على الواجهة الثابتة Storage دون أن تنادي call أولا،تُستدعى الدالة call تلقائيًا للقرص الرئيسي.
 
  
 +
== الحصول على نسخة من كائن القرص ==
 +
تُستعمل الواجهة الساكنة <code>Storage</code> للتفاعل مع عدّة أقراص مضبوطة. مثلًا، يٌستعمل التابع <code>put</code> من الواجهة لتخزين نسخة <code>avatar</code> في القرص الرئيسي. إذا ناديت التابع <code>put</code> على الواجهة الثابتة <code>Storage</code> دون أن تنادي <code>call</code> أولا،تُستدعى الدالة <code>call</code> تلقائيًا للقرص الرئيسي:<syntaxhighlight lang="php">
 
use Illuminate\Support\Facades\Storage;
 
use Illuminate\Support\Facades\Storage;
 
 
Storage::put('avatars/1', $fileContents);
 
Storage::put('avatars/1', $fileContents);
  
إذا كان التطبيق يتعامل مع أكثر من قرص، يمكن استعمال التابع disk من الواجهة الثابتة Storage للعمل على ملفات في قرص معيّن:
 
  
 +
</syntaxhighlight>إذا كان التطبيق يتعامل مع أكثر من قرص، يمكن استعمال التابع <code>disk</code> من الواجهة الثابتة <code>Storage</code><syntaxhighlight lang="php">
 +
Storage::disk('s3')->put('avatars/1', $fileContents);
 +
</syntaxhighlight>للعمل على ملفات في قرص معيّن:<syntaxhighlight lang="php">
 
Storage::disk('s3')->put('avatars/1', $fileContents);
 
Storage::disk('s3')->put('avatars/1', $fileContents);
 +
</syntaxhighlight>
  
= الحصول على الملفات =
+
== استرداد الملفات ==
يُستعمل التابع get للحصول على محتوى ملف. يعيد التابع سلسلة نصية خام من محتويات الملف. تذكر أنّ كل مسارات الملفات يجب أن تُذكر في علاقة بالملف الجذر "root" المحدّد في ملف الضبط:
+
يُستعمل التابع <code>get</code> للحصول على محتوى ملف. يعيد التابع سلسلة نصية خام من محتويات الملف. تذكر أنّ كل مسارات الملفات يجب أن تُذكر في علاقة بالملف الجذر "root" المحدّد في ملف الضبط:<syntaxhighlight lang="php">
 
 
 
$contents = Storage::get('file.jpg');
 
$contents = Storage::get('file.jpg');
 
+
</syntaxhighlight>يُستعمل التابع <code>exists</code> للتأكد من وجود الملف على القرص:<syntaxhighlight lang="php">
يُستعمل التابع exists للتأكد من وجود الملف على القرص:
 
 
 
 
$exists = Storage::disk('s3')->exists('file.jpg');
 
$exists = Storage::disk('s3')->exists('file.jpg');
 +
</syntaxhighlight>
  
== تنزيل الملفات ==
+
=== تنزيل الملفات ===
يُستعمل التابع download لتوليد إجابة تفرض على متصفح المستخدم تنزيل ملف من مسار ممرَّر. يقبل التابع download اسم ملف كمعامل ثاني يُحدِّد اسم الملف الذي سيراه المستخدم بعد تنزيل الملف. أخيرًا، يمكن تمرير مصفوفة من ترويسات HTTP كمعامل ثالث للتابع
+
يُستعمل التابع <code>download</code> لتوليد إجابة تفرض على متصفح المستخدم تنزيل ملف من مسار ممرَّر. يقبل التابع <code>download</code> اسم ملف كمعامل ثاني يُحدِّد اسم الملف الذي سيراه المستخدم بعد تنزيل الملف. أخيرًا، يمكن تمرير مصفوفة من ترويسات HTTP كمعامل ثالث للتابع<syntaxhighlight lang="php">
 
 
 
return Storage::download('file.jpg');
 
return Storage::download('file.jpg');
 
 
return Storage::download('file.jpg', $name, $headers);
 
return Storage::download('file.jpg', $name, $headers);
  
== عنوان URL الملفات ==
 
يمكن استعمال التابع url للحصول على مسار URL لملف معيّن. إن كنت تستعمل المشغّل local، سيضيف التابع القيمة storage/ للعنوان الممرَّر ويعيد النتيجة. إن كنت تستخدم المشغّل s3 أو rackspace، سيعيد التابع العنوان البعيد الكامل:
 
  
 +
</syntaxhighlight>
 +
 +
=== عنوان URL الملفات ===
 +
يمكن استعمال التابع <code>url</code> للحصول على مسار URL لملف معيّن. إن كنت تستعمل المشغّل local، سيضيف التابع القيمة storage/ للعنوان الممرَّر ويعيد النتيجة. إن كنت تستخدم المشغّل s3 أو rackspace، سيعيد التابع العنوان البعيد الكامل:<syntaxhighlight lang="php">
 
use Illuminate\Support\Facades\Storage;
 
use Illuminate\Support\Facades\Storage;
 
 
$url = Storage::url('file.jpg');
 
$url = Storage::url('file.jpg');
  
تنبيه: تذكر أنّه إن كنت تستعمل المشغّل local، يجب أن توجد جميع الملفات العامة في الدليل storage/app/public. أيضًا، عليك إنشاء وصلة رمزية من public/storage إلى storage/app/public.
 
  
=== عناوين URL المؤقتة ===
+
</syntaxhighlight>تنبيه: تذكر أنّه إن كنت تستعمل المشغّل local، يجب أن توجد جميع الملفات العامة في الدليل <code>storage/app/public</code>. أيضًا، عليك إنشاء وصلة رمزية من <code>public/storage</code> إلى <code>storage/app/public</code>.
بالنسبة للملفات المخزَّنة باستعمال مشغّلات S3 أو rackspace، يمكن إحداث عنوان URL مؤقت لملف معيّن باستعمال التابع temporaryUrl. يقبل هذا التابع مسارًا ونسخة الكائن DateTime يحدّد وقت انتهاء صلاحية المسار:
 
  
 +
==== عناوين URL المؤقتة ====
 +
بالنسبة للملفات المخزَّنة باستعمال مشغّلات S3 أو rackspace، يمكن إحداث عنوان URL مؤقت لملف معيّن باستعمال التابع <code>temporaryUrl</code>. يقبل هذا التابع مسارًا ونسخة الكائن <code>DateTime</code> يحدّد وقت انتهاء صلاحية المسار:<syntaxhighlight lang="php">
 
$url = Storage::temporaryUrl(
 
$url = Storage::temporaryUrl(
  
 
   'file.jpg', now()->addMinutes(5)
 
   'file.jpg', now()->addMinutes(5)
 +
);
  
);
 
  
=== تخصيص عناوين URL المحلية ===
+
</syntaxhighlight>
إذا أردت التعريف المسبق للمستضيف للملفات المخزّنة على قرص باستعمال المشغّل local، يمكن إضافة الخيار url لمصفوفة ضبط القرص:
 
  
 +
==== تخصيص عناوين URL المحلية ====
 +
إذا أردت التعريف المسبق للمستضيف للملفات المخزّنة على قرص باستعمال المشغّل local، يمكن إضافة الخيار <code>url</code> لمصفوفة ضبط القرص:<syntaxhighlight lang="php">
 
'public' => [
 
'public' => [
  
 
   'driver' => 'local',
 
   'driver' => 'local',
 
 
   'root' => storage_path('app/public'),
 
   'root' => storage_path('app/public'),
 
 
   'url' => env('APP_URL').'/storage',
 
   'url' => env('APP_URL').'/storage',
 
 
   'visibility' => 'public',
 
   'visibility' => 'public',
  
 
],
 
],
  
== وصف بيانات الملفات ==
 
بالإضافة لقراءة وكتابة الملفات، يوفّر Laravel معلومات عن الملفات نفسها. مثلًا، يُستعمل التابع size لإعادة معلومات عن حجم الملف بالوحدة byte:
 
  
 +
</syntaxhighlight>
 +
 +
=== وصف بيانات الملفات File Metadata ===
 +
بالإضافة لقراءة وكتابة الملفات، يوفّر [[Laravel]] معلومات عن الملفات نفسها. مثلًا، يُستعمل التابع <code>size</code> لإعادة معلومات عن حجم الملف بالوحدة byte:<syntaxhighlight lang="php">
 
use Illuminate\Support\Facades\Storage;
 
use Illuminate\Support\Facades\Storage;
 
 
$size = Storage::size('file.jpg');
 
$size = Storage::size('file.jpg');
  
يعيد التابع lastModified وقت آخر تغيير طرأ على الملف:
 
  
 +
</syntaxhighlight>يعيد التابع <code>lastModified</code> وقت آخر تغيير طرأ على الملف:<syntaxhighlight lang="php">
 
$time = Storage::lastModified('file.jpg');
 
$time = Storage::lastModified('file.jpg');
 +
</syntaxhighlight>
  
= تخزين الملفات =
+
== تخزين الملفات ==
يُستعمل التابع put لتخزين محتويات خام لملف على قرص. يمكن تمرير مورد (php resource) للتابع put، ممّا يسمح باستغلال خاصية دعم التدفق في Flysystem. يُنصح  باستخدام التدفق في حال العمل بملفات ضخمة:
+
يُستعمل التابع <code>put</code> لتخزين محتويات خام لملف على قرص. يمكن تمرير مورد (php resource) للتابع <code>put</code>، ممّا يسمح باستغلال خاصية دعم التدفق في Flysystem. يُنصح  باستخدام التدفق في حال العمل بملفات ضخمة:<syntaxhighlight lang="php">
 
 
 
use Illuminate\Support\Facades\Storage;
 
use Illuminate\Support\Facades\Storage;
  
 
Storage::put('file.jpg', $contents);
 
Storage::put('file.jpg', $contents);
 +
Storage::put('file.jpg', $resource);
  
Storage::put('file.jpg', $resource);
+
 
 +
</syntaxhighlight>
  
 
=== التدفّق التلقائي ===
 
=== التدفّق التلقائي ===
إذا أردت أن يتحكم Laravel تلقائيا بتدفق ملف معيّن في مكان التخزين، استعمل التابع putFile أو putFileAs.
+
إذا أردت أن يتحكم Laravel تلقائيا بتدفق ملف معيّن في مكان التخزين، استعمل التابع <code>putFile</code> أو <code>putFileAs</code>.
 
 
يقبل هذا التابع مثيلا عن Illuminate\Http\File أو lluminate\Http\UploadedFile ويقوم بدفق الملف للمكان المحدّد:
 
  
 +
يقبل هذا التابع نسخة عن <code>Illuminate\Http\File</code> أو <code>lluminate\Http\UploadedFile</code> ويقوم بدفق الملف للمكان المحدّد:<syntaxhighlight lang="php">
 
use Illuminate\Http\File;
 
use Illuminate\Http\File;
 
 
use Illuminate\Support\Facades\Storage;
 
use Illuminate\Support\Facades\Storage;
 
 
// إحداث رقم خاص بالملف تلقائيًا
 
// إحداث رقم خاص بالملف تلقائيًا
 
 
Storage::putFile('photos', new File('/path/to/photo'));
 
Storage::putFile('photos', new File('/path/to/photo'));
  
 
// اختيار اسم الملف يدويًا
 
// اختيار اسم الملف يدويًا
 +
Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');
 +
  
Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');
 
  
هناك بعض المعلومات يجب معرفتها عند العمل بالتابع putFile. لاحظ أننا حددنا فقط اسم المجلد وليس اسم الملف. في العادة يصنع التابع رقم هوية ID فريدا لتكون اسم الملف. يُحدَّد ملحق اسم الملف بمعاينة نوع MIME الملف. يعيد التابع مسار الملف لذا يمكنك تخزين المسار بما فيه الإسم المصنوع في قاعدة البيانات.
 
  
يقبل التابعان putFile و putFileAs أيضًا معاملًا لتحديد إمكانية رؤية الملف المخزَّن. هذه الخاصية مفيدة خاصة في حال تخزين ملف في قرص سحابي مثل s3 وجعل الوصول إليه عموميًا:
+
</syntaxhighlight>هناك بعض المعلومات يجب معرفتها عند العمل بالتابع <code>putFile</code>. لاحظ أننا حددنا فقط اسم المجلد وليس اسم الملف. في العادة يصنع التابع رقم هوية <code>ID</code> فريدا لتكون اسم الملف. يُحدَّد ملحق اسم الملف بمعاينة نوع MIME الملف. يعيد التابع مسار الملف لذا يمكنك تخزين المسار بما فيه الإسم المصنوع في قاعدة البيانات.
  
 +
يقبل التابعان <code>putFile</code> و <code>putFileAs</code> أيضًا معاملًا لتحديد إمكانية رؤية الملف المخزَّن. هذه الخاصية مفيدة خاصة في حال تخزين ملف في قرص سحابي مثل s3 وجعل الوصول إليه عموميًا:<syntaxhighlight lang="php">
 
Storage::putFile('photos', new File('/path/to/photo'), 'public');
 
Storage::putFile('photos', new File('/path/to/photo'), 'public');
 +
</syntaxhighlight>
  
 
=== الإضافة للملف ===
 
=== الإضافة للملف ===
يسمح التابعان prepend و append بالإضافة لملفٍ ما في بدايته أو في نهايته:
+
يسمح التابعان <code>prepend</code> و <code>append</code> بالإضافة لملفٍ ما في بدايته أو في نهايته:<syntaxhighlight lang="php">
 +
Storage::prepend('file.log', 'إضافة في البداية');
 +
Storage::append('file.log', 'إضافة في النهاية');
  
Storage::prepend('file.log', 'إضافة في البداية');
 
  
Storage::append('file.log', 'إضافة في النهاية');
+
</syntaxhighlight>
  
 
=== نسخ ونقل الملفات ===
 
=== نسخ ونقل الملفات ===
يُستعمل التابع copy لنقل نسخة من ملف موجود لمكان جديد في القرص، في حين يُستخدم move لإعادة تسمية ملف أو نقله كليًا لمكان جديد:
+
يُستعمل التابع <code>copy</code> لنقل نسخة من ملف موجود لمكان جديد في القرص، في حين يُستخدم move لإعادة تسمية ملف أو نقله كليًا لمكان جديد:<syntaxhighlight lang="php">
 
 
 
Storage::copy('old/file.jpg', 'new/file.jpg');
 
Storage::copy('old/file.jpg', 'new/file.jpg');
 +
Storage::move('old/file.jpg', 'new/file.jpg');
  
Storage::move('old/file.jpg', 'new/file.jpg');
 
  
== رفع الملفات ==
+
</syntaxhighlight>
في تطبيقات الويب، يعدّ رفع ملف مثل صورة أو وثيقة من حالات الاستخدام الشائعة جدًا في تخزين الملفات. يجعل Laravel تخزين الملفات المرفوعة أمرًا سهلًا باستخدام التابع store على نسخة الكائن من الملف المرفوع. استدعِ التابع store مع المسار الذي تريد أن تخزّن الملف المرفوع فيه:
 
  
 +
=== رفع الملفات ===
 +
في تطبيقات الويب، يعدّ رفع ملف مثل صورة أو وثيقة من حالات الاستخدام الشائعة جدًا في تخزين الملفات. يجعل [[Laravel]] تخزين الملفات المرفوعة أمرًا سهلًا باستخدام التابع <code>store</code> على نسخة الكائن من الملف المرفوع. استدعِ التابع <code>store</code> مع المسار الذي تريد أن تخزّن الملف المرفوع فيه:<syntaxhighlight lang="php">
 
<?php
 
<?php
 
 
namespace App\Http\Controllers;
 
namespace App\Http\Controllers;
  
 
use Illuminate\Http\Request;
 
use Illuminate\Http\Request;
 
 
use App\Http\Controllers\Controller;
 
use App\Http\Controllers\Controller;
  
 
class UserAvatarController extends Controller
 
class UserAvatarController extends Controller
 
 
{
 
{
  
 
   /**
 
   /**
 
+
    * تحديث صورة المستخدم
    * Update the avatar for the user.
 
 
 
 
    *
 
    *
 
+
    * @param  Request $request
    * @param  Request $request
 
 
 
 
    * @return Response
 
    * @return Response
 
 
    */
 
    */
  
 
   public function update(Request $request)
 
   public function update(Request $request)
 
 
   {
 
   {
  
 
       $path = $request->file('avatar')->store('avatars');
 
       $path = $request->file('avatar')->store('avatars');
 
 
       return $path;
 
       return $path;
  
 
   }
 
   }
 +
}
 +
  
}
+
</syntaxhighlight>
  
 
هناك بعض الأمور المهمة التي يجب معرفتها. مثلًا، لاحظ أننا حددنا فقط اسم المجلد وليس اسم الملف. في العادة يُنشِئ التابع رقم مُعرِّف ID فريد ليكون اسم الملف. يُحدَّد ملحق اسم الملف بمعاينة نوع MIME للملف. يعيد التابع مسار الملف لذا يمكنك تخزين المسار بما فيه الاسم المُنشَأ في قاعدة البيانات.
 
هناك بعض الأمور المهمة التي يجب معرفتها. مثلًا، لاحظ أننا حددنا فقط اسم المجلد وليس اسم الملف. في العادة يُنشِئ التابع رقم مُعرِّف ID فريد ليكون اسم الملف. يُحدَّد ملحق اسم الملف بمعاينة نوع MIME للملف. يعيد التابع مسار الملف لذا يمكنك تخزين المسار بما فيه الاسم المُنشَأ في قاعدة البيانات.
  
يمكنك أيضًا استدعاء putFile من الواجهة الثابتة Storage للقيام بنفس العمل في المثال السابق:
+
يمكنك أيضًا استدعاء <code>putFile</code> من الواجهة الثابتة <code>Storage</code> للقيام بنفس العمل في المثال السابق:<syntaxhighlight lang="php">
 
 
 
$path = Storage::putFile('avatars', $request->file('avatar'));
 
$path = Storage::putFile('avatars', $request->file('avatar'));
 +
</syntaxhighlight>
  
=== تحديد اسم الملف ===
+
==== تحديد اسم الملف ====
إذا لم ترد أن يعطى اسم آلي للملفات، استعمل التابع storeAs الذي يقبل مسارًا، واسمًا للملف، وقرصًا (غير إجباري) كمعاملات:
+
إذا لم ترد أن يعطى اسم آلي للملفات، استعمل التابع <code>storeAs</code> الذي يقبل مسارًا، واسمًا للملف، وقرصًا (غير إجباري) كمعاملات:<syntaxhighlight lang="php">
 
 
 
$path = $request->file('avatar')->storeAs(
 
$path = $request->file('avatar')->storeAs(
 
+
  'avatars', $request->user()->id
   'avatars', $request->user()->id
 
  
 
);
 
);
  
يمكنك أيضًا استعمال التابع putFileAs من الواجهة الثابتة Storage للقيام بنفس عمل المثال السابق:
 
  
 +
</syntaxhighlight>يمكنك أيضًا استعمال التابع <code>putFileAs</code> من الواجهة الثابتة <code>Storage</code> للقيام بنفس عمل المثال السابق:<syntaxhighlight lang="php">
 
$path = Storage::putFileAs(
 
$path = Storage::putFileAs(
 
 
   'avatars', $request->file('avatar'), $request->user()->id
 
   'avatars', $request->file('avatar'), $request->user()->id
  
 
);
 
);
  
=== تحديد القرص ===
 
في العادة، يستخدم هذا التابع القرص الرئيسي. إذا أردت تحديد قرص آخر، مرّر اسم القرص كمعامل ثاني للتابع store
 
  
 +
</syntaxhighlight>
 +
 +
==== تحديد القرص ====
 +
في العادة، يستخدم هذا التابع القرص الرئيسي. إذا أردت تحديد قرص آخر، مرّر اسم القرص كمعامل ثاني للتابع <code>store:</code><syntaxhighlight lang="php">
 
$path = $request->file('avatar')->store(
 
$path = $request->file('avatar')->store(
 
 
   'avatars/'.$request->user()->id, 's3'
 
   'avatars/'.$request->user()->id, 's3'
  
 
);
 
);
  
== إمكانية رؤية الملفات ==
 
في تضمين Flysystem من Laravel، مرئية الوصول (visibility) هي تجريد لأذونات الملفات في مختلف المنصات. يمكن تعريف الملفات كملفات عمومية (public) أو خاصة (private). عند تعريف ملف كعمومي، أنت تعلن أنّ يمكن رؤيته من الآخرين. مثلًا، عند استخدام برنامج التشغيل S3، يمكنك استرداد عناوين URLs الخاصة بالملفات العامّة (public files).
 
  
يمكن تحديد إمكانية الرؤية عند إنشاء الملف عبر التابع put:
+
</syntaxhighlight>
 +
 
 +
=== إمكانية رؤية الملفات ===
 +
في تضمين Flysystem من Laravel، إمكانية رؤية الملفات (visibility) هي تجريد لأذونات الملفات في مختلف المنصات. يمكن تعريف الملفات كملفات عمومية (public) أو خاصة (private). عند تعريف ملف كعمومي، أنت تعلن أنّ يمكن رؤيته من الآخرين. مثلًا، عند استخدام برنامج التشغيل S3، يمكنك استرداد عناوين URLs الخاصة بالملفات العامّة (public files).
  
 +
يمكن تحديد إمكانية الرؤية عند إنشاء الملف عبر التابع <code>put</code>:<syntaxhighlight lang="php">
 
use Illuminate\Support\Facades\Storage;
 
use Illuminate\Support\Facades\Storage;
 
 
Storage::put('file.jpg', $contents, 'public');
 
Storage::put('file.jpg', $contents, 'public');
  
إذا كان الملف موجودًا مسبقًا، يمكن إعادة إمكانية الرؤية وتغييرها باستخدام التابعين getVisibility و setVisibility:
 
  
 +
</syntaxhighlight>إذا كان الملف موجودًا مسبقًا، يمكن إعادة إمكانية الرؤية وتغييرها باستخدام التابعين <code>getVisibility</code> و <code>setVisibility</code>:<syntaxhighlight lang="php">
 
$visibility = Storage::getVisibility('file.jpg');
 
$visibility = Storage::getVisibility('file.jpg');
 
 
Storage::setVisibility('file.jpg', 'public')
 
Storage::setVisibility('file.jpg', 'public')
  
= حذف الملفات =
 
يقبل التابع delete اسم ملف واحد أو مصفوفة ملفات لحذفها من القرص:
 
  
 +
</syntaxhighlight>
 +
 +
== حذف الملفات ==
 +
يقبل التابع <code>delete</code> اسم ملف واحد أو مصفوفة ملفات لحذفها من القرص:<syntaxhighlight lang="php">
 
use Illuminate\Support\Facades\Storage;
 
use Illuminate\Support\Facades\Storage;
  
 
Storage::delete('file.jpg');
 
Storage::delete('file.jpg');
 
 
Storage::delete(['file.jpg', 'file2.jpg']);
 
Storage::delete(['file.jpg', 'file2.jpg']);
  
يمكن تحديد القرص الذي يحتوي الملف إن احتجت لذلك:
 
  
 +
</syntaxhighlight>يمكن تحديد القرص الذي يحتوي الملف إن احتجت لذلك:<syntaxhighlight lang="php">
 
use Illuminate\Support\Facades\Storage;
 
use Illuminate\Support\Facades\Storage;
 +
Storage::disk('s3')->delete('folder_path/file_name.jpg');
 +
  
Storage::disk('s3')->delete('folder_path/file_name.jpg');
+
</syntaxhighlight>
  
= الدليل =
+
== المجلدات ==
  
 
=== إعادة كل الملفات من مجلد ===
 
=== إعادة كل الملفات من مجلد ===
يُرجع التابع files كل الملفات الموجودة في مجلّد ممرَّر كوسيط إليه. إذا أردت استرجاع كل الملفات حتى من المجلدات الفرعية، استخدم التابع allFiles:
+
يُرجع التابع <code>files</code> كل الملفات الموجودة في مجلّد ممرَّر كوسيط إليه. إذا أردت استرجاع كل الملفات حتى من المجلدات الفرعية، استخدم التابع <code>allFiles</code>:<syntaxhighlight lang="php">
 
 
 
use Illuminate\Support\Facades\Storage;
 
use Illuminate\Support\Facades\Storage;
  
 
$files = Storage::files($directory);
 
$files = Storage::files($directory);
 +
$files = Storage::allFiles($directory);
  
$files = Storage::allFiles($directory);
 
  
=== إعادة كل المجلدات في مجلد معين ===
+
</syntaxhighlight>
يُرجع التابع directories كل المجلدات الموجودة  في مجلد ممرّر كوسيط إليه . إذا أردت استرجاع كل المجلدات حتى من المجلدات الفرعية، استخدم التابع allDirectories
 
  
 +
=== إعادة كل المجلدات من مجلد معين ===
 +
يُرجع التابع <code>directories</code> كل المجلدات الموجودة  في مجلد ممرّر كوسيط إليه . إذا أردت استرجاع كل المجلدات حتى من المجلدات الفرعية، استخدم التابع <code>allDirectories:</code><syntaxhighlight lang="php">
 
$directories = Storage::directories($directory);
 
$directories = Storage::directories($directory);
  
 
// Recursive...
 
// Recursive...
 +
$directories = Storage::allDirectories($directory);
  
$directories = Storage::allDirectories($directory);
+
 
 +
</syntaxhighlight>
  
 
=== إنشاء مجلد ===
 
=== إنشاء مجلد ===
يُستخدم التابع makeDirectory لصناعة مجلد ممرَّر كوسيط إليه بما فيه المجلدات الفرعية
+
يُستخدم التابع <code>makeDirectory</code> لصناعة مجلد ممرَّر كوسيط إليه بما فيه المجلدات الفرعية<syntaxhighlight lang="php">
 
 
 
Storage::makeDirectory($directory);
 
Storage::makeDirectory($directory);
 +
</syntaxhighlight>
  
 
=== حذف مجلد ===
 
=== حذف مجلد ===
يُستخدم التابع deleteDirectory لحذف مجلد وكل ملفاته:
+
يُستخدم التابع <code>deleteDirectory</code> لحذف مجلد وكل ملفاته:<syntaxhighlight lang="php">
 
 
 
Storage::deleteDirectory($directory);
 
Storage::deleteDirectory($directory);
 +
</syntaxhighlight>
  
= نظام الملفات المخصص =
+
== نظام الملفات المخصص ==
 
وفّر تضمين Flysystem في Laravel واجهة لعدّة برامج تشغيل. لكنّه ليس محدودًا بها بل يوفّر أيضًا مكيّفات لعدّة أنظمة تخزين أخرى. يمكنك إنشاء برنامج تشغيل مخصص إذا أردت استعمال أحد المكيّفات الإضافية في تطبيقك.
 
وفّر تضمين Flysystem في Laravel واجهة لعدّة برامج تشغيل. لكنّه ليس محدودًا بها بل يوفّر أيضًا مكيّفات لعدّة أنظمة تخزين أخرى. يمكنك إنشاء برنامج تشغيل مخصص إذا أردت استعمال أحد المكيّفات الإضافية في تطبيقك.
  
لوضع نظام ملفات مخصص، ستحتاج لمكيّف Flysystem. لنضف المكيّف Dropbox مدعوما من مجموعة مستخدمين:
+
لوضع نظام ملفات مخصص، ستحتاج لمكيّف Flysystem. لنضف المكيّف Dropbox مدعوما من مجموعة مستخدمين:<syntaxhighlight lang="php">
 
 
 
composer require spatie/flysystem-dropbox
 
composer require spatie/flysystem-dropbox
 
+
</syntaxhighlight>بعد ذلك، يجب إنشاء موّفر خدمات مثل DropboxServiceProvider. في التابع boot من الموفر، استعمل التابع extend الواجهة الثابتة Storage لتعريف المشغّل المخصص:<syntaxhighlight lang="php">
بعد ذلك، يجب إنشاء موّفر خدمات مثل DropboxServiceProvider. في التابع boot من الموفر، استعمل التابع extend الواجهة الثابتة Storage لتعريف المشغّل المخصص:
 
 
 
 
<?php
 
<?php
  
سطر 381: سطر 369:
  
 
use Storage;
 
use Storage;
 
 
use League\Flysystem\Filesystem;
 
use League\Flysystem\Filesystem;
 
 
use Illuminate\Support\ServiceProvider;
 
use Illuminate\Support\ServiceProvider;
 
 
use Spatie\Dropbox\Client as DropboxClient;
 
use Spatie\Dropbox\Client as DropboxClient;
 
 
use Spatie\FlysystemDropbox\DropboxAdapter;
 
use Spatie\FlysystemDropbox\DropboxAdapter;
  
 
class DropboxServiceProvider extends ServiceProvider
 
class DropboxServiceProvider extends ServiceProvider
 
 
{
 
{
  
 
   /**
 
   /**
 
+
    * تنفيذ خدمات ما قبل التسجيل
    * Perform post-registration booting of services.
 
 
 
    *
 
 
 
 
    * @return void
 
    * @return void
 
 
    */
 
    */
  
 
   public function boot()
 
   public function boot()
 
 
   {
 
   {
  
سطر 411: سطر 388:
  
 
           $client = new DropboxClient(
 
           $client = new DropboxClient(
 
 
               $config['authorization_token']
 
               $config['authorization_token']
 +
          );
  
           );
+
          return new Filesystem(new DropboxAdapter($client));
 
 
           return new Filesystem(new DropboxAdapter($client));
 
  
 
       });
 
       });
 
 
   }
 
   }
  
 
   /**
 
   /**
 
+
    * تسجيل الارتباطات  في الحاوي
    * Register bindings in the container.
 
 
 
 
    *
 
    *
 
 
    * @return void
 
    * @return void
 
 
    */
 
    */
  
سطر 435: سطر 405:
  
 
   {
 
   {
 
 
      //
 
      //
 +
   }
 +
}
  
   }
 
  
}
+
</syntaxhighlight>
  
المعامل الأول في التابع extend هو اسم المشغّل، المعامل الثاني Closure يقبل المتغيّرين app$ و  config$. يعيد Closure بعد انتهائه نسخةً من League\Flysystem\Filesystem. يحتوي المتغيّر config$ قيمة config/filesystems.php للقرص المذكور.
+
المعامل الأول في التابع <code>extend</code> هو اسم المشغّل، المعامل الثاني Closure يقبل المتغيّرين <code>app$</code> و  <code>config$</code>. يعيد Closure بعد انتهائه نسخةً من <code>League\Flysystem\Filesystem</code>. يحتوي المتغيّر <code>config$</code> قيمة <code>config/filesystems.php</code> للقرص المذكور.
  
بعد إنشاء موّفر الخدمات، يمكن استعمال المشغّل dropbox في ملف الضبط config/filesystems.php.
+
بعد إنشاء موّفر الخدمات، يمكن استعمال برنامج التشغيل dropbox في ملف الضبط <code>config/filesystems.php</code>.
  
 
== مصادر ==
 
== مصادر ==
 
* [https://laravel.com/docs/5.6/filesystem صفحة File storage في ثوثيق Laravel الرسمي.]
 
* [https://laravel.com/docs/5.6/filesystem صفحة File storage في ثوثيق Laravel الرسمي.]

المراجعة الحالية بتاريخ 14:06، 24 أكتوبر 2018

مقدمة

يوفّر Laravel تجريدًا قويًا لنظام الملفات بفضل الحزمة Flysystem. يوفّر تضمين أنظمة الملفات في Laravel مشغّلات سهلة الاستعمال للتعامل مع الأنظمة المحلية و Amazon S3 والتخزين السحابي Rackspace، بل من السهل جدًا تغيير خيارات التخزين إذ تبقى وصلة API نفسها مع كل الأنظمة.

الضبط

يوجد ملف ضبط نظام الملفات في config/filesystems.php. يمكنك في هذا الملف ضبط كل الأقراص "disks". يمثّل كل قرص مشغّل تخزين ومكان تخزين خاص. يحتوي الملف على أمثلة ضبط لكل مشغّل مدعوم. لذا غيّر الملف حسب خياراتك ومعلوماتك الخاصة.

طبعًا، يمكنك ضبط أي عدد من الأقراص تريد أو حتى أقراص عديدة تستعمل نفس المشغّل.

القرص الصلب العام

القرص العام public مُعدٌّ للملفات التي سيكون ولوجها عامًّا. في العادة، يستخدم القرص public المشغل local ويُخزِّن الملفات في storage/app/public. لإتاحة إمكانية ولوجهم من الويب، يجب إنشاء وصلة رمزية من public/storage إلى storage/app/public. تُبقي هذه الطريقة كل الملفات العمومية في مكان واحد يمكن مشاركته بسهولة عند استعمال تقنية نشر دون وقت إيقاف مثل Envoyer.

لإنشاء الوصلة الرمزية، استعمل الأمر storage:link:

php artisan storage:link

بعد إنشاء الملف والوصلة الرمزية، يمكنك توليد عنوان URL للملف عبر الدالة المساعدة asset:

echo asset('storage/file.txt');

برنامج التشغيل المحلي

عند استخدام المشغّل المحلي local، كل الأعمال على الملفات موجودة في المجلد الجذر (root) المعرّف في ملف الضبط. في العادة، قيمته هي المجلد storage/app. لذا، الأمر الآتي سيُسجّل ملفًا في storage/app/file.txt:

Storage::disk('local')->put('file.txt', 'Contents');

متطلبات برنامج التشغيل

حزم Composer

قبل استخدام مشغّلات S3 أو SFTP أو Rackspace، ستحتاج أولا لتثبيت الحزم الملائمة عبر Composer:

  • league/flysystem-sftp ~1.0 :SFTP
  • league/flysystem-aws-s3-v3 ~1.0 :Amazon S3
  • league/flysystem-rackspace ~1.0 :Rackspace

من الضروري لأداء جيد استخدام مكيّفات تخزين مؤقت (cached adapter). ستحتاج حزمة أخرى لذلك:

  • league/flysystem-cached-adapter ~1.0 : CachedAdapter

ضبط مشغّل S3

توجد معلومات ضبط المشغّل S3 في الملف config/filesystems.php. يحتوي هذا الملف على مثال لمصفوفة ضبط لمشغل S3. لك حرية تغيير هذه المصفوفة بضبتك ومعلوماتك الخاصة. للتسهيل، يستعمل متغيرات البيئة أسماء مطابقة لطريقة التسمية  المتبعة في واجهة سطر الأوامر لخدمات AWS.

ضبط مشغّل FTP

يعمل مضمِّن نظام الملفات جيدًا مع FTP. لكن الملف filesystems.php لا يتضمن مثالًا عن الضبط. إن احتجت لضبط FTP يمكنك استعمال المثال التالي:

'ftp' => [

   'driver'   => 'ftp',
   'host'     => 'ftp.example.com',
   'username' => 'your-username',
   'password' => 'your-password',

  // خيارات غير إجبارية

  // 'port'     => 21,
  // 'root'     => '',
  // 'passive'  => true,
  // 'ssl'      => true,
  // 'timeout'  => 30,

],

ضبط مشغّل SFTP

يعمل مضمِّن نظام الملفات جيدًا مع SFTP. لكن الملف filesystems.php لا يتضمن مثالًا عن الضبط. إن احتجت لضبط FTP يمكنك استعمال المثال التالي:

'sftp' => [

   'driver' => 'sftp',
   'host' => 'example.com',
   'username' => 'your-username',
   'password' => 'your-password',

  // ضبط مفتاح SSH
  // 'privateKey' => '/path/to/privateKey',
  // 'password' => 'encryption-password',
  // Optional SFTP Settings...
  // 'port' => 22,
  // 'root' => '',
  // 'timeout' => 30,

],

ضبط مشغّل Rackspace

يعمل مضمِّن نظام الملفات جيدًا مع Rackspace. لكن الملف filesystems.php لا يتضمن مثالًا عن الضبط. إن احتجت لضبط FTP يمكنك استعمال المثال التالي:

'rackspace' => [

   'driver'    => 'rackspace',
   'username'  => 'your-username',
   'key'       => 'your-key',
   'container' => 'your-container',
   'endpoint'  => 'https://identity.api.rackspacecloud.com/v2.0/',
   'region'    => 'IAD',
   'url_type'  => 'publicURL',

],

التخزين المؤقت

لتمكين قرص ما من استخدام التخزين المؤقت، تضاف التعليمة cache لخيارات ضبط القرص. يجب أن يكون الخيار cache مصفوفة من خيارات التخزين تحتوي الاسم disk

's3' => [

   'driver' => 's3',
  // خيارات أخرى

   'cache' => [

       'store' => 'memcached',
       'expire' => 600,
       'prefix' => 'cache-prefix',

   ],
],

وتاريخ انتهاء الصلاحية expire إضافة إلى سابقة prefix:

الحصول على نسخة من كائن القرص

تُستعمل الواجهة الساكنة Storage للتفاعل مع عدّة أقراص مضبوطة. مثلًا، يٌستعمل التابع put من الواجهة لتخزين نسخة avatar في القرص الرئيسي. إذا ناديت التابع put على الواجهة الثابتة Storage دون أن تنادي call أولا،تُستدعى الدالة call تلقائيًا للقرص الرئيسي:

use Illuminate\Support\Facades\Storage;
Storage::put('avatars/1', $fileContents);

إذا كان التطبيق يتعامل مع أكثر من قرص، يمكن استعمال التابع disk من الواجهة الثابتة Storage

Storage::disk('s3')->put('avatars/1', $fileContents);

للعمل على ملفات في قرص معيّن:

Storage::disk('s3')->put('avatars/1', $fileContents);

استرداد الملفات

يُستعمل التابع get للحصول على محتوى ملف. يعيد التابع سلسلة نصية خام من محتويات الملف. تذكر أنّ كل مسارات الملفات يجب أن تُذكر في علاقة بالملف الجذر "root" المحدّد في ملف الضبط:

$contents = Storage::get('file.jpg');

يُستعمل التابع exists للتأكد من وجود الملف على القرص:

$exists = Storage::disk('s3')->exists('file.jpg');

تنزيل الملفات

يُستعمل التابع download لتوليد إجابة تفرض على متصفح المستخدم تنزيل ملف من مسار ممرَّر. يقبل التابع download اسم ملف كمعامل ثاني يُحدِّد اسم الملف الذي سيراه المستخدم بعد تنزيل الملف. أخيرًا، يمكن تمرير مصفوفة من ترويسات HTTP كمعامل ثالث للتابع

return Storage::download('file.jpg');
return Storage::download('file.jpg', $name, $headers);

عنوان URL الملفات

يمكن استعمال التابع url للحصول على مسار URL لملف معيّن. إن كنت تستعمل المشغّل local، سيضيف التابع القيمة storage/ للعنوان الممرَّر ويعيد النتيجة. إن كنت تستخدم المشغّل s3 أو rackspace، سيعيد التابع العنوان البعيد الكامل:

use Illuminate\Support\Facades\Storage;
$url = Storage::url('file.jpg');

تنبيه: تذكر أنّه إن كنت تستعمل المشغّل local، يجب أن توجد جميع الملفات العامة في الدليل storage/app/public. أيضًا، عليك إنشاء وصلة رمزية من public/storage إلى storage/app/public.

عناوين URL المؤقتة

بالنسبة للملفات المخزَّنة باستعمال مشغّلات S3 أو rackspace، يمكن إحداث عنوان URL مؤقت لملف معيّن باستعمال التابع temporaryUrl. يقبل هذا التابع مسارًا ونسخة الكائن DateTime يحدّد وقت انتهاء صلاحية المسار:

$url = Storage::temporaryUrl(

   'file.jpg', now()->addMinutes(5)
);

تخصيص عناوين URL المحلية

إذا أردت التعريف المسبق للمستضيف للملفات المخزّنة على قرص باستعمال المشغّل local، يمكن إضافة الخيار url لمصفوفة ضبط القرص:

'public' => [

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

],

وصف بيانات الملفات File Metadata

بالإضافة لقراءة وكتابة الملفات، يوفّر Laravel معلومات عن الملفات نفسها. مثلًا، يُستعمل التابع size لإعادة معلومات عن حجم الملف بالوحدة byte:

use Illuminate\Support\Facades\Storage;
$size = Storage::size('file.jpg');

يعيد التابع lastModified وقت آخر تغيير طرأ على الملف:

$time = Storage::lastModified('file.jpg');

تخزين الملفات

يُستعمل التابع put لتخزين محتويات خام لملف على قرص. يمكن تمرير مورد (php resource) للتابع put، ممّا يسمح باستغلال خاصية دعم التدفق في Flysystem. يُنصح  باستخدام التدفق في حال العمل بملفات ضخمة:

use Illuminate\Support\Facades\Storage;

Storage::put('file.jpg', $contents);
Storage::put('file.jpg', $resource);

التدفّق التلقائي

إذا أردت أن يتحكم Laravel تلقائيا بتدفق ملف معيّن في مكان التخزين، استعمل التابع putFile أو putFileAs.

يقبل هذا التابع نسخة عن Illuminate\Http\File أو lluminate\Http\UploadedFile ويقوم بدفق الملف للمكان المحدّد:

use Illuminate\Http\File;
use Illuminate\Support\Facades\Storage;
// إحداث رقم خاص بالملف تلقائيًا
Storage::putFile('photos', new File('/path/to/photo'));

// اختيار اسم الملف يدويًا
Storage::putFileAs('photos', new File('/path/to/photo'), 'photo.jpg');

هناك بعض المعلومات يجب معرفتها عند العمل بالتابع putFile. لاحظ أننا حددنا فقط اسم المجلد وليس اسم الملف. في العادة يصنع التابع رقم هوية ID فريدا لتكون اسم الملف. يُحدَّد ملحق اسم الملف بمعاينة نوع MIME الملف. يعيد التابع مسار الملف لذا يمكنك تخزين المسار بما فيه الإسم المصنوع في قاعدة البيانات. يقبل التابعان putFile و putFileAs أيضًا معاملًا لتحديد إمكانية رؤية الملف المخزَّن. هذه الخاصية مفيدة خاصة في حال تخزين ملف في قرص سحابي مثل s3 وجعل الوصول إليه عموميًا:

Storage::putFile('photos', new File('/path/to/photo'), 'public');

الإضافة للملف

يسمح التابعان prepend و append بالإضافة لملفٍ ما في بدايته أو في نهايته:

Storage::prepend('file.log', 'إضافة في البداية');
Storage::append('file.log', 'إضافة في النهاية');

نسخ ونقل الملفات

يُستعمل التابع copy لنقل نسخة من ملف موجود لمكان جديد في القرص، في حين يُستخدم move لإعادة تسمية ملف أو نقله كليًا لمكان جديد:

Storage::copy('old/file.jpg', 'new/file.jpg');
Storage::move('old/file.jpg', 'new/file.jpg');

رفع الملفات

في تطبيقات الويب، يعدّ رفع ملف مثل صورة أو وثيقة من حالات الاستخدام الشائعة جدًا في تخزين الملفات. يجعل Laravel تخزين الملفات المرفوعة أمرًا سهلًا باستخدام التابع store على نسخة الكائن من الملف المرفوع. استدعِ التابع store مع المسار الذي تريد أن تخزّن الملف المرفوع فيه:

<?php
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Http\Controllers\Controller;

class UserAvatarController extends Controller
{

   /**
    * تحديث صورة المستخدم
    *
    * @param  Request $request
    * @return Response
    */

   public function update(Request $request)
   {

       $path = $request->file('avatar')->store('avatars');
       return $path;

   }
}

هناك بعض الأمور المهمة التي يجب معرفتها. مثلًا، لاحظ أننا حددنا فقط اسم المجلد وليس اسم الملف. في العادة يُنشِئ التابع رقم مُعرِّف ID فريد ليكون اسم الملف. يُحدَّد ملحق اسم الملف بمعاينة نوع MIME للملف. يعيد التابع مسار الملف لذا يمكنك تخزين المسار بما فيه الاسم المُنشَأ في قاعدة البيانات.

يمكنك أيضًا استدعاء putFile من الواجهة الثابتة Storage للقيام بنفس العمل في المثال السابق:

$path = Storage::putFile('avatars', $request->file('avatar'));

تحديد اسم الملف

إذا لم ترد أن يعطى اسم آلي للملفات، استعمل التابع storeAs الذي يقبل مسارًا، واسمًا للملف، وقرصًا (غير إجباري) كمعاملات:

$path = $request->file('avatar')->storeAs(
  'avatars', $request->user()->id

);

يمكنك أيضًا استعمال التابع putFileAs من الواجهة الثابتة Storage للقيام بنفس عمل المثال السابق:

$path = Storage::putFileAs(
   'avatars', $request->file('avatar'), $request->user()->id

);

تحديد القرص

في العادة، يستخدم هذا التابع القرص الرئيسي. إذا أردت تحديد قرص آخر، مرّر اسم القرص كمعامل ثاني للتابع store:

$path = $request->file('avatar')->store(
   'avatars/'.$request->user()->id, 's3'

);

إمكانية رؤية الملفات

في تضمين Flysystem من Laravel، إمكانية رؤية الملفات (visibility) هي تجريد لأذونات الملفات في مختلف المنصات. يمكن تعريف الملفات كملفات عمومية (public) أو خاصة (private). عند تعريف ملف كعمومي، أنت تعلن أنّ يمكن رؤيته من الآخرين. مثلًا، عند استخدام برنامج التشغيل S3، يمكنك استرداد عناوين URLs الخاصة بالملفات العامّة (public files).

يمكن تحديد إمكانية الرؤية عند إنشاء الملف عبر التابع put:

use Illuminate\Support\Facades\Storage;
Storage::put('file.jpg', $contents, 'public');

إذا كان الملف موجودًا مسبقًا، يمكن إعادة إمكانية الرؤية وتغييرها باستخدام التابعين getVisibility و setVisibility:

$visibility = Storage::getVisibility('file.jpg');
Storage::setVisibility('file.jpg', 'public')

حذف الملفات

يقبل التابع delete اسم ملف واحد أو مصفوفة ملفات لحذفها من القرص:

use Illuminate\Support\Facades\Storage;

Storage::delete('file.jpg');
Storage::delete(['file.jpg', 'file2.jpg']);

يمكن تحديد القرص الذي يحتوي الملف إن احتجت لذلك:

use Illuminate\Support\Facades\Storage;
Storage::disk('s3')->delete('folder_path/file_name.jpg');

المجلدات

إعادة كل الملفات من مجلد

يُرجع التابع files كل الملفات الموجودة في مجلّد ممرَّر كوسيط إليه. إذا أردت استرجاع كل الملفات حتى من المجلدات الفرعية، استخدم التابع allFiles:

use Illuminate\Support\Facades\Storage;

$files = Storage::files($directory);
$files = Storage::allFiles($directory);

إعادة كل المجلدات من مجلد معين

يُرجع التابع directories كل المجلدات الموجودة  في مجلد ممرّر كوسيط إليه . إذا أردت استرجاع كل المجلدات حتى من المجلدات الفرعية، استخدم التابع allDirectories:

$directories = Storage::directories($directory);

// Recursive...
$directories = Storage::allDirectories($directory);

إنشاء مجلد

يُستخدم التابع makeDirectory لصناعة مجلد ممرَّر كوسيط إليه بما فيه المجلدات الفرعية

Storage::makeDirectory($directory);

حذف مجلد

يُستخدم التابع deleteDirectory لحذف مجلد وكل ملفاته:

Storage::deleteDirectory($directory);

نظام الملفات المخصص

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

لوضع نظام ملفات مخصص، ستحتاج لمكيّف Flysystem. لنضف المكيّف Dropbox مدعوما من مجموعة مستخدمين:

composer require spatie/flysystem-dropbox

بعد ذلك، يجب إنشاء موّفر خدمات مثل DropboxServiceProvider. في التابع boot من الموفر، استعمل التابع extend الواجهة الثابتة Storage لتعريف المشغّل المخصص:

<?php

namespace App\Providers;

use Storage;
use League\Flysystem\Filesystem;
use Illuminate\Support\ServiceProvider;
use Spatie\Dropbox\Client as DropboxClient;
use Spatie\FlysystemDropbox\DropboxAdapter;

class DropboxServiceProvider extends ServiceProvider
{

   /**
    * تنفيذ خدمات ما قبل التسجيل 
    * @return void
    */

   public function boot()
   {

       Storage::extend('dropbox', function ($app, $config) {

           $client = new DropboxClient(
               $config['authorization_token']
          );

          return new Filesystem(new DropboxAdapter($client));

       });
   }

   /**
    * تسجيل الارتباطات  في الحاوي
    *
    * @return void
    */

   public function register()

   {
      //
   }
}

المعامل الأول في التابع extend هو اسم المشغّل، المعامل الثاني Closure يقبل المتغيّرين app$ و  config$. يعيد Closure بعد انتهائه نسخةً من League\Flysystem\Filesystem. يحتوي المتغيّر config$ قيمة config/filesystems.php للقرص المذكور.

بعد إنشاء موّفر الخدمات، يمكن استعمال برنامج التشغيل dropbox في ملف الضبط config/filesystems.php.

مصادر