Une perspective d’ingénierie

La gestion du contenu évolue. L’approche CMS monolithique traditionnelle cède la place à des architectures sans tête, où la gestion et la présentation du contenu sont découplés. Ce changement apporte de nouveaux défis, en particulier lorsque les organisations doivent migrer des systèmes hérités vers des plateformes modernes sans tête.

Notre équipe a rencontré ce scénario lors de la création d’un chemin de migration de Drupal à StoryBlok. Ces systèmes gèrent l’architecture de contenu en tout à fait différemment – Drupal utilise un modèle de champ d’entité intégré à PHP, tandis que StoryBlok utilise une structure flexible d’histoires et de blocs conçu pour la livraison sans tête.

Si vous avez juste besoin d’utiliser un script pour faire une migration de contenu simple – mais extensible – de Drupal à StoryBlok, j’ai déjà partagé instructions étape par étape sur la façon de le télécharger et de l’utiliser dans un article précédent. Si vous êtes intéressé par le processus de création d’un tel script afin que vous puissiez écrire votre propre version (éventuellement) meilleure, restez ici!

Nous avons observé que les développeurs ont parfois du mal avec les transferts de contenu manuel et les scripts personnalisés lors de la migration entre CMSS. Cela nous a amenés à développer et à partager notre approche de migration, que nous avons mis en œuvre en tant qu’outil open-source que d’autres pourraient utiliser comme référence pour leurs besoins de migration.

Notre solution combine deux composants principaux: une commande DRUSH personnalisée qui gère la cartographie et la transformation de contenu et un nouveau client PHP pour l’API de gestion de StoryBlok qui exploite les fonctionnalités linguistiques modernes pour une meilleure expérience de développeur.

Nous explorerons les décisions d’ingénierie derrière le développement de cet outil, en examinant nos choix architecturaux et comment nous avons abordé des défis de migration du monde réel en utilisant des pratiques de PHP modernes.

Note: Vous pouvez trouver le code source complet de l’outil de migration dans le repo exportateur de Drupal.

Planification de l’architecture de migration

Le voyage de Drupal à StoryBlok présente des défis architecturaux uniques. La différence fondamentale réside dans la façon dont ces systèmes conceptualisent le contenu: Drupal Structures Content en tant qu’entités avec des champs, tandis que StoryBlok utilise une approche basée sur des composants avec des histoires et des blocs.

Analyse initiale des exigences

Un outil de migration réussi doit comprendre intimement les deux systèmes. Le modèle de contenu de Drupal s’appuie fortement sur son API d’entité, le stockage du contenu en tant que collections de champ structurées au sein des entités. Un article typique de Drupal peut contenir des champs pour le titre, le contenu corporel, les images et les taxonomies. Bloken revanche, structure le contenu comme des histoires contenant des blocs, des composants réutilisables qui peuvent être imbriqués et disposés de manière flexible. C’est une différence subtile qui a façonné nos exigences techniques, en particulier autour de la cartographie du contenu et de la transformation des données, mais en fin de compte, il est facile de voir les relations entre les deux modèles de contenu.

Contraintes techniques

Au début du développement, nous avons identifié plusieurs contraintes clés. API de gestion de StoryBlok applique des limites de taux qui affectent la rapidité avec laquelle nous pouvons transférer le contenu. Les actifs multimédias doivent d’abord être téléchargés puis liés. La récupération des erreurs devient essentielle lors de la migration de centaines de pièces de contenu.

Le tout nouveau Client PHP de l’API de gestion gère ces contraintes à travers des mécanismes de réchauffement intégrés et la validation de la réponse, donc en écrivant un script de migration, nous n’avons pas à nous en soucier.

Sélection d’outils

Nous avons choisi Dush comme interface de ligne de commande pour plusieurs raisons. Tout d’abord, il est profondément intégré au processus bootstrap de Drupal, offrant un accès direct à l’API de l’entité et aux données sur le terrain. Deuxièmement, les développeurs de Drupal connaissent déjà ses conventions, ce qui rend notre outil plus accessible.

La décision de développer un nouveau Client de l’API de gestion est venu de notre expérience avec l’évolution de PHP depuis que nous avons développé le premier client PHP, et notre objectif de fournir aux développeurs un outil dédié pour cette API spécifique qui offrait un DX amélioré et un ensemble de fonctionnalités sur mesure.

Ce travail de base a façonné la façon dont nous avons approché le flux de travail de migration.

Les blocs de construction: un nouveau client API de gestion

Un outil de migration de contenu interagit fortement avec l’API de gestion de StoryBlok et MDASH, créant des histoires, téléchargeant des actifs et gestion des balises. Chaque opération doit être fiable et prévisible. Notre tout nouveau client simplifie ces interactions via des appels de méthode intuitifs: le client gère l’authentification, la mise en forme de demande et l’analyse de réponse dans les coulisses, permettant aux développeurs de se concentrer sur les opérations de contenu plutôt que sur la mécanique des API.

Conception de fiabilité

Les migrations de contenu impliquent souvent des centaines d’appels API. Notre client comprend des mécanismes intégrés pour gérer les scénarios communs comme la limitation du taux et les demandes d’échec. Le modèle de gestion de la réponse fournit des commentaires clairs sur le succès de l’opération: un enregistreur peut être injecté dans la classe client, comme nous l’avons fait en utilisant le Drush Logger dans notre script de migration à partir de Drupal.

Amélioration de l’expérience de développement

Au-delà des opérations de base de l’API, le client réduit la charge cognitive grâce à des modèles prévisibles. Les objets de données fournissent un moyen structuré de préparer le contenu pour StoryBlok: ce modèle valide les données au début du processus, en prenant des problèmes potentiels avant d’atteindre l’API.

