Raccourcis : Contenu - rubriques - sous rubriques
EN FR
La page correspondant à la dernière version stable est consultable dans le Manuel Jelix 1.6

Jelix contient une couche d'abstraction aux bases de données de type key-value, moins complexes que les bases de données SQL.

Vous avez jKVDb dont vous pouvez récupérer un connecteur à une base de données clé-valeur. Tout comme jDb, il y a des profiles définis dans un fichier profiles.ini.php (Voir le chapitre sur l'utilisation de ce fichier profiles.ini.php), où vous pouvez définir des paramètres pour vous connecter à ces bases de données.

jKVDb fonctionne avec des "drivers" pour accéder aux données clé-valeur. Jelix fourni des drivers pour de simples fichiers (file et file2), memcache, redis, et ... sql. Voir plus bas pour plus d'informations sur ces drivers.

Configuration

Comme jDb, profiles.ini.php contient des sections, une pour chaque base de données à laquelle vous voulez accéder. Chaque section contient au moins un paramètre driver donnant le nom du driver à utiliser Des autres paramètres peuvent être définis en fonction du driver sélectionné.

Le type de connexion à indiquer dans les noms des sections de profiles.ini.php est jkvdb.

Accéder à une base de données

Vous devez appeler jKVDb::getConnection(), en donnant éventuellement un profile (sinon le profile par défaut est utilisé). Vous récupérez un objet qui hérite de jKVDriver.

Avec cet objet, vous pouvez accéder au contenu de la base clé-valeur, et aussi le modifier. Voici des méthodes que vous pouvez appeler:

  • get($key): pour récupérer un valeur correspondant à une clé donnée. Renvoi null si la clé n'existe pas.
  • set($key, $value): pour stocker un nouvelle valeur ou modifier une valeur existante.
  • insert($key, $value): pour stocker une nouvelle valeur. Retourne false si clé existe déjà.
  • replace($key,$value): pour changer la valeur correspondant à une clé. Si la clé n'existe pas, false est retourné.
  • delete($key): supprime la clé-valeur correspondante.
  • flush(): supprime toutes les clés.
  • append($key, $value): Concatène une chaine de caractères à la fin d'une valeur.
  • prepend($key, $value): Concatène une chaine de caractères au début d'une valeur.

Autres opérations particulières

Certains drivers peuvent implémenter des méthodes additionnelles en fonction des possibilités de la base. Un exemple de ces interfaces est jIKVttl, où les valeurs ont un temps de vie limité.

Pour stocker de telles valeurs, vous devez appeler la méthode setWithTtl($key, $value, $ttl), où $ttl est une valeur en secondes.

Vous pouvez aussi appeler la méthode garbage pour effacer toutes les clés que ne sont plus valides.

Drivers

memcache

Il utilise l'API memcache de PHP (à ne pas confondre avec l'autre API: memcached). Il supporte uniquement la version 3.0.1 de memcache ou inférieur.

Dans le profil, vous devez indiquer un host et un port, ou plusieurs host/port. Voici un exemple avec un simple serveur:


[jkvdb:mymemcacheserver]
driver=memcache
host=localhost

Ou avec plusieurs serveurs:


[jkvdb:mymemcacheserver]
driver=memcache

host=memcache_server1:11211;memcache_server2:11212

; ou:
host[]=memcache_server1:11211
host[]=memcache_server2:11212

Vous pouvez aussi définir le paramètre compress=1, pour que les valeurs soient compressées lors du stockage.

Ce driver supporte l'interface jIKVttl.

redis

Ce driver permet d'accéder à une base de données Redis.

Deux plugins sont disponibles :

  • "redis_ext", fourni avec Jelix, se base sur l'API de l'extension PHP redis (plugin introduit dans Jelix 1.6.14)
  • "redis_php", disponible séparément via le paquet Composer "jelix/php-redis-plugin", utilise une classe pure PHP (PhpRedis) pour communiquer avec la base Redis. (ce plugin était nommé "redis" avant Jelix 1.6.14)

Paramètres possibles :

Pour les configurer, il suffit d'indiquer un host et un paramètre port. Exemple :


[jkvdb:myredis]
driver=redis_ext
host = localhost
port = 6379

Ce driver supporte l'interface jIKVttl.

