Laravel/cache

التخزين المؤقت الضبط يوفر Laravel واجهة برمجيّة معبّرة وموحّدة لكل التخزين المؤقت. يوجد ملف ضبط التخزين في config/cache.php. في هذا الملف، يمكن تحديد مشغّل التخزين الذي سيُستعمل تلقائيًّا في كامل التطبيق. يدعم Laravel العديد من الواجهات الخلفيّة الشائعة مثل Memcached و Recis من البداية. يحتوي ملف ضبط التخزين أيضًا على خيارات متعدّدة مفصّلة في الملف ذاته لذا تأكد من قراءته جيدا. تلقائيًّا، يستعمل Laravel برنامج التشغيل file للتخزبن المؤقت، يسجل هذا المشغل الكائنات المخزّنة بطريقة متسلسلة في نظام الملفات. بالنسبة للتطبيقات الكبيرة، من المنصوح به استعمال برامج تشغيل أفضل مثل Memcached أو Redis. يمكنك أيضًا إعداد أكثر من ضبط لبرنامج تشغيل واحد. المتطلبات الأساسية لبرنامج التشغيل Database عند استعمال برنامج تشغيل التخزين المؤقت Database، ستحتاج لتثبيت جدول لاحتواء العناصر المخزّنة. ستجد في المثال التالي تعريف مخطط (schema) للجدول: Schema::create('cache', function ($table) {

   $table->string('key')->unique();
   $table->text('value');
   $table->integer('expiration');

}); ملاحظة: يمكن أيضا استعمال الأمر php artisan cache:table لإنتاج تهجير بالمخطط المناسب. Memcached يتطلب استخدام برنامج التشغيل Memcached أولًا تثيت حزمة Memcached PECL. يمكنك تسجيل كل خوادم Memcached في الملف config/cache.php: 'memcached' => [

   [
       'host' => '127.0.0.1',
       'port' => 11211,
       'weight' => 100
   ],

], يمكن ربط الخيار host بمسار يشير إلى Unix socket (أو إلى اختصار يشير إلىUnix socket). إذا قمت بهذا، فعليك إعطاء الخيار port القيمة 0:

'memcached' => [

   [
       'host' => '/var/run/memcached/memcached.sock',
       'port' => 0,
       'weight' => 100
   ],

], Redis قبل استعمال برنامج تشغيل التخزين المؤقت Redis مع Laravel، ستحتاج أولًا إمّا لتثبيت الحزمة predis/predis عن طريق composer أو لتثبيت إضافة PhpRedis عن طريق PECL. للمزيد من المعلومات حول ضبط Redis، راجع صفحة توثيق Laravel. استعمال التخزين المؤقت الحصول على نسخة تخزين يوفّر العقدان Illuminate/Contracts/Cache/Factory و Illuminate/Contracts/Cache/Repository مدخلًا لخدمات التخزين المؤقت في Laravel. يوفر العقد Factory مدخلًا لكل برامج التشغيل المعرَّفة في التطبيق بينما يوفّر Repository عادة تنفيذ برنامج التشغيل الافتراضي للتطبيق مثلما هو مذكور في ملف ضبط التخزين المؤقت. لكن يمكن أيضًا استعمال الواجهة الساكنة Cache، وهي ما سنستخدمه في هذا التوثيق. توفّر الواجهة الساكنة Cache طريقة وصول مقتضبة ومناسبة إلى عقود التخزين المؤقت الأساسية: <?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Cache;

class UserController extends Controller {

   /**
    * إظهار لائحة المستخدمين
    *
    * @return Response
    */
   public function index()
   {
       $value = Cache::get('key');
      //
   }

} الوصول إلى المخازن المؤقتة المتعدّدة باستعمال الواجهة الساكنة Cache، يمكنك الوصول إلى العديد من المخازن المؤقتة باستعمال التابع store. يجب أن يوافق المفتاح الممرّر للتابع store لأحد المخازن المذكورة في مصفوفة الضبط stores الموجودة في ملف الضبط: $value = Cache::store('file')->get('foo');

Cache::store('redis')->put('bar', 'baz', 10); استرداد عناصر من التخزين المؤقت يُستعمل التابع get من الواجهة الساكنة Cache استرداد العناصر المخزّنة موقّتًا. إن كان العنصر المطلوب استرداده غير مخزَّن، سيعيد التابع القيمة null. إن أردت، بإمكانك تمرير معامِل ثاني للتابع تحدّد فيه القيمة الافتراضية في حال عدم وجود العنصر: $value = Cache::get('key');

