Comment réécrire jQuery Cookie et la bibliothèque core/js-cookie dans Drupal en utilisant le module js_cookie

Aperçu du chemin de migration

1) Drupal 8 → 9 : jQuery Cookie → core/js-cookie

Contexte historique : Drupal 9 a remplacé jQuery Cookie par js-cookie et a fourni des exemples de correspondance de code et de bibliothèques. https://www.drupal.org/node/3104677

# AVANT (Drupal 8 / début 9)
my_library:
  js:
    js/my_library.js: {}
  dependencies:
    - core/jquery
    - core/jquery.cookie
    - core/drupal

// AVANT (API jQuery Cookie)
(($, Drupal) => {
  Drupal.behaviors.myModule = {
    attach: () => {
      $.cookie('cutest', 'red panda');
      const myCookieValue = $.cookie('cutest');
      $.removeCookie('cutest');

      $.cookie.json = true;
      $.cookie('cutest', { animal: 'red panda' });
    },
  };
})(jQuery, Drupal);

Après (Drupal 9), vous dépendiez de core/js-cookie et utilisiez l’API Cookies.* : https://www.drupal.org/node/3104677

# APRÈS (Drupal 9)
my_library:
  js:
    js/my_library.js: {}
  dependencies:
    - core/drupal
    - core/js-cookie

// APRÈS (Drupal 9, API js-cookie)
((Drupal, Cookies) => {
  Drupal.behaviors.myModule = {
    attach: () => {
      Cookies.set('cutest', 'red panda');
      const myCookieValue = Cookies.get('cutest');
      Cookies.remove('cutest');

      Cookies.set('cutest', JSON.stringify({ animal: 'red panda' }));
      const cutest = JSON.parse(Cookies.get('cutest') || 'null');
    },
  };
})(Drupal, window.Cookies);

2) Drupal 10.1+ et 11 : core/js-cookie → js_cookie contribué

Puisque le cœur de Drupal a déprécié core/js-cookie dans Drupal 10.1 et l’a supprimé dans Drupal 11, vous devez le remplacer par la bibliothèque du module contrib JS Cookie : js_cookie/js-cookie. https://www.drupal.org/node/3322720

Composer

composer require drupal/js_cookie

Cela installe le module qui expose une bibliothèque d’assets Drupal pour le package amont js-cookie. https://www.drupal.org/project/js_cookie

Déclarer une dépendance module/thème (projets contrib/custom)

# my_module.info.yml (ou le .info.yml de votre thème)
name: My Module
type: module
core_version_requirement: ^10 || ^11
dependencies:
  - js_cookie:js_cookie

La page du projet précise explicitement d’ajouter js_cookie:js_cookie comme dépendance pour les modules contrib (et d’exiger drupal/js_cookie dans composer si votre module possède son propre composer.json). [4]

Changer la dépendance de votre bibliothèque

# Remplacez ceci (déprécié en 10.1, supprimé en 11)
# - core/js-cookie

# Par ceci (fourni par le module contrib)
my_library:
  js:
    js/my_library.js: {}
  dependencies:
    - core/drupal
    - js_cookie/js-cookie

Ce remplacement exact est celui recommandé dans le registre de changement du core. [2]

Code JavaScript

Votre code JS ne nécessite aucun changement si vous utilisiez déjà l’API Cookies de js-cookie — seule la dépendance de bibliothèque change. [2]

((Drupal, Cookies) => {
  Drupal.behaviors.myModule = {
    attach: () => {
      // Définir un cookie.
      Cookies.set('cutest', 'red panda', { path: '/', sameSite: 'Lax' });

      // Lire un cookie.
      const myCookieValue = Cookies.get('cutest');

      // Supprimer un cookie.
      Cookies.remove('cutest', { path: '/' });

      // Stocker/récupérer du JSON en toute sécurité.
      Cookies.set('cutest', JSON.stringify({ animal: 'red panda' }));
      const cutestRaw = Cookies.get('cutest');
      const cutest = cutestRaw ? JSON.parse(cutestRaw) : null;
    },
  };
})(Drupal, window.Cookies);

Astuce : js-cookie est conforme à la RFC 6265 et encode les valeurs différemment de l’ancien jQuery Cookie, surtout pour le JSON. Le registre de changement de Drupal 9 détaille ces différences. https://www.drupal.org/node/3104677

Exemples issus de l’écosystème

• Le module EU Cookie Compliance a suivi la dépréciation de core/js-cookie et des correctifs ont été proposés pour passer à js_cookie/js-cookie. https://www.drupal.org/project/eu_cookie_compliance/issues/3380490
• Divers projets contrib ont créé des issues pour remplacer jQuery Cookie par js-cookie, puis pour traiter la dépréciation de core/js-cookie. https://www.drupal.org/project/quicktabs/issues/3298649
  https://www.drupal.org/project/fpa/issues/3505122

Recettes de mise à niveau étape par étape

A) De jQuery Cookie directement à js_cookie/js-cookie (Drupal 10+)

1. Supprimez les dépendances core/jquery et core/jquery.cookie de votre fichier .libraries.yml. https://www.drupal.org/node/3104677
2. Ajoutez js_cookie:js_cookie aux dépendances de votre .info.yml (modules contrib/custom). https://www.drupal.org/project/js_cookie
3. Modifiez votre dépendance de bibliothèque vers js_cookie/js-cookie. https://www.drupal.org/project/js_cookie
4. Réécrivez votre JS de $.cookie vers Cookies.* comme montré plus haut. https://www.drupal.org/node/3104677

B) De core/js-cookie à js_cookie/js-cookie (Drupal 10.1 → 11)

1. Installez le module : composer require drupal/js_cookie. https://www.drupal.org/project/js_cookie
2. (Contrib) Ajoutez js_cookie:js_cookie dans .info.yml ; il suffit d’activer le module. https://www.drupal.org/project/js_cookie
3. Dans .libraries.yml, remplacez core/js-cookie par js_cookie/js-cookie. https://www.drupal.org/node/3322720
4. Conservez votre code JS existant basé sur Cookies.*. Aucun changement fonctionnel requis. https://www.drupal.org/node/3322720

Pièges et bonnes pratiques

• Préparation pour Drupal 11 : core/js-cookie est supprimé dans Drupal 11 — assurez-vous que toutes les dépendances pointent vers js_cookie/js-cookie. https://www.drupal.org/node/3322720
• Vie privée/CDN : La page du projet js_cookie documente comment éviter de charger js-cookie via un CDN (protection des données). Préférez les assets locaux. https://www.drupal.org/project/js_cookie
• Encodage & JSON : Ne dépendez pas du comportement JSON implicite. Utilisez explicitement JSON.stringify et JSON.parse comme montré plus haut. https://www.drupal.org/node/3104677
• Patches réels : Consultez les files d’issues (ex. EU Cookie Compliance) pour repérer les modèles de mise à jour. https://www.drupal.org/project/eu_cookie_compliance/issues/3380490