Depuis Jelix 1.6.8, il prend également en charge les paramètres suivants :

  • db : le numéro de base de donnée redis (0 par défaut)
  • key_prefix : un prefix qui sera ajouté sur chaque clé indiquée
  • key_prefix_flush_method : méthode de suppression des clés quand on indique un prefixe.

Si vous indiquez un préfixe pour les clés, alors toutes les clés que vous indiquez seront préfixées par le préfixe en question dans la base Redis.

De même, le vidage du cache ne concernera que les clés commençant par ce préfixe. Cependant, à cause de l'implementation d'une telle fonction dans Redis, cela peut être très gourmand en temps, et rendre votre application trop lente.

Diverses méthodes sont implémentées dans le plugin pour supprimer les clés, et sont indiquées dans le paramètre key_prefix_flush_method :

  • direct : les clés sont supprimées directement. Comportement par défaut. Mais à n'utiliser que si vous savez que votre base Redis ne contient pas beaucoup de clés.
  • jkvdbredisworker : la suppression des clés sera faite de manière asynchrone par un worker ou un cron.
  • event : si les deux autres méthodes ne vous conviennent pas, il est alors de votre responsabilité d'implémenter le processus (asynchrone de préférence !) qui vous convient. Un évènement jKvDbRedisFlushKeyPrefix est émis par le plugin, avec le nom du profile et le prefixe des clés à supprimer. à vous d'implémenter un listener sur cet évènement qui appellera votre processus de suppression.

Fonctionnement de la suppression asynchrone des clés à prefixes :

Le plugin stocke les prefixes des clés à supprimer dans une liste qui a pour clé jkvdbredisdelkeys dans Redis. Un worker ou un cron doit alors dépiler régulièrement cette liste de préfix et supprimer les clés correspondantes.

Vous avez un exemple de worker dans lib/jelix/core-modules/jelix/Command/RedisKvdbDeletionWorker.php. Vous pouvez le lancer au moyen de systemd/sysinit/supervisord par exemple. La commande sera alors php monappli/console.php jkvdb:redis:delete <profile><profile> est le nom du profile jkvdb concerné. La commande scrute en permanence la liste jkvdbredisdelkeys dans Redis et efface les clés correspondantes aux prefixes de cette liste. Pour l'arrêter, un <CTRL+C> (sur linux) suffira si vous le lancez vous même en ligne de commande.

db

Il permet d'utiliser une table SQL pour stocker les clé-valeurs. Pour le configurer, vous devez indiquer:

  • table: le nom de la table à utiliser.
  • dbprofile: le nom du profil jDb à utiliser pour accéder à la base SQL.

La table doit contenir trois champs, avec des noms et des types de champs spécifiques. Voici un script SQL pour créer de telles tables:


CREATE TABLE mykvdbtable (
k_key VARCHAR( 50 ) NOT NULL ,
k_value longblob NOT NULL ,
k_expire DATETIME NOT NULL ,
PRIMARY KEY (k_key)
);

Vous pouvez avoir plusieurs tables, pour éviter d'avoir des conflits entre les modules qui utilisent jKVDb.

Ce driver supporte l'interface jIKVttl

file

Il charge les valeurs dans des fichiers. Chaque fichier contient une valeur. Configuration:

  • storage_dir: le répertoire où les fichiers sont placés. Peut contenir des raccourcis comme "var:" ou "temp:", le répertoire par défaut est var/kvfiles/.
  • file_locking: false pour désactiver le "lock" de fichiers. True par défaut.
  • automatic_cleaning_factor: donne la fréquence avec laquelle il faut nettoyer les fichiers trop vieux. 0 signifie jamais, 1 signifie pour chaque accès, plus élevé signifie une fréquence moins élevée..
  • directory_level: si vous savez que vous aurez des milliers de valeurs, vous pouvez augmenter le nombre de niveau de répertoires: 2 par defaut.
  • directory_umask: le umask des répertoires créés. 0700 par défaut.
  • file_umask: le umask des fichiers créés. 0600 par défaut.

Ce driver supporte l'interface jIKVttl.

file2

C'est un driver similaire au driver "file", mais en moins sophistiqué. Pas de paramètres de configuration et les fichiers sont stockés dans temp/filekv/.

Vous ne devez l'utiliser que pour des valeurs temporaires.