Comment utiliser UserData API de Drupal ?

Vous avez certainement déjà eu besoin de stocker des données relatives à un utilisateur, et vous avez sûrement pensé à ajouter un champs à l’entité User. Mais saviez-vous qu’il existe une API Drupal qui permet d’associer des données à un utilisateur, et ce de façon extrêmement simple et rapide ?

Dans cette article, je vous explique le fonctionnement de UserData API de Drupal, et quand et comment elle peut être utilisée pour créer des expériences utilisateur plus personnalisées et plus engageantes.

Qu’est-ce que UserData API ?

UserData API est une fonctionnalité fournie avec le module User. Son but est de stocker certaines informations relatives à un utilisateur. Son fonctionnement est similaire à une API, mais à la seule différence que UserData API est propre à un environnement.

Techniquement, UserData API est une table en base de données qui possède 4 colonnes :

• uid
• module : le module auquel on associe la donnée
• name
• value

Les trois premières colonnes sont des clés primaires. Ce qui signifie qu’il n’existe qu’un seul triplet (uid,module,name). Autrement dit, étant donné un uid, un module et un name, il ne peut y avoir qu’une seule valeur associée à ce triplet.

Pour quelle utilisation ?

Vous l’aurez compris, cette API peut être utilisée pour stocker n’importe quelle donnée utilisateur, mais elle est particulièrement pertinente pour des données dynamiques et/ou complexes.

Complexe car elle vous permet de stocker des données sérialisées. Ainsi, plutôt que de créer un type de contenu Drupal (node) et d’ajouter un champs "entity reference" au sein de l’entité User, ici, vous pouvez stocker votre objet PHP. Ce qui vous permettra de vous affranchir de la rigidité des entités Drupal.

Dynamique car le fait d’ajouter, de consulter ou de supprimer cette donnée est très largement moins coûteux que d’interagir avec les entités Drupal. En effet, en plus de la place qu’occupe un type de contenu dans la base de données, il ne faut pas oublier tous les mécanismes sous-jacents qui sont invoqués à la manipulation des nodes, tels que les hooks, controlAccessHandler, le cache, etc.

Comment UserData API fonctionne ?

L’utilisation de cette API est simple et très bien documentée au sein du fichier web/core/modules/user/src/UserDataInterface.php

UserData API contient 3 méthodes :

La méthode set() qui permet d’insérer une donnée

/**
 * Stores data for a user account.
 *
 *@paramstring$module
*   The name of the module the data is associated with.
 *@paramint$uid
*   The user account ID the data is associated with.
 *@paramstring$name
*   The name of the data key.
 *@parammixed$value
*   The value to store. Non-scalar values are serialized automatically.
 */
public function set($module, $uid, $name, $value);

Avec cette méthode, vous avez certainement remarqué que nous devons obligatoirement renseigner le nom du module à la donnée. Si la donnée n’est pas une donnée scalaire (donc un objet), alors elle sera sérialisée automatiquement.

Attention, aucune vérification n’est faite sur l’uid ainsi que sur le nom du module. Il faudra donc veiller à la validité de vos données.

La méthode get() qui permet de récupérer une ou plusieurs valeurs

/**
 * Returns data stored for a user account.
 *
 *@paramstring$module
*   The name of the module the data is associated with.
 *@paramint$uid
*   (optional) The user account ID the data is associated with.
 *@paramstring$name
*   (optional) The name of the data key.
 *
 *@returnmixed|array
 *   The requested user account data, depending on the arguments passed:
 *   - For $module, $name, and $uid, the stored value is returned, or NULL if
 *     no value was found.
 *   - For $module and $uid, an associative array is returned that contains
 *     the stored data name/value pairs.
 *   - For $module and $name, an associative array is returned whose keys are
 *     user IDs and whose values contain the stored values.
 *   - For $module only, an associative array is returned that contains all
 *     existing data for $module in all user accounts, keyed first by user ID
 *     and $name second.
 */
public function get($module, $uid = NULL, $name = NULL);

Cette méthode permet ainsi de récupérer une valeur donnée selon le nom du module, l’id de l’utilisateur et le nom de la variable recherchée (clés).

