Porter des plugins WordPress vers EmDash

Cette skill mappe les concepts WordPress à leurs équivalents EmDash pour le portage de plugins. Pour les détails généraux de création de plugins (structure, definePlugin(), hooks, stockage, interface admin, etc.), consultez la skill creating-plugins.

Approche de migration

1. Comprendre le plugin — Ce qu'il fait, pas comment
2. Identifier les concepts — Types de contenu, pages admin, hooks, shortcodes
3. Mapper vers EmDash — Utiliser les tableaux ci-dessous
4. Implémenter en TypeScript — Partant de zéro, pas une portage ligne par ligne. Consultez la skill creating-plugins pour les détails d'implémentation.
5. Tester le comportement — Même résultat, implémentation différente

Mappage des concepts

Contenu et données

Configuration du site

Menus de navigation

Taxonomies

Widgets et barres latérales

Interface admin

Hooks

Sortie frontale

Stockage de plugin

Modèles spécifiques au portage

Ces modèles couvrent des concepts spécifiques à WordPress qui n'ont pas de mappage 1:1 direct. Pour les modèles généraux de plugin (définir hooks, stockage, routes, interface admin), consultez la skill creating-plugins.

Shortcodes → Blocs Portable Text

Les shortcodes WordPress ([youtube id="xxx"]) deviennent des types de bloc personnalisé Portable Text. Les données de bloc remplacent les attributs du shortcode, et un composant Astro remplace la fonction de rendu du shortcode. C'est une fonction approuvée uniquement.

// WordPress
add_shortcode('youtube', function($atts) {
    return '<iframe src="https://youtube.com/embed/' . $atts['id'] . '"></iframe>';
});

// EmDash — déclaration de type de bloc dans definePlugin()
admin: {
    portableTextBlocks: [{
        type: "youtube",
        label: "YouTube Video",
        icon: "video",
        fields: [
            { type: "text_input", action_id: "id", label: "YouTube URL" },
            { type: "text_input", action_id: "title", label: "Title" },
        ],
    }],
}

// EmDash — composant Astro pour rendu
// src/astro/YouTube.astro
const { id, title } = Astro.props.node;
const videoId = id?.match(/(?:v=|youtu\.be\/)([^&]+)/)?.[1] ?? id;
// <iframe src={`https://youtube-nocookie.com/embed/${videoId}`} ... />

Options API → KV de plugin

L'API get_option/update_option de WordPress mappe vers le stockage KV du plugin. La différence clé : les options WordPress sont globales, le KV d'EmDash est automatiquement scoped au plugin.

// WordPress
$count = get_option("myplugin_post_count", 0);
update_option("myplugin_post_count", $count + 1);
delete_option("myplugin_temp_data");

// EmDash — pas de préfixe nécessaire, automatiquement scoped
const count = (await ctx.kv.get<number>("post-count")) ?? 0;
await ctx.kv.set("post-count", count + 1);
await ctx.kv.delete("temp-data");

Tables de base de données personnalisées → Collections de stockage

Les plugins WordPress qui créent des tables personnalisées avec $wpdb->query("CREATE TABLE ...") doivent utiliser les collections de stockage EmDash à la place. Aucune migration nécessaire — déclarez le schéma dans definePlugin() et il est automatiquement provisionné.

// WordPress
$wpdb->insert($table, ['form_id' => $id, 'data' => json_encode($data), 'created_at' => current_time('mysql')]);
$results = $wpdb->get_results("SELECT * FROM $table WHERE form_id = '$id' ORDER BY created_at DESC LIMIT 50");

// EmDash — déclaré dans definePlugin()
storage: {
    submissions: {
        indexes: ["formId", "createdAt", ["formId", "createdAt"]],
    },
},

// Dans un hook ou gestionnaire de route
await ctx.storage.submissions!.put(entryId, { formId, data, createdAt: new Date().toISOString() });
const result = await ctx.storage.submissions!.query({
    where: { formId },
    orderBy: { createdAt: "desc" },
    limit: 50,
});

