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

• Introduction
  • Caractéristiques Clés
  • Exemple
• Installation
  • Exigences
• Utilisation
  • Configuration de Base
  • Comment Cela Fonctionne
  • Intégration Octane
• Configuration
  • Activer/Désactiver
  • Store Redis
  • Préfixes de Cache
  • Configuration du Cache Local
  • Écouteurs Octane
• Utilisation Avancée
  • Traitement Manuel des Invalidations
  • Vidage du Cache Local
  • Gestion des Connexions
• Optimisation
  • Limites de Demande des Workers
  • Caching Sélectif avec Préfixes
  • Considérations Mémoire
• Modèles Communs
  • Configuration de l'Application
  • Données de Référence Accédées Fréquemment
  • Alternative aux Tags de Cache
• Limitations
  • Mode Cluster Redis
• Directives de Support
  • Support Axé sur la Communauté
  • Bugs et Priorisation des Fonctionnalités
• Licence - Licence MIT

🔗Introduction

Recall est un package de caching côté client Redis haute performance pour Laravel. Il exploite la fonctionnalité de caching côté client de Redis 6 avec invalidation automatique pour réduire de manière significative les allers-retours Redis et la latence. Construit spécifiquement pour les environnements Laravel Octane, il utilise APCu ou Swoole Table comme couche de cache local qui reste synchronisée avec Redis grâce à des messages d'invalidation.