Concevoir le flux de travail de migration

Passer de la structure basée sur les entités de Drupal à StoryBlok modèle de composant Planification minutieuse du flux de travail de migration requise. Notre objectif était de créer un processus qui serait à la fois fiable et adaptable à différentes structures de contenu.

Structure de commandement

La migration exploite requête d’entité système pour extraire le contenu systématiquement. Par défaut, Les chèques d’accès ont été désactivés (une décision commerciale réversible) pour se concentrer uniquement sur la migration nœuds publiés.

Étapes clés et idées

• Champs de texte

  • Effort minimal requis: des valeurs comme value() cartographié directement sur les champs StoryBlok.
  • Le texte riche ne posait aucun défis encoding, permettant des transferts 1: 1 simples.

• Manipulation d’images

  1. Télécharger: Des actifs ont été envoyés dans un seau AWS S3.
  2. Lien: StoryBlok API Asset upload() Méthode Retour a object_idsimplifiant la cartographie du champ.
  3. Attribuer: L’identité d’actifs et le nom de fichier ont été attachés à l’histoire.

• Gestion des balises

  • Les tags extraits de Drupal ont été pré-créés via StoryBlok API de jour (facultatif mais assure la cohérence).
  • Lorsque vous attribuez des balises aux histoires, StoryBlok crée automatiquement des manquants, rationalisant le processus.

Pourquoi les flux de travail mis en scène sont importants

La migration évite les références brisées en hiérarchisant les dépendances (actifs d’abord, tags Suivant, contenu dernier). Alors que les balises pré-création ajoutent le contrôle, les équipes peuvent adapter cette logique, par exemple, en laissant les balises de génération automatique de StoryBlok pour gagner du temps.

La flexibilité est essentielle: chaque décision (vérifications d’accès, flux de travail de balises) peut être ajustée pour s’aligner sur les objectifs du projet.

Défis de mise en œuvre du monde réel

La migration du contenu entre Drupal et StoryBlok présente des défis que vous, en tant qu’implémenteur, pouvez rencontrer.

Par exemple, lorsqu’il s’agit de grands ensembles de données, vous pouvez constater que les sites Drupal avec des milliers de nœuds peuvent rapidement atteindre les limites de taux appliquées par l’API de gestion de StoryBlok. Dans de tels cas, un mécanisme de lots pour vos demandes mérite d’être considéré. Au lieu de traiter chaque nœud à la fois, vous pouvez traiter un sous-ensemble d’enregistrements, attendre une courte période, puis continuer.

Alternativement, vous pouvez utiliser le createBulk Méthode de l’API de l’histoire dans l’API de gestion, qui vous permet de gérer plusieurs créations d’histoire avec la gestion et les tentatives de limite de taux intégrées. Un autre obstacle potentiel est la conversion de types de champs complexes, en particulier lorsque les structures imbriquées ou les champs de paragraphe de Drupal doivent être cartographiés sur le modèle plus flexible basé sur des blocs de StoryBlok.

Une approche consiste d’abord à analyser la profondeur et la structure de nidification de la teneur en Drupal, puis aplatissent les éléments profondément imbriqués dans des composants réutilisables de StoryBlok tout en maintenant la hiérarchie correcte. Par exemple, un paragraph Le champ avec des supports et du texte intégrés peut être divisé en blocs dans StoryBlok, chaque composant représentant une section logique de contenu. En structurant les données de cette façon avant la migration, vous vous assurez que le contenu reste modifiable et correctement structuré dans le nouveau système.

La cohérence des données est un autre aspect que vous devez gérer attentivement. Lors de la migration de centaines de dossiers, les échecs partiels sont toujours risqués. Une approche pour gérer ceci consiste à enregistrer des informations détaillées pour chaque opération de migration et à implémenter un mécanisme de réessayer pour les opérations défaillantes.

Par exemple, envelopper les appels d’API dans un try-catch Les erreurs de blocage et de journalisation peuvent être un moyen pratique de s’assurer qu’aucun enregistrement n’est supprimé silencieusement. Lorsque vous traitez de champs tels que des termes ou étiquettes de taxonomie créés à la volée dans StoryBlok, vous pouvez rencontrer des problèmes de duplication. Une bonne pratique consiste à effectuer un chèque avant de créer une nouvelle balise. Cela pourrait impliquer de maintenir un cache local de balises créées précédemment et de vérifier contre eux avant d’envoyer une demande de création à l’API.

Il en va de même pour les images; Un chèque pourrait vous assurer de ne pas télécharger le même actif deux fois.

Leçons apprises et attendant avec impatience

UN Client API dédié Pour StoryBlok, les interactions ont rationalisé, abstraction de la complexité backend tout en améliorant la maintenabilité du code. Utilisation précoce de objets de données structurées Préparer le contenu s’est avéré critique, permettant la détection d’erreur préventive et la réduction des défaillances de l’API.

Nous avons également rencontré certains défis et voyons la place à l’amélioration:

• Problèmes d’encodage en texte riche (par exemple, entités HTML) ont été résolues avec une étape de prétraitement
• Goulot d’étranglement des performances avec de grandes textes / images Optimisation de la mémoire requise et manipulation de la demande raffinée

Les améliorations pourraient inclure le soutien à Drupal Layout Buildercouches de validation avancées ou systèmes de gestion des actifs dynamiques.

💡 Pour des plongées plus profondes dans notre client API de gestion ou les stratégies de migration, contactez via Discordeexplorez le REPO Client PHPou connectez-vous avec moi sur Mastodonte. Les commentaires et les contributions sont les bienvenus!

(IL)