$value = Cache::get('key', 'default') يمكنك حتى تمرير نطاق مغلق Closure كقيمة مبدئية. ستُعاد في هذه الحالة نتيجة النطاق المغلق Closure في حال عدم وجود العنصر في التخزين المؤقت. يسمح لك تمرير النطاق المغلق Closure تأجيل استرداد القيم الافتراضية من قاعدة البيانات أو من خدمات خارجيّة أخرى: $value = Cache::get('key', function () {

   return DB::table(...)->get();

}); التحقّق من وجود العنصر يُستعمل التابع has للتحقّق من وجود العنصر في التخزين المؤقت. يُرجع التابع القيمة false إن كانت النتيجة false أو null: if (Cache::has('key')) {

  //

} زيادة/نقصان القيم يٌستعمل التابعان increment و decrement لتعديل قيمة الأعداد في التخزين المؤقت. يقبل كلا التابعان معاملات غير إجبارية تحدّد القيمة المضافة أو المنقوصة من العدد: Cache::increment('key'); Cache::increment('key', $amount); Cache::decrement('key'); Cache::decrement('key', $amount); الاسترداد والتخزين قد تريد في بعض الأحيان أن تستردّ عنصرًا مخزّنًا وتخزّن قيمة افتراضية في حال عدم وجوده. مثلًا، قد تريد استرداد لائحة المستخدمين من التخزين المؤقت أو استردادها من قاعدة البيانات و تخزينها إن لم تكن مخزنة من البداية. يمكن القيام بذلك باستعمال التابع Cache::remember: $value = Cache::remember('users', $minutes, function () {

   return DB::table('users')->get();

}); في حال عدم وجود المستخدمين في التخزين المؤقت، يُنفّذ كائن Closure الممرّر كمعامل و يعيد المستخدمين كنتيجة تحفظ في التخزين المؤقت. يُستعمل التابع rememberforever لنفس الغرض لكن مدّة التخزين المؤقت التي يضعها هذا التابع أبدية: $value = Cache::rememberForever('users', function() {

   return DB::table('users')->get();

}); الاسترداد والحذف قد تحتاج لاسترداد عنصر ثمّ حذفه من التخزين المؤقت. يُستعمل التابع pull لهذا الغرض. مثل التابع get، يُعيد التابع pull القيمة null في حال عدم وجود العنصر: $value = Cache::pull('key'); تخزين العناصر مؤقّتًا يمكنك استعمال التابع put من الواجهة الساكنة Cache لوضع البيانات في التخزين المؤقت. يجب ذكر عدد الدقائق التي تبقى فيها البيانات مخزّنة:

Cache::put('key', 'value', $minutes);

يمكن أيضًا إضافة معامل من نوع DateTime لتحديد تاريخ انقضاء صلاحية البيانات المخزّنة بدل عدد الدقائق: $expiresAt = now()->addMinutes(10);

Cache::put('key', 'value', $expiresAt); التخزين في حالة عدم الوجود يُضيف التابع add البيانات إلى التخزين إذا لم تكن مخزّنة أصلًا. يُرجع هذا التابع القيمة true إذا أضيفت البيانات بنجاح و القيمة false عدا ذلك: Cache::add('key', 'value', $minutes);

التخزين الأبدي للعناصر يُستعمل التابع forever لتخزين البيانات بصفة دائمة. بما أنّ ليس لهذه البيانات تاريخ انتهاء صلوحية، يجب حذفها يدويًّا عبر التابع forget: Cache::forever('key', 'value'); ملاحظة: إن كنت تستعمل برنامج التشغيل MemCached، يمكن أن تُمحى البيانات المخزّنة عن طريق forever إذا بلغ حجم التخزين الحد الأقصى. حذف العناصر من التخزين المؤقت يمكن استخدام التابع forget لحذف العناصر من التخزين المؤقت: Cache::forget('key'); يمكن تفريغ كامل التخزين المؤقت عبر التابع flush: Cache::flush(); تنبيه: التفريغ لا يحترم أي قواعد ويمحو كل البيانات من التخزين المؤقت. يجب الإنتباه جيدا عند تفريغ تخزين مؤقت مشترك بين عدّة تطبيقات. القفل الذرّي تنبيه: لا يمكن استعمال هذه الخاصية إلّا إذا برنامج تشغيل التخزين المستعمل Memcached أو redis هو برنامج التشغيل الافتراضي في التطبيق. أيضًا، يجب أن تكون كل الخوادم باتصال بخادم تخزين مركزي موحّد.