Lorsque vous récupérez une valeur à partir de Redis, Recall la stocke localement. Lorsque cette valeur change dans Redis (de n'importe quel client), Redis notifie automatiquement Recall pour invalider la copie locale. Cela vous donne la rapidité du caching en mémoire avec les garanties de cohérence de Redis.

🔗Caractéristiques Clés

• Invalidation Automatique : Redis notifie votre application lorsque les clés mises en cache changent, assurant la cohérence du cache
• Zéro Configuration : Fonctionne directement avec des paramètres par défaut sensés
• Intégration Octane : Réchauffement automatique de la connexion, traitement d'invalidation basé sur la demande, et arrêt gracieux
• Support des Drivers Doubles : APCu pour tous les serveurs Octane, Swoole Table pour les environnements Swoole/OpenSwoole
• Caching Sélectif : Configurez quels préfixes de clés mettre en cache localement
• Protection Contre les Conditions de Compétition : Le suivi des demandes en attente empêche le caching de données obsolètes lors d'invalidations concurrentes

🔗Exemple

// Configurez recall comme votre driver de cache
// config/cache.php
'stores' => [
    'recall' => [
        'driver' => 'recall',
    ],
],
 
// Utilisez-le comme n'importe quel cache Laravel
use Illuminate\Support\Facades\Cache;
 
// Premier appel : récupère dans Redis, stocke localement
$user = Cache::store('recall')->get('user:1');
 
// Appels suivants : servis depuis le cache local APCu/Swoole Table (microsecondes)
$user = Cache::store('recall')->get('user:1');
 
// Lorsque user:1 est mis à jour quelque part, Redis notifie Recall pour invalider
Cache::store('recall')->put('user:1', $newUserData, 3600);
// Le cache local est automatiquement invalidé sur tous les workers

🔗Installation

Installez le package via Composer :

composer require defectivecode/laravel-recall

🔗Exigences

• PHP >= 8.4
• Laravel 11.x ou 12.x
• Laravel Octane
• Redis 6.0+ (pour le support du caching côté client)
• ext-apcu OU ext-swoole (au moins un requis pour le cache local)

🔗Utilisation

🔗Configuration de Base

1. Ajoutez le store de cache Recall à votre config/cache.php :

'stores' => [
    // ... autres stores
 
    'recall' => [
        'driver' => 'recall',
    ],
],

2. Utilisez le store de cache dans votre application :

use Illuminate\Support\Facades\Cache;
 
// Stockez une valeur (écrit dans Redis)
Cache::store('recall')->put('key', 'value', 3600);
 
// Récupérez une valeur (le premier appel touche Redis, les appels suivants utilisent le cache local)
$value = Cache::store('recall')->get('key');
 
// Supprimez une valeur
Cache::store('recall')->forget('key');

🔗Comment Cela Fonctionne

1. Première Lecture : La valeur est récupérée depuis Redis et stockée dans le cache local APCu/Swoole Table
2. Lectures Suivantes : La valeur est servie directement depuis la mémoire locale (sub-millisecondes)
3. Écriture Partout : Lorsque n'importe quel client modifie la clé dans Redis, Redis envoie un message d'invalidation
4. Invalidation Automatique : Recall reçoit le message et supprime la clé du cache local
5. Prochaine Lecture : Une nouvelle valeur est récupérée depuis Redis et mise en cache localement à nouveau

Ce modèle est particulièrement puissant dans les environnements Laravel Octane où les workers persistent entre les demandes, permettant au cache local de s'accumuler et de servir de nombreuses demandes depuis la mémoire.

🔗Intégration Octane

Recall s'intègre automatiquement avec Laravel Octane lorsqu'il est disponible :

• Démarrage du Worker : Établit la connexion d'invalidation Redis (démarrage à chaud)
• Demande Reçue : Traite tous les messages d'invalidation en attente
• Arrêt du Worker : Ferme gracieusement les connexions

Aucune configuration supplémentaire n'est requise. L'intégration est automatique lorsque Octane est installé.

🔗Configuration

Publiez le fichier de configuration :

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

Cela crée config/recall.php avec les options suivantes :

🔗Activer/Désactiver

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

Lorsque désactivé, Recall passe directement à Redis sans utiliser la couche de cache locale. Utile pour le débogage ou le déploiement progressif.

🔗Store Redis

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

Le store de cache Laravel à utiliser pour les opérations Redis. Cela doit faire référence à un store Redis configuré dans votre config/cache.php.

🔗Préfixes de Cache

'cache_prefixes' => [],

Ne mettez en cache que les clés correspondant à ces préfixes localement. Laissez vide pour mettre en cache toutes les clés.

// Ne mettez en cache localement que les clés utilisateur et paramètres
'cache_prefixes' => ['users:', 'settings:', 'config:'],

Ceci est utile lorsque vous avez des clés à fort volume qui changent fréquemment et qui ne devraient pas être mises en cache localement.

🔗Configuration du Cache Local

'local_cache' => [
    // Driver : "apcu" ou "swoole"
    'driver' => env('RECALL_LOCAL_DRIVER', 'apcu'),
 
    // Préfixe pour les clés de cache local
    'key_prefix' => env('RECALL_LOCAL_PREFIX', 'recall:'),
 
    // TTL par défaut en secondes (filet de sécurité si l'invalidation est manquée)
    'default_ttl' => (int) env('RECALL_LOCAL_TTL', 3600),
 
    // Taille de la Table Swoole (puissance de 2, seulement pour le driver swoole)
    'table_size' => (int) env('RECALL_SWOOLE_TABLE_SIZE', 65536),
 
    // Taille max en octets par valeur dans la Table Swoole (seulement pour le driver swoole)
    'value_size' => (int) env('RECALL_SWOOLE_VALUE_SIZE', 8192),
],

Driver APCu (Par Défaut)

Le driver APCu fonctionne avec tous les environnements PHP et serveurs Octane (Swoole, RoadRunner, FrankenPHP). Il stocke les valeurs mises en cache dans la mémoire partagée accessible à tous les processus PHP.

Exigences :

• ext-apcu installé et activé
• apc.enable_cli=1 dans php.ini pour l'utilisation en CLI

Driver Swoole Table

Le driver Swoole Table utilise les tables de mémoire partagée de Swoole, fournissant un accès cohérent à travers les coroutines dans le même worker. Meilleur pour les environnements Swoole/OpenSwoole.

Conseils de configuration :

• table_size : Doit être une puissance de 2 (par exemple, 65536, 131072). Détermine le nombre maximal d'entrées.
• value_size : Nombre maximal d'octets pour les valeurs sérialisées. Les valeurs plus grandes sont tronquées en silence.

🔗Écouteurs Octane

'listeners' => [
    // Réchauffe la connexion au démarrage du worker (réduit la latence de la première demande)
    'warm' => env('RECALL_LISTEN_WARM', true),
 
    // Traite les invalidations lors des événements d'intervalle (plus réactif, léger surcoût)
    'tick' => env('RECALL_LISTEN_TICK', false),
],

Connexions Chauffées

Lorsque activé, Recall établit l'abonnement à l'invalidation Redis lorsque le worker Octane démarre. Cela élimine la latence de connexion sur la première demande.

Traitement de Tick

Lorsque activé, Recall traite les messages d'invalidation lors des événements de tick Octane en plus des événements de demande. Cela fournit une invalidation de cache plus réactive au prix d'un léger surcoût supplémentaire.

🔗Utilisation Avancée

🔗Traitement Manuel des Invalidations

Si vous devez traiter manuellement des invalidations (par exemple, dans un processus de longue durée) :

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

🔗Vidage du Cache Local

Pour vider uniquement le cache local sans affecter Redis :

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

🔗Gestion des Connexions

use DefectiveCode\Recall\RecallManager;
 
$manager = app(RecallManager::class);
 
// Vérifiez si l'abonnement à l'invalidation est connecté
if ($manager->isConnected()) {
    // ...
}
 
// Déconnexion manuelle
$manager->disconnect();

🔗Optimisation

🔗Limites de Demande des Workers

Laravel Octane fait tourner les workers après un nombre configurable de demandes pour éviter les fuites de mémoire. Lorsque un worker tourne, son cache local est vidé. Augmenter cette limite permet au cache local de Recall de persister plus longtemps, améliorant les taux de succès du cache.

Dans votre config/octane.php :

// La valeur par défaut est de 500 demandes avant de tourner
'max_requests' => 10000,

Des valeurs plus élevées signifient une meilleure utilisation du cache mais exigent la confiance que votre application n'a pas de fuites de mémoire. Surveillez l'utilisation de la mémoire de votre worker lors de l'ajustement de cette valeur.

🔗Caching Sélectif avec Préfixes

Utilisez cache_prefixes pour contrôler quelles clés sont mises en cache localement. Ceci est précieux lorsque :

• Clés à fort changement : Certaines clés changent si fréquemment que le caching local apporte peu de bénéfice
• Grandes valeurs : Réduisez la pression de mémoire en ne mettant en cache que des clés plus petites, lues fréquemment
• Données sensibles : Gardez certaines données uniquement dans Redis pour des raisons de sécurité ou de conformité

// config/recall.php
'cache_prefixes' => [
    'users:',      // Mettre en cache les données utilisateur localement
    'settings:',   // Mettre en cache les paramètres de l'application
    'products:',   // Mettre en cache le catalogue de produits
],

Les clés ne correspondant pas à ces préfixes fonctionneront toujours mais contourneront le caching local, allant directement à Redis.

🔗Considérations Mémoire

Mémoire APCu

APCu partage la mémoire entre tous les processus PHP. Configurez la limite de mémoire dans php.ini :

; La valeur par défaut est de 32Mo, augmentez pour des besoins de cache plus importants
apc.shm_size = 128M

Surveillez l'utilisation d'APCu avec apcu_cache_info() :

$info = apcu_cache_info();
$memory = $info['mem_size']; // Utilisation actuelle de la mémoire en octets

Dimensionnement de la Table Swoole

Les Tables Swoole ont une capacité fixe configurée à la création. Planifiez pour votre taille de cache attendue :

'local_cache' => [
    // Nombre maximal d'entrées (doit être une puissance de 2)
    'table_size' => 65536,  // 64K entrées
 
    // Taille maximale des valeurs sérialisées en octets
    'value_size' => 8192,   // 8Ko par valeur
],

Utilisation de la mémoire : table_size × (value_size + overhead). Une table avec 65536 entrées et des valeurs de 8Ko utilise environ 512Mo.

🔗Modèles Communs

🔗Configuration de l'Application

// Caches les features et paramètres
$features = Cache::store('recall')->remember('config:features', 3600, function () {
    return Feature::all()->pluck('enabled', 'name')->toArray();
});
 
// Lorsque les paramètres changent, tous les workers reçoivent automatiquement des mises à jour

🔗Données de Référence Accédées Fréquemment

// Cache les catégories de produits
$categories = Cache::store('recall')->remember('categories:all', 3600, function () {
    return Category::with('children')->whereNull('parent_id')->get();
});
 
// Cache les taux de change
$rates = Cache::store('recall')->remember('rates:exchange', 300, function () {
    return ExchangeRate::all()->pluck('rate', 'currency')->toArray();
});

🔗Alternative aux Tags de Cache

Recall ne supporte pas les tags de cache, mais vous pouvez obtenir une fonctionnalité similaire avec des préfixes :

// Au lieu des tags, utilisez des préfixes cohérents
Cache::store('recall')->put("blog:posts:{$id}", $post, 3600);
Cache::store('recall')->put("blog:comments:{$postId}", $comments, 3600);
 
// Effacez tout le cache relatif au blog par préfixe (nécessite une implémentation manuelle)
// Ou comptez sur l'invalidation automatique lorsque les données changent

🔗Limitations

🔗Mode Cluster Redis

Recall ne prend pas en charge le mode Cluster Redis. L'option REDIRECT de la commande CLIENT TRACKING nécessite que la connexion de données et la connexion du souscripteur d'invalidation soient sur le même nœud Redis. Dans un cluster, les clés sont distribuées sur plusieurs nœuds en fonction des slots de hachage, ce qui rend impossible la réception des invalidation pour les clés stockées sur différents nœuds.

Pour les déploiements Redis en cluster, envisagez :

• D'utiliser une seule instance Redis pour les données mises en cache bénéficiant du caching côté client
• D'utiliser Redis Cluster pour d'autres données tout en gardant des données stables, lues fréquemment sur une instance autonome.

🔗Directives de Support

Merci d'avoir choisi notre paquet open source ! Veuillez prendre un moment pour consulter ces directives de support. Elles vous aideront à tirer le meilleur parti de notre projet.

🔗Support Axé sur la Communauté

Notre projet open-source est alimenté par notre incroyable communauté. Si vous avez des questions ou avez besoin d'aide, StackOverflow et d'autres ressources en ligne sont vos meilleures options.

🔗Bugs et Priorisation des Fonctionnalités

La réalité de la gestion d'un projet open-source signifie que nous ne pouvons pas traiter tous les bugs ou demandes de fonctionnalités immédiatement. Nous priorisons les problèmes dans l'ordre suivant :

1. Bugs Affectant Nos Produits Payants

Les bugs qui impactent nos produits payants seront toujours notre priorité absolue. Dans certains cas, nous ne traiterons peut-être que les bugs qui nous affectent directement.

2. Demandes de Tirage de la Communauté

Si vous avez identifié un bug et avez une solution, veuillez soumettre une demande de tirage. Après les problèmes affectant nos produits, nous accordons la prochaine priorité la plus élevée à ces corrections pilotées par la communauté. Une fois examinée et approuvée, nous fusionnerons votre solution et créditerons votre contribution.

3. Soutien Financier

Pour les problèmes en dehors des catégories mentionnées, vous pouvez choisir de financer leur résolution. Chaque problème ouvert est lié à un bon de commande où vous pouvez contribuer financièrement. Nous priorisons ces problèmes en fonction du montant du financement fourni.

Contributions de la Communauté

L'open-source prospère lorsque sa communauté est active. Même si vous ne réparez pas de bugs, envisagez de contribuer par des améliorations de code, des mises à jour de documentation, des tutoriels, ou en aidant les autres dans les canaux communautaires. Nous encourageons vivement tout le monde, en tant que communauté, à aider à soutenir le travail open-source.

Pour réitérer, DefectiveCode priorisera les bugs en fonction de leur impact sur nos produits payants, des demandes de tirage de la communauté, et du soutien financier reçu pour les problèmes.

🔗Licence - Licence MIT

Copyright © Defective Code, LLC. Tous droits réservés

La permission est par la présente accordée, gratuitement, à toute personne obtenant une copie de ce logiciel et des fichiers de documentation associés (le "Logiciel"), de traiter le Logiciel sans restriction, y compris sans limitation les droits d'utiliser, de copier, de modifier, de fusionner, de publier, de distribuer, de sous-licencier, et/ou de vendre des copies du Logiciel, et de permettre aux personnes à qui le Logiciel est fourni de le faire, sous réserve des conditions suivantes :

L'avertissement de copyright ci-dessus et cet avis de permission doivent être inclus dans toutes les copies ou portions substantielles du Logiciel.

LE LOGICIEL EST FOURNI "EN L'ÉTAT", SANS GARANTIE D'AUCUNE SORTE, EXPRESSE OU TACITE, Y COMPRIS MAIS SANS S'Y LIMITER AUX GARANTIES DE COMMERCIALITÉ, D'ADAPTATION À UN OBJECTIF PARTICULIER ET DE NON CONTREFAÇON. EN AUCUN CAS, LES AUTEURS OU DÉTENTEURS DE DROITS D'AUTEUR NE POURRONT ÊTRE TENUS RESPONSABLES DE TOUTE RECLAMATION, DOMMAGE OU AUTRE RESPONSABILITÉ, QUE CE SOIT DANS LE CADRE D'UN CONTRAT, DUN DÉLIT OU AUTRE, DÉCOULANT DE, OU EN RELATION AVEC LE LOGICIEL OU L'UTILISATION OU AUTRES TRANSACTIONS DANS LE LOGICIEL.