Chapitre 4.4 — Structure des fichiers & du code

⏱️ TL;DR — Une installation WordPress se divise en trois zones : le cœur (wp-admin/, wp-includes/ — on n’y touche jamais), les fichiers racine (wp-config.php, index.php, .htaccess), et surtout wp-content/ — votre territoire : themes/, plugins/, uploads/, mu-plugins/. Règle d’or : tout votre code custom vit dans wp-content (un thème ou un plugin), jamais dans le cœur. Modifier le cœur (« core hack ») serait écrasé à la moindre mise à jour.

🎯 Objectifs

• Cartographier l’arborescence d’une installation WordPress.
• Identifier où votre code doit (et ne doit pas) vivre.
• Comprendre le rôle de wp-content et de ses sous-dossiers.
• Connaître les must-use plugins et la règle « ne jamais hacker le cœur ».

1. Vue d’ensemble

/ (racine web)
├── index.php            ← point d'entrée (ne pas toucher)
├── wp-config.php        ← configuration + secrets (ch. 4.2)
├── wp-load.php, wp-settings.php, wp-blog-header.php  ← démarrage
├── .htaccess            ← réécriture d'URL (Apache)
├── wp-admin/            ← LE CŒUR (back-office) — ne pas toucher
├── wp-includes/         ← LE CŒUR (fonctions, classes) — ne pas toucher
└── wp-content/          ← VOTRE TERRITOIRE
    ├── themes/          ← les thèmes (un dossier par thème)
    ├── plugins/         ← les plugins (un dossier ou fichier par plugin)
    ├── mu-plugins/      ← "must-use" plugins (chargés automatiquement)
    ├── uploads/         ← les médias (par année/mois)
    └── languages/       ← fichiers de traduction

2. Le cœur : regarder, ne pas toucher

wp-admin/ et wp-includes/ contiennent le code de WordPress lui-même. Vous pouvez (et devez) le lire — c’est une doc vivante — mais jamais le modifier :

⚠️ Piège — le « core hack ». Modifier un fichier du cœur pour « juste changer un petit truc » est écrasé à la prochaine mise à jour de WordPress, et peut créer des failles de sécurité. Tout se fait via des hooks (Partie 5) dans un thème ou un plugin. Si vous êtes tenté de toucher au cœur, c’est qu’il existe un hook, un filtre ou une meilleure approche — cherchez-le.

Le cœur est aussi votre meilleure documentation : pour comprendre comment une fonction marche, on lit sa source dans wp-includes/ (ou sur le dépôt GitHub WordPress/wordpress-develop).

3. wp-content : votre territoire

💡 Pour un dev React — Mentalement : le cœur = les node_modules d’un framework (on lit, on ne modifie pas). wp-content = votre dossier src/. Un thème = la couche présentation, un plugin = une feature/module. Les mu-plugins ressemblent à du code d’amorçage global qui s’exécute sans qu’on ait à « l’activer ». Et uploads/ = un dossier d’assets uploadés (comme un bucket local) — jamais dans Git.

4. Thème ou plugin : où mettre mon code ?

Règle simple (approfondie en Partie 7) :

• Code lié à l’apparence, au rendu, au design → thème.
• Code lié à une fonctionnalité qui doit survivre à un changement de thème (un type de contenu, une intégration, un réglage métier) → plugin.

⚠️ Piège — tout mettre dans functions.php du thème. Le débutant colle toute sa logique dans le functions.php du thème. Problème : changez de thème, tout disparaît. Un Custom Post Type « Produit » ou une intégration d’API doit être un plugin (indépendant du thème). Le functions.php est pour ce qui est vraiment propre à l’apparence.

Pour des snippets « site-specific » qui ne justifient pas un vrai plugin, on crée souvent un petit plugin « site custom » (ou un mu-plugin) plutôt que de polluer le thème.

5. Ce qu’on versionne (et pas)

• On versionne : votre thème et vos plugins custom (leur dossier), la config d’environnement (.wp-env.json, composer.json, package.json).
• On ne versionne pas : le cœur WordPress (dépendance), wp-content/uploads/, wp-config.php (secrets), node_modules/, les plugins/thèmes tiers (gérés via un manifeste ou l’installeur).

Beaucoup d’équipes versionnent seulement wp-content (ou juste leurs plugins/thèmes) et gèrent le cœur + les dépendances via Composer (avec wpackagist) — une pratique pro qui rapproche WordPress d’un workflow de dev moderne.

✏️ Exercices

1. Un collègue veut « corriger un bug » en éditant un fichier de wp-includes/. Que lui répondez-vous ?
2. Où placez-vous un Custom Post Type « Événement » censé rester même si le client change de thème ? Pourquoi ?
3. Citez trois éléments à ne pas committer dans Git pour un projet WordPress.

🧠 Quiz de révision

Chapitre suivant : Débogage : WP_DEBUG, logs & Xdebug.