English | العربية | বাংলা | Bosanski | Deutsch | Español | Français | हिन्दी | Italiano | 日本語 | 한국어 | मराठी | Português | Русский | Kiswahili | தமிழ் | తెలుగు | Türkçe | اردو | Tiếng Việt | 中文

• المقدمة
  • الميزات الرئيسية
  • مثال
• التثبيت
  • المتطلبات
• الاستخدام
  • الإعداد الأساسي
  • كيفية العمل
  • تكامل Octane
• التكوين
  • التمكين/التعطيل
  • متجر Redis
  • بادئات التخزين المؤقت
  • تكوين التخزين المؤقت المحلي
  • مستمعو Octane
• الاستخدام المتقدم
  • معالجة الإبطال اليدوي
  • تفريغ التخزين المؤقت المحلي
  • إدارة الاتصال
• التحسين
  • حدود طلبات العمال
  • التخزين المؤقت الانتقائي بالبادئات
  • اعتبارات الذاكرة
• الأنماط الشائعة
  • تكوين التطبيق
  • بيانات مرجعية يتم الوصول إليها بشكل متكرر
  • بديل العلامات في التخزين المؤقت
• القيود
  • وضع مجموعة Redis
• إرشادات الدعم
  • دعم مدفوع من المجتمع
  • الأخطاء، وأولوية الميزات
• الترخيص - MIT License

🔗المقدمة

Recall هي حزمة تخزين مؤقت عالية الأداء على جانب العميل لـ Redis ل Laravel. تستفيد من خاصية التخزين المؤقت على جانب العميل في Redis 6 مع إبطال تلقائي للحد من الرحلات الزمنية ووقت الاستجابة بشكل كبير. تم بناؤها خصيصًا لبيئات Laravel Octane، وتستخدم APCu أو Swoole Table كطبقة تخزين مؤقت محلية تبقى متزامنة مع Redis من خلال رسائل الإبطال.

عندما تسترجع قيمة من Redis، يقوم Recall بتخزينها محليًا. عندما تتغير تلك القيمة في Redis (من أي عميل)، يقوم Redis بإخطار Recall تلقائيًا لإبطال النسخة المحلية. هذا يمنحك سرعة التخزين المؤقت في الذاكرة مع ضمانات التناسق لـ Redis.

🔗الميزات الرئيسية

• الإبطال التلقائي: يقوم Redis بإخطار تطبيقك عند تغيير المفاتيح المخزنة مؤقتًا، مما يضمن تماسك التخزين المؤقت
• صفر إعدادات: يعمل جاهزًا مع إعدادات افتراضية معقولة
• تكامل Octane: تسخين الاتصال تلقائيًا، معالجة الإبطال بناءً على الطلب، والإغلاق اللائق
• دعم مزدوج للسائقين: APCu لجميع خوادم Octane، Swoole Table لبيئات Swoole/OpenSwoole
• تخزين مؤقت انتقائي: تكوين مفاتيح البادئة التي ترغب في تخزينها مؤقتًا محليًا
• حماية من حالات التنافس: تتبع الطلبات المعلقة يمنع تخزين بيانات قديمة أثناء عمليات الإبطال المتزامنة

🔗مثال

// تكوين Recall كسائق التخزين المؤقت الخاص بك
// config/cache.php
'stores' => [
    'recall' => [
        'driver' => 'recall',
    ],
],
 
// استخدمه كأي تخزين مؤقت في Laravel
use Illuminate\Support\Facades\Cache;
 
// المكالمة الأولى: تسترجع من Redis، تخزن محليًا
$user = Cache::store('recall')->get('user:1');
 
// المكالمات التالية: تقدم من APCu/Swoole Table المحلي (بمدة زمنية خلال ميكروثانية)
$user = Cache::store('recall')->get('user:1');
 
// عندما يتم تحديث user:1 في أي مكان، يقوم Redis بإخطار Recall للإبطال
Cache::store('recall')->put('user:1', $newUserData, 3600);
// يتم إبطال التخزين المؤقت المحلي تلقائيًا على جميع العمليات

🔗التثبيت

قم بتثبيت الحزمة عبر Composer:

