Chapitre 12.3 — Pièges courants & FAQ

« Ça ne marche pas et je ne comprends pas pourquoi. » 9 fois sur 10, la réponse est ici. Classé par domaine, du point de vue d’un dev venant de React/Next.js.

🔴 Caches & « ça ne s’applique pas »

1. Mon changement de code ne s’applique pas. → Purgez les caches (page cache, object cache/Redis, OPcache), et le cache navigateur. En dev, désactivez le cache. (Parties 4.5 / 11.2.)

2. Ma nouvelle capability / mon CPT / ma route REST n’existe pas. → db/*… non : côté WordPress, il faut souvent flush les rewrite rules (CPT en 404) et purger les caches ; pour un plugin, vérifier qu’il est activé et que le hook est bien sur init.

3. Mon CPT renvoie 404 sur ses URLs. → flush_rewrite_rules() à l’activation (ou Réglages → Permaliens → Enregistrer). Jamais à chaque requête. (Partie 5.9.)

🔴 Hooks

4. Mon filtre vide le titre/contenu. → Un filtre doit retourner la valeur ; return oublié = null. (Partie 5.2.)

5. Mon callback ne reçoit pas tous ses arguments. → Déclarez le nombre d’arguments : add_action('save_post','cb',10,3). (Partie 5.2.)

6. J’ai enregistré mon CPT trop tôt/tard. → Sur init, pas au chargement du fichier ni dans le rendu. (Partie 5.1.)

🔴 Requêtes & base

7. J’ai remplacé le domaine avec un sed sur le dump SQL, tout est cassé. → Données sérialisées corrompues. Utilisez wp search-replace. (Partie 2.6.)

8. posts_per_page => -1 fait planter le site. → Charge tout en mémoire. Paginez/limitez. (Partie 5.5.)

9. J’écris wp_posts en dur et ça casse ailleurs. → Le préfixe varie : $wpdb->posts / $wpdb->prefix. (Partie 5.6.)

10. Requête N+1, page lente. → Query Monitor ; jointure/_embed/préchargement. (Parties 5.5 / 11.2.)

🔴 Sécurité

11. Un utilisateur accède aux données d’un autre. → IDOR : testez la capability avec l’objet (current_user_can('edit_post', $id)). (Partie 7.7.)

12. Faille XSS : du HTML utilisateur s’exécute. → Échappez à la sortie (esc_html/esc_attr/esc_url) ; wp_kses_post pour du HTML riche. (Partie 7.7.)

13. Mon action mutante marche sans jeton. → Ajoutez un nonce (anti-CSRF). (Partie 7.7.)

14. Injection SQL. → $wpdb->prepare(), jamais de concaténation. (Partie 5.6.)

🔴 Thèmes & plugins

15. Mon code disparaît quand je change de thème. → Une fonctionnalité (CPT, intégration) va dans un plugin, pas dans functions.php. (Partie 4.4 / 6.7.)

16. Ma modif du thème acheté a sauté après une mise à jour. → Utilisez un thème enfant. (Partie 6.3.)

17. Mes styles/scripts ne se chargent pas. → Passez par l’enqueue (jamais <script> en dur), et vérifiez wp_head()/wp_footer() dans le thème. (Partie 6.1 / 6.4.)

🔴 Blocs (Gutenberg)

18. « Ce bloc contient un contenu inattendu ». → Invalidation : le save a changé. Pour du contenu variable, faites un bloc dynamique (render PHP). (Parties 3.1 / 8.5.)

19. Ma meta n’apparaît pas dans le bloc / le store. → register_post_meta(..., 'show_in_rest' => true). (Parties 7.4 / 8.7.)

20. Mes supports (couleur/alignement) ne s’appliquent pas sur le front. → get_block_wrapper_attributes() dans render.php. (Partie 8.5.)

21. L’UI de mon bloc reste en anglais. → wp_set_script_translations() + fichiers .json. (Partie 11.7.)

🔴 REST / headless

22. Mon CPT n’apparaît pas dans /wp-json. → show_in_rest => true. (Partie 7.3.)

23. Mon token/clé fuit dans le bundle client. → Variable serveur (pas NEXT_PUBLIC_) ; auth côté serveur. Révoquez le secret exposé. (Partie 9.2.)

24. CORS bloque mon appel WordPress depuis le navigateur. → N’appelez pas WordPress depuis le client : passez par votre backend Next.js. (Partie 9.2/9.5.)

25. Le HTML de content.rendered casse/expose une faille. → Assainir (DOMPurify) avant dangerouslySetInnerHTML ; réécrire les URLs. (Partie 9.5.)

🔴 WooCommerce

26. WP_Query('shop_order') ne trouve pas les commandes. → HPOS : wc_get_orders() / WC_Order, et déclarer la compat. (Partie 10.1/10.4.)

27. woocommerce_checkout_fields n’a aucun effet. → Checkout en blocs : utilisez l’API des champs additionnels. (Partie 10.3.)

28. Une commande est marquée payée mais ne l’est pas. → Se fier au webhook signé, pas au retour navigateur. (Partie 10.5.)

FAQ franche

WordPress est-il « headless » ? Pas par défaut, mais sa REST API (Partie 9) et WPGraphQL le permettent. Réfléchissez au coût (Partie 9.7).

Faut-il Composer pour un plugin ? Pas pour le plugin lui-même (installé par zip/git). Composer sert à l’outillage (PHPCS, PHPStan, PHPUnit) et à gérer le cœur/plugins tiers en pro. (Partie 4.4 / 11.4.)

Y a-t-il du hot reload ? Pour le JS des blocs, wp-scripts start (watch). Pour le PHP, non façon Vite ; cycle sauvegarde → reload (+ purge de cache). (Partie 8.2.)

Puis-je écrire un plugin en autre chose que PHP ? Le serveur est en PHP (imposé). Le front est en JS/React (blocs, Partie 8) ; le headless en Next.js (Partie 9).

Puis-je modifier le cœur ? Non (« core hack » écrasé à chaque update). Tout via hooks/plugins/thèmes. (Partie 4.4.)

Thème classique ou bloc (FSE) ? Bloc/FSE pour du neuf (déclaratif, WYSIWYG) ; classique pour maintenir l’existant ou un contrôle PHP fin. (Partie 6.)

REST ou GraphQL ? REST (natif) par défaut ; WPGraphQL pour un front riche en relations/typage. (Partie 9.4.)

Headless ou pas ? Pas par principe. Site standard → thème bloc. Besoin front custom/perf/multi-canal + équipe Next → headless (ou îlots React). (Partie 9.7.)

Comment gagner de l’argent avec un plugin GPL ? Support/updates, version Pro (freemium), SaaS hébergé, sur-mesure. (Parties 1.3 / 13.)

La règle d’or, répétée

Ça ne marche pas ? → 1. Purgez les caches (dont object cache). 2. WP_DEBUG activé → lisez debug.log. 3. Flush rewrite si CPT/route. 4. Query Monitor pour voir requêtes/hooks/erreurs. 5. Cherchez en anglais (glossaire ch. 12.1).

Chapitre suivant : Ressources.