تسمح الأقفال الذرية بالتحكم في الأقفال الموزعة دون ااهتمام بالشروط. مثلا، يَستعمل Laravel Forge الأقفال الذرية ليضمن أنّ مهمّة واحدة تعمل على الخادم في أي وقت. يمكنك الإنشاء والتصرف في الأقفال عبر التابع Cache::lock: if (Cache::lock('foo', 10)->get()) {

  // Lock acquired for 10 seconds...

   Cache::lock('foo')->release();

} يقبل التابع lock كائن closure، بعد تنفيذ عمل النطاق المغلق Closure، يفكّ Laravel تلقائيًّا القفل: Cache::lock('foo')->get(function () {

  // يُكتسب القفل إلى أجل غير مسمّى ويُفكّ تلقائيا

}); إذا كان القفل غير متوفّر لحظة طلبه، يمكنك جعل Laravel ينتظره: if (Cache::lock('foo', 10)->block()) {

  // قفل مُكتَسَب بعد الإنتظار

} في الحالة العادية، ينتظر التابع block إلى أن يتوفّر القفل. يمكنك استعمال blockfor لحد مدة الإنتظار بعدد ثواني معيّن. إذا لم يتوفّر القفل في الفترة المحددة، يُرفع الاستثناء : Illuminate\Contracts\Cache\LockTimeoutException :

if (Cache::lock('foo', 10)->blockFor(5)) {

  //قفل مكتسب بعد انتظار 5 ثواني على الأكثر

}

Cache::lock('foo', 10)->blockFor(5, function () {

  ///قفل مكتسب بعد انتظار 5 ثواني على الأكثر

});

مساعد التخزين المؤقت بالإضافة إلى استعمال الواجهة الساكنة Cache والعقد cache، يمكنك أيضا استعمال الدالة العامة cache لاسترداد وتخزين البيانات مؤقتًا. عندما تنادى الدالة cache بمعامل سلسلي واحد، ستعيد قيمة المفتاح الممَرّر: $value = cache('key'); إذا وفّرت مصفوفة من الثنائيات مفاتيح/قيم مع تاريخ صلوحية، ستقوم الدالة بتخزين البيانات للمدة المحددة: cache(['key' => 'value'], $minutes);

cache(['key' => 'value'], now()->addSeconds(10)); ملاحظة: عند اختبار النداء للدالة العامّة cache، يمكن استعمال Cache::shouldReceive كما في اختبار الواجهات الساكنة. وسوم التخزين المؤقت تنبيه: وسوم التخزين المؤقت غير مدعومة عند استخدام برنامجي التشغيل file أو database. أيضًا، عند عند محاولة التخزين «الدائم» لعدّة وسوم من وسوم التخزين المؤقت، يُفضَّل استخدام برامج تشغيل مثل Memcached التي تفرغ تلقائيًّا التسجيلات منتهية الصلاحيّة. تخزين عناصر التخزين المؤقت للوسوم تُتيح وسوم التخزين المؤقت إمكانية جمع العناصر المتشابهة في التخزين المؤقت تحت وسم واحد ثم إمكانية حذف كل العناصر الحاملة لنفس الوسم دفعة واحدة. يمكنك الوصول إلى التخزين المؤقت للوسوم بتمرير مصفوفة من أسماء الوسوم. لنصل مثلًا إلى التخزين المؤقت للوسوم ونضف بعض القيم: Cache::tags(['people', 'artists'])->put('John', $john, $minutes);

Cache::tags(['people', 'authors'])->put('Anne', $anne, $minutes);

الوصول إلى عناصرالتخزين المؤقت للوسوم لاسترجاع عناصر مخزنة حاملة لعلامات، مرّر قائمة العلامات للتابع tags ثم استعمل التابع get مع المفتاح الذي تريد استرجاعه $john = Cache::tags(['people', 'artists'])->get('John');