composer require defectivecode/laravel-recall

🔗المتطلبات

• PHP >= 8.4
• Laravel 11.x أو 12.x
• Laravel Octane
• Redis 6.0+ (لدعم التخزين المؤقت على جانب العميل)
• ext-apcu أو ext-swoole (واحد على الأقل مطلوب للتخزين المؤقت المحلي)

🔗الاستخدام

🔗الإعداد الأساسي

1. أضف متجر Recall للتخزين المؤقت إلى config/cache.php:

'stores' => [
    // ... متاجر أخرى
 
    'recall' => [
        'driver' => 'recall',
    ],
],

2. استخدم متجر التخزين المؤقت في تطبيقك:

use Illuminate\Support\Facades\Cache;
 
// تخزين قيمة (تكتب إلى Redis)
Cache::store('recall')->put('key', 'value', 3600);
 
// استرجاع قيمة (المكالمة الأولى تضرب Redis، المكالمات التالية تستخدم التخزين المؤقت المحلي)
$value = Cache::store('recall')->get('key');
 
// حذف قيمة
Cache::store('recall')->forget('key');

🔗كيفية العمل

1. القراءة الأولى: يتم جلب القيمة من Redis وتخزينها في ذاكرة التخزين المؤقت المحلية APCu/Swoole Table
2. القراءات اللاحقة: يتم تقديم القيمة مباشرة من الذاكرة المحلية (أقل من مللي ثانية)
3. الكتابة في أي مكان: عندما يقوم أي عميل بتعديل المفتاح في Redis، يقوم Redis بإرسال رسالة إبطال
4. الإبطال التلقائي: يتلقى Recall الرسالة ويزيل المفتاح من التخزين المؤقت المحلي
5. القراءة التالية: يتم جلب قيمة جديدة من Redis وتخزينها مؤقتًا محليًا مرة أخرى

هذا النمط قوي بشكل خاص في بيئات Laravel Octane حيث تستمر العمليات بين الطلبات، مما يسمح بتراكم التخزين المؤقت المحلي وتقديم العديد من الطلبات من الذاكرة.

🔗تكامل Octane

يتكامل Recall تلقائيًا مع Laravel Octane عند توفره:

• بدء العمل: يؤسس اتصال إبطال لـ Redis (بدء دافئ)
• استلام الطلب: يعالج أي رسائل إبطال معلقة
• توقف العمل: يغلق الاتصالات بشكل لطيف

لا حاجة لإعدادات إضافية. التكامل تلقائي عند تثبيت Octane.

🔗التكوين

قم بنشر ملف التكوين:

php artisan vendor:publish --tag=recall-config

هذا ينشئ config/recall.php مع الخيارات التالية:

🔗التمكين/التعطيل

'enabled' => env('RECALL_ENABLED', true),

عند تعطيلها، يقوم Recall بالمرور مباشرة إلى Redis دون استخدام طبقة التخزين المؤقت المحلية. مفيد لأغراض التصحيح أو النشر التدريجي.

🔗متجر Redis

'redis_store' => env('RECALL_REDIS_STORE', 'redis'),

متجر التخزين المؤقت لـ Laravel لاستخدامه في عمليات Redis. يجب أن يشير إلى متجر Redis تم تكوينه في config/cache.php.

🔗بادئات التخزين المؤقت

'cache_prefixes' => [],

قم بتخزين المفاتيح فقط التي تطابق هذه البادئات محليًا. اتركها فارغة لتخزين جميع المفاتيح.

// قم بتخزين مفاتيح المستخدم والإعدادات محليًا فقط
'cache_prefixes' => ['users:', 'settings:', 'config:'],

هذا مفيد عندما يكون لديك مفاتيح ذات حجم كبير تتغير بشكل متكرر ولا ينبغي تخزينها محليًا.

🔗تكوين التخزين المؤقت المحلي