Ensemencement de données (remplace contenu de démarrage, configuration de thème)

Les plugins WordPress qui appellent wp_insert_term(), register_nav_menu(), ou insèrent du contenu par défaut à l'activation doivent utiliser un fichier seed :

{
    "version": "1",
    "settings": { "title": "My Site", "tagline": "Welcome" },
    "taxonomies": [
        {
            "name": "category",
            "label": "Categories",
            "hierarchical": true,
            "collections": ["posts"],
            "terms": [
                { "slug": "news", "label": "News" },
                { "slug": "tutorials", "label": "Tutorials" }
            ]
        }
    ],
    "menus": [
        {
            "name": "primary",
            "label": "Primary Navigation",
            "items": [
                { "type": "custom", "label": "Home", "url": "/" },
                { "type": "page", "ref": "about", "collection": "pages" }
            ]
        }
    ],
    "redirects": [
        { "source": "/?p=123", "destination": "/about" },
        { "source": "/old-contact", "destination": "/contact", "type": 301 }
    ]
}

Enregistrez dans .emdash/seed.json (ou connectez via package.json#emdash.seed) ; le runtime l'applique au prochain démarrage initial quand la base de données est vide.

Utilisez redirects pour les URLs WordPress héritées qui reçoivent encore du trafic après migration.

Interrogation de contenu (remplace WP_Query)

// WordPress
$query = new WP_Query(['post_type' => 'post', 'category_name' => 'tech', 'posts_per_page' => 10]);

// EmDash — dans frontmatter de composant Astro
import { getEmDashCollection, getEntryTerms } from "emdash";
const { entries } = await getEmDashCollection("posts", {
    where: { category: "technology" },
    limit: 10,
});

Menus (remplace wp_nav_menu)

// WordPress
wp_nav_menu(['theme_location' => 'primary']);

// EmDash — dans composant Astro
import { getMenu } from "emdash";
const nav = await getMenu("primary");
// nav.items[].label, nav.items[].url, nav.items[].children

Zones de widgets (remplace dynamic_sidebar)

// WordPress
dynamic_sidebar("sidebar-1");

// EmDash — dans composant Astro
import { getWidgetArea } from "emdash";
const sidebar = await getWidgetArea("sidebar");
// sidebar.widgets[].type: "content" | "menu" | "component"

Signaux d'alerte (Nécessite décision humaine)

Signaler ces éléments pour révision — ils peuvent nécessiter des décisions architecturales :

1. Intégration profonde WP — Hooks dans les fonctionnalités du noyau WP absentes d'EmDash
2. Dépendances de thème — Suppose une structure de thème spécifique
3. Fonctionnalités multisite — Non supportées
4. WP_Query complexe — Les requêtes de métadonnées peuvent nécessiter une implémentation personnalisée
5. SQL direct — Le schéma diffère, utiliser Kysely ou stockage de plugin
6. Abus de session/transient — Nécessite une couche de cache appropriée
7. Vérifications de capacité utilisateur — Réviser mappage de rôles (futur)
8. Buffering ob_start() — Modèle PHP, repenser pour le streaming
9. Tâches Cron — wp_schedule_event() n'a pas d'équivalent direct ; nécessite cron de plateforme

Format de sortie

Lors du portage d'un plugin, fournir :

1. Analyse — Ce que fait le plugin WP (concepts, pas code)
2. Mappage de concepts — Quels concepts WP mappent vers quelles fonctionnalités EmDash
3. Code de plugin — src/descriptor.ts et src/index.ts (utiliser skill creating-plugins pour structure)
4. Données seed — Si le plugin a besoin de taxonomies/menus/widgets par défaut
5. Composants Astro — Pour sortie frontale
6. Signaux d'alerte — Tout ce qui nécessite une décision humaine