$anne = Cache::tags(['people', 'authors'])->get('Anne'); حذف عناصرالتخزين المؤقت للوسوم يمكن حذف جميع العناصر المخزّنة الحاملة لنفس الوسم أو مجموعة من الوسوم. مثلًا، إذا أردت حذف جميع العناصر الحاملة إمّا للوسم people أو للوسم authors أو كليهما، كلّ من John و Anne ستحذف من التخزين المؤقت: Cache::tags(['people', 'authors'])->flush(); في المقابل، الصياغة الموالية ستحذف فقط العناصر الحاملة للوسم authors، أي أنّ John لن يحذف بل فقط Anne: Cache::tags('authors')->flush(); إضافة برامج تشغيل مخصصة للتخزين المؤقت كتابة برنامج التشغيل لإنشاء برنامج تشغيل مخصّص، نحتاج في البداية لاستخدام (implement) العقد Illuminate\Contracts\Cache\Store. لذا، فإن تعريف استخدام (implementation) التخزين المؤقت ل MongoDB مثلًا سيشبه ما يلي: namespace App\Extensions;

use Illuminate\Contracts\Cache\Store;

class MongoStore implements Store {

   public function get($key) {}
   public function many(array $keys);
   public function put($key, $value, $minutes) {}
   public function putMany(array $values, $minutes);
   public function increment($key, $value = 1) {}
   public function decrement($key, $value = 1) {}
   public function forever($key, $value) {}
   public function forget($key) {}
   public function flush() {}
   public function getPrefix() {}

} كل ما نحتاجه الآن هو كتابة كل هذه التوابع باستعمال اتصال MongoDB. لمعرفة كيف تكتب التوابع، ألق نظرة على الملف Illuminate\Cache\MemcachedStore. عند الانتهاء من تعريف الاستخدام، يمكنك إنهاء تسجيل برنامج التشغيل المخصص: Cache::extend('mongo', function ($app) {

   return Cache::repository(new MongoStore);

}); ملاحظة: إن كنت تتساءل أين تضع شيفرة المشغّل الخاص، يمكنك إنشاء إضافة (extension) تحت الدليل app لكن تذكر أنّ Laravel لا يفرض هيكلة موحدة وأنّ بإمكانك ترتيب التطبيق كيفما تريد. تسجيل برنامج التشغيل لتسجيل برنامج التشغيل المخصص في Laravel، ستستعمل التابع extend من الواجهة الساكنة Cache. النداء Cache::extend يمكن أن يتم في التابع boot من الملف App\Providers\AppServiceProvider الذي يأتي مع أي تطبيق Laravel جديد. أو يمكنك إنشاء ملف مقدم خدمات خاص بك ليحتضن الإضافة، لا تنس تسجيل ال مقدم الجديد في مصفوفة المقدمين في config/app.php: namespace App\Providers;

use App\Extensions\MongoStore; use Illuminate\Support\Facades\Cache; use Illuminate\Support\ServiceProvider;

class CacheServiceProvider extends ServiceProvider {

   /**
    * خدمات ما قبل التسجيل
    *
    * @return void
    */
   public function boot()
   {
       Cache::extend('mongo', function ($app) {
           return Cache::repository(new MongoStore);
       });
   }
   /**
    * تسجيل الروابط في الحاوي
    *
    * @return void
    */
   public function register()
   {
      //
   }

} المعامل الأول الممرّر للتابع extend هو اسم برنامج التشغيل. سيتوافق هذا الاسم مع الخيار driver في ملف الضبط config/cache.php.المعامل الثاني هو closure سيُعيد نسخة من Illuminate\Cache\Repository. سيُمرَّر للClosure نسخة من app$ وهو نسخة من حاوي الخدمات. بعد تسجيل الإضافة، حدث الخيار driver من ملف الضبط config/cache.php باسم الإضافة. الأحداث لتنفيذ شيفرة ما مع كل عملية تخزين مؤقت، يمكنك الاستماع للأحداث التي تطلقها عملية التخزين المؤقت. في العادة، توضع المنصتات في الملف EventServiceProvider: /**

* ربط المنصتات في التطبيق
*
* @var array
*/

protected $listen = [

   'Illuminate\Cache\Events\CacheHit' => [
       'App\Listeners\LogCacheHit',
   ],

   'Illuminate\Cache\Events\CacheMissed' => [
       'App\Listeners\LogCacheMissed',
   ],

   'Illuminate\Cache\Events\KeyForgotten' => [
       'App\Listeners\LogKeyForgotten',
   ],

   'Illuminate\Cache\Events\KeyWritten' => [
       'App\Listeners\LogKeyWritten',
   ],

]; مصادر صفحة Cache في توثيق Laravel الرسمي.