'local_cache' => [
    // السائق: "apcu" أو "swoole"
    'driver' => env('RECALL_LOCAL_DRIVER', 'apcu'),
 
    // بادئة لمفاتيح التخزين المؤقت المحلية
    'key_prefix' => env('RECALL_LOCAL_PREFIX', 'recall:'),
 
    // زمن انتهاء الصلاحية الافتراضي بالثواني (شبكة أمان إذا تم تفويت الإبطال)
    'default_ttl' => (int) env('RECALL_LOCAL_TTL', 3600),
 
    // حجم جدول Swoole (قوة 2، فقط لسائق swoole)
    'table_size' => (int) env('RECALL_SWOOLE_TABLE_SIZE', 65536),
 
    // الحد الأقصى من البايتات لكل قيمة في جدول Swoole (فقط لسائق swoole)
    'value_size' => (int) env('RECALL_SWOOLE_VALUE_SIZE', 8192),
],

سائق APCu (افتراضي)

يعمل سائق APCu مع جميع بيئات PHP وخوادم Octane (Swoole، RoadRunner، FrankenPHP). يخزن القيم المخبأة في ذاكرة مشتركة يمكن الوصول إليها من جميع عمليات PHP.

المتطلبات:

• ext-apcu مثبت ومفعل
• apc.enable_cli=1 في php.ini للاستخدام في CLI

سائق جدول Swoole

يستخدم سائق جدول Swoole جداول الذاكرة المشتركة الخاصة بـ Swoole، مما يوفر وصولاً متسقًا عبر التآفقات داخل نفس العامل. الأفضل لبيئات Swoole/OpenSwoole.

نصائح التكوين:

• table_size: يجب أن تكون قوة 2 (مثل 65536، 131072). يحدد الحد الأقصى لعدد الإدخالات.
• value_size: الحد الأقصى من البايتات للقيم المسلسلة. القيم الأكبر يتم تقطيعها بهدوء.

🔗مستمعو Octane

'listeners' => [
    // تسخين الاتصال عند بدء العامل (يقلل زمن استجابة الطلب الأول)
    'warm' => env('RECALL_LISTEN_WARM', true),
 
    // معالجة الإبطال خلال أحداث النقطة (استجابة أكبر، تكلفة إضافية طفيفة)
    'tick' => env('RECALL_LISTEN_TICK', false),
],

الاتصالات الدافئة

عندما يتم تمكينها، يقوم Recall بإقامة الاشتراك في الإبطال لـ Redis عند بدء عامل Octane. هذا يلغي زمن اتصال الطلب الأول.

معالجة النقاط

عندما يتم تمكينها، يقوم Recall بمعالجة رسائل الإبطال أثناء أحداث نقاط Octane بالإضافة إلى أحداث الطلب. هذا يوفر إبطال التخزين المؤقت المستجيب بشكل أكبر بتكلفة إضافية طفيفة.

🔗الاستخدام المتقدم

🔗معالجة الإبطال اليدوي

إذا كنت بحاجة إلى معالجة الإبطال يدويًا (على سبيل المثال، في عملية طويلة الأمد):

use DefectiveCode\Recall\RecallManager;
 
$manager = app(RecallManager::class);
$manager->processInvalidations();

🔗تفريغ التخزين المؤقت المحلي

لتفريغ التخزين المؤقت المحلي فقط دون التأثير على Redis:

use DefectiveCode\Recall\RecallManager;
 
$manager = app(RecallManager::class);
$manager->flushLocalCache();

🔗إدارة الاتصال

use DefectiveCode\Recall\RecallManager;
 
$manager = app(RecallManager::class);
 
// تحقق مما إذا كان الاشتراك في الإبطال متصلًا
if ($manager->isConnected()) {
    // ...
}
 
// قطع الاتصال يدويًا
$manager->disconnect();

🔗التحسين

🔗حدود طلبات العمال

يقوم Laravel Octane بدوران العمال بعد عدد قابل للتكوين من الطلبات لتجنب تسرب الذاكرة. عندما يدور عامل، يتم مسح التخزين المؤقت المحلي الخاص به. زيادة هذه الحدود تسمح بتمديد التخزين المؤقت المحلي لـ Recall، مما يحسن معدلات النجاح.

في config/octane.php:

// الافتراضي هو 500 طلبات قبل الدوران
'max_requests' => 10000,