Comme expliqué ci-dessus en commentaire, vous pouvez jouer avec les paramètres facultatifs selon votre besoin :

• Si $uid n’est pas renseigné, alors nous obtenons un tableau associatif dont les clés sont les $uid (uid ⇒ value)
• Si $name n’est pas renseigné, alors nous récupérons toutes les valeurs pour un $uid et un $module donnée via un tableau associatif (name ⇒ value)
• Enfin, si ni $uid et $name ne sont renseignés (il ne reste que $module), alors nous obtenons toutes les valeurs de tous les $uid, via un tableau associatif (uid ⇒ [name ⇒ value])

La méthode delete() qui permet de supprimer une ou plusieurs données

/**
 * Deletes data stored for a user account.
 *
 *@paramstring|array$module
*   (optional) The name of the module the data is associated with. Can also
 *   be an array to delete the data of multiple modules.
 *@paramint|array$uid
*   (optional) The user account ID the data is associated with. If omitted,
 *   all data for $module is deleted. Can also be an array of IDs to delete
 *   the data of multiple user accounts.
 *@paramstring$name
*   (optional) The name of the data key. If omitted, all data associated with
 *   $module and $uid is deleted.
 */
public function delete($module = NULL, $uid = NULL, $name = NULL) {
	$query = $this->connection->delete('users_data');
    // Cast scalars to array so we can consistently use an IN condition.
  if (isset($module)) {
     $query->condition('module', (array) $module, 'IN');
  }
  if (isset($uid)) {
    $query->condition('uid', (array) $uid, 'IN');
  }
  if (isset($name)) {
    $query->condition('name', (array) $name, 'IN');
  }
  $query->execute();
}

Là encore, comme expliqué en commentaire, vous pouvez jouer avec les paramètres facultatifs. J’ai laissé, volontairement, le code de la fonction car ce dernier offre une deuxième lecture par rapport aux commentaires : si un paramètre est renseigné, alors on applique le filtre correspondant. Ainsi, si $module est renseigné, la suppression concernera le(s) donnée(s) spécifiques à ce module; si $uid est renseigné, alors la suppression concernera le(s) donnée(s) relatifs à l’utilisateur uid, et enfin si name est renseigné, alors un filtre sera appliqué sur le nom de la variable. La combinaison de ces trois paramètres offre ainsi 8 possibilités !

Dans quels cas j’ai utilisé UserData API ?

À plusieurs reprises, j’ai utilisé le UserData API. Voici quelques exemples :

> Exemple 1 – Lors de la mise en place d’un système de notifications Web push pour les utilisateurs connectés. Je devais stocker un objet json propre à l’utilisateur, qui me servait à envoyer une notification à la bonne personne.

> Exemple 2 – Pour un système de mise en favoris de contenu. J’ai stocké grâce à cette API un tableau dont la clé́ était l’url du contenu mis en favoris, et en valeur un tableau contenant le titre et la catégorie du contenu. Ainsi en consultant un contenu (view mode full), je pouvais savoir très rapidement si ce contenu avait été mis en favoris ou non.

> Exemple 3 – Sur un site internet gérant des évènements, la nouvelle fonctionnalité était de pouvoir s’inscrire à des évènements dont la gestion des inscriptions se faisaient sur un service externe. Lorsque l’utilisateur s’inscrivait sur le site, je le notifiais au service externe, qui me renvoyait un numéro de dossier. Ce numéro de dossier étant propre à l’utilisateur, je ne pouvais donc pas en faire un champs au niveau de l’entité Évènement. La solution la plus évidente aurait été de créer une entité « réservation », mais pour diverses raisons nous voulions une solution rapide et simple. J’ai donc utilisé UserData API. Cela nous a permis de créer une sorte de table de jointure, stockant pour un utilisateur et un évènement donné, le numéro de dossier relatif au dossier ouvert au sein du service externe.

En conclusion, UserData API de Drupal est une solution qui nous permet de récupérer et de stocker rapidement et simplement des données personnalisées pour un utilisateur. Maintenant, c'est à vous de tester ! 😉

Crédit photo : oatawa