قيم أعلى تعني تحسين استخدام التخزين المؤقت لكن تتطلب الثقة بأن تطبيقك لا يحتوي على تسرب للذاكرة. راقب استخدام ذاكرة العمال عند تعديل هذه القيمة.

🔗التخزين المؤقت الانتقائي بالبادئات

استخدم cache_prefixes للتحكم في المفاتيح المخزنة محليًا. هذا ذو قيمة عندما:

• المفاتيح الأكثر تقلبًا: بعض المفاتيح تتغير بشكل متكرر لدرجة أن التخزين المؤقت المحلي يوفر فوائد قليلة
• القيم الكبيرة: تقليل ضغط الذاكرة عن طريق تخزين المفاتيح الصغيرة الأكثر قراءة
• البيانات الحساسة: الاحتفاظ ببيانات معينة فقط في Redis لأسباب أمنية أو امتثال

// config/recall.php
'cache_prefixes' => [
    'users:',      // تخزين بيانات المستخدم محليًا
    'settings:',   // تخزين إعدادات التطبيق
    'products:',   // تخزين كتالوج المنتجات
],

المفاتيح التي لا تطابق هذه البادئات ستستمر في العمل لكن ستتجاوز التخزين المؤقت المحلي، مما يذهب مباشرة إلى Redis.

🔗اعتبارات الذاكرة

ذاكرة APCu

تشارك APCu الذاكرة عبر جميع عمليات PHP. قم بتكوين حد الذاكرة في php.ini:

; الافتراضي هو 32 ميغابايت، زيادة للاحتياجات التخزينية الأكبر
apc.shm_size = 128M

راقب استخدام APCu باستخدام apcu_cache_info():

$info = apcu_cache_info();
$memory = $info['mem_size']; // استخدام الذاكرة الحالي بالبايتات

تحديد حجم جدول Swoole

تمتلك جداول Swoole سعة ثابتة تم تكوينها عند الإنشاء. خطط لحجم التخزين المؤقت المتوقع لديك:

'local_cache' => [
    // الحد الأقصى من الإدخالات (يجب أن تكون قوة 2)
    'table_size' => 65536,  // 64K إدخالات
 
    // الحد الأقصى من حجم القيمة المسلسلة بالبايتات
    'value_size' => 8192,   // 8KB لكل قيمة
],

استخدام الذاكرة: table_size × (value_size + overhead). سيستخدم جدول يحتوي على 65536 إدخالًا وقيم 8KB حوالي 512MB.

🔗الأنماط الشائعة

🔗تكوين التطبيق

// تخزين ميزات وخيارات التخزين المؤقت
$features = Cache::store('recall')->remember('config:features', 3600, function () {
    return Feature::all()->pluck('enabled', 'name')->toArray();
});
 
// عندما تتغير الإعدادات، يحصل جميع العمال تلقائيًا على تحديثات

🔗بيانات مرجعية يتم الوصول إليها بشكل متكرر

// تخزين فئات المنتجات مؤقتًا
$categories = Cache::store('recall')->remember('categories:all', 3600, function () {
    return Category::with('children')->whereNull('parent_id')->get();
});
 
// تخزين أسعار صرف العملات مؤقتًا
$rates = Cache::store('recall')->remember('rates:exchange', 300, function () {
    return ExchangeRate::all()->pluck('rate', 'currency')->toArray();
});

🔗بديل العلامات في التخزين المؤقت

لا يدعم Recall علامات التخزين المؤقت، لكن يمكنك تحقيق وظيفة مماثلة مع البادئات:

// بدلاً من العلامات، استخدم بادئات متسقة
Cache::store('recall')->put("blog:posts:{$id}", $post, 3600);
Cache::store('recall')->put("blog:comments:{$postId}", $comments, 3600);
 
// قم بمسح جميع التخزين المؤقت المتعلق بالمدونة من خلال البادئة (يتطلب تنفيذًا يدويًا)
// أو اعتمد على الإبطال التلقائي عند تغيير البيانات

🔗القيود

🔗وضع مجموعة Redis

لا يدعم Recall وضع مجموعة Redis. تتطلب خيار REDIRECT في الأمر CLIENT TRACKING أن يكون اتصال البيانات واتصال المشترك في الإبطال على نفس عقدة Redis. في مجموعة، يتم توزيع المفاتيح عبر عدة عقد بناءً على تجزئة الفتحات، مما يجعل من المستحيل تلقي إبطال للمفاتيح المخزنة على عقد مختلفة.

لعمليات Redis المجمعة، ضع في اعتبارك:

• استخدام مثيل Redis واحد للبيانات المخزنة مؤقتًا التي تستفيد من التخزين المؤقت على جانب العميل
• استخدام مجموعة Redis للبيانات الأخرى بينما يتم الاحتفاظ بالبيانات المستقرة ذات القراءة المتكررة على وحدة مستقلة

🔗إرشادات الدعم

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

🔗دعم مدفوع من المجتمع

مشروعنا مفتوح المصدر مدعوم من مجتمعنا الرائع. إذا كانت لديك أسئلة أو تحتاج إلى مساعدة، فإن StackOverflow وغيرها من الموارد عبر الإنترنت هي أفضل الخيارات لديك.

🔗الأخطاء، وأولوية الميزات

حقيقة إدارة مشروع مفتوح المصدر تعني أنه لا يمكننا معالجة كل خطأ أو طلب ميزة مبلّغ عنه على الفور. نحن نحدد أولويات المشكلات بالترتيب التالي:

1. الأخطاء التي تؤثر على منتجاتنا المدفوعة

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

2. طلبات السحب من المجتمع

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

3. الدعم المالي

بالنسبة للمشكلات خارج الفئات المذكورة، يمكنك اختيار تمويل حلها. كل مشكلة مفتوحة مرتبطة بنموذج طلب يمكنك من خلاله المساهمة ماليًا. نحن نحدد أولويات هذه المشكلات بناءً على المبلغ المالي المقدم.

مساهمات المجتمع

تزدهر المصادر المفتوحة عندما يكون المجتمع نشطًا. حتى لو لم تكن تصلح الأخطاء، فكر في المساهمة من خلال تحسينات الكود، أو تحديث الوثائق، أو إنشاء دروس، أو بمساعدة الآخرين في قنوات المجتمع. نحن نشجع بشكل كبير الجميع، كمجتمع، على تقديم الدعم للعمل المفتوح المصدر.

لإعادة التأكيد، ستحظى DefectiveCode بأولوية الأخطاء استنادًا إلى كيفية تأثيرها على منتجاتنا المدفوعة، وطلبات سحب المجتمع، والدعم المالي الذي تم تلقيه للمشكلات.

🔗الترخيص - MIT License

حقوق الطبع والنشر © Defective Code, LLC. جميع الحقوق محفوظة

يتم منح الإذن بموجب هذا، مجانًا، لأي شخص يحصل على نسخة من هذا البرنامج وملفات الوثائق المرتبطة (الـ"برنامج")، للتعامل في البرنامج دون قيود، بما في ذلك بدون حصر الحقوق في الاستخدام والنسخ والتعديل والدمج والنشر والتوزيع والتراخيص الفرعية و/أو بيع نسخ من البرنامج، والسماح للأشخاص الذين تم تقديم البرنامج لهم بذلك، بشرط الالتزام بالشروط التالية:

يجب تضمين إشعار حقوق الطبع والنشر أعلاه وإشعار الإذن هذا في جميع النسخ أو الأجزاء الجوهرية من البرنامج.

يتم توفير البرنامج "كما هو"، دون أي ضمان من أي نوع، صريح أو ضمني، بما في ذلك ولكن لا تقتصر على ضمانات القابلية للتسويق، والملاءمة لغرض معين وعدم الانتهاك. في أي حال من الأحوال، لا يتحمل المؤلفون أو أصحاب حقوق الطبع المسؤولية عن أي مطالبة أو أضرار أو مسؤوليات أخرى، سواء كانت في إطار عقد أو ضرر أو خلاف ذلك، ناشئة عن أو نتيجة عن أو تتعلق بالبرنامج أو الاستخدام أو التعاملات الأخرى في البرنامج.