WordPress

WordPress est un socle qu’on ne modifie pas, et deux endroits où l’on écrit. Savoir lequel des deux est la première compétence du cours.

Les trois zones

wp-admin/      # le cœur : l'administration
wp-includes/   # le cœur : les fonctions de WordPress
wp-content/    # LE VÔTRE
├── themes/    #   l'apparence et les gabarits
├── plugins/   #   les fonctionnalités
└── uploads/   #   les fichiers envoyés
wp-config.php  # la configuration (base de données, clefs, débogage)

Thème ou greffon : la règle de partage

Les deux peuvent tout faire techniquement. La règle n’est pas technique, elle est de survie :

La question qui tranche : « si je change de thème demain, dois-je perdre ceci ? ». Un type de contenu déclaré dans un thème disparaît avec lui — les articles restent en base, mais plus rien ne sait les afficher, ni même qu’ils existent. C’est l’erreur la plus coûteuse du développement WordPress, et elle ne se voit que le jour du changement de thème.

Le bac à sable de cette page

Tout ce que vous lirez ici a tourné sur une installation réelle. Les versions, relevées le 16 août 2026 :

WordPress 7.0.4 (fr_FR)
WP-CLI 2.12.0
PHP 8.4.22

WordPress 7.0.4 exige PHP 7.4 et MySQL 5.5.5 au minimum (source : api.wordpress.org/core/version-check). Le fil rouge est un seul objet, construit d’un bout à l’autre : un type de contenu recette.

C’est LE mécanisme de WordPress. Tout le reste en découle. Le cœur appelle, à des moments nommés, toutes les fonctions qu’on a inscrites — et vous n’avez jamais à modifier le cœur pour intervenir.

Deux familles, une différence

<?php
// Une ACTION : elle agit, elle ne rend rien.
add_action('init', function () {
    register_post_type('recette', [/* ... */]);
});

// Un FILTRE : il reçoit, il transforme, il REND.
add_filter('the_title', function ($titre, $id = 0) {
    return get_post_type($id) === 'recette' ? '🍲 ' . $titre : $titre;
}, 10, 2);

post 4 → 🍲 Tarte aux pommes

Les deux nombres qu’on oublie

add_action et add_filter prennent deux arguments de plus, et les oublier est la cause de la moitié des pannes de débutant.

Combien de monde y a-t-il là-dedans ?

init n’est pas un crochet vide qui vous attend. Sur l’installation de cette page — un thème, deux greffons — voici ce qui s’y trouve déjà :

<?php
global $wp_filter;
$hook = $wp_filter['init'];
$total = 0;
foreach ($hook->callbacks as $priorite => $fonctions) {
    $total += count($fonctions);
}
echo count($hook->callbacks) . " priorités, $total fonctions accrochées sur init";

11 priorités, 124 fonctions accrochées sur init

Cent vingt-quatre fonctions, sur un site quasi vide. C’est ce que veut dire « extensible » : vous n’êtes jamais seul sur un hook, et c’est pourquoi la priorité existe.

Modifier un thème téléchargé, c’est perdre ses modifications à la première mise à jour. Le thème ENFANT hérite de tout et ne contient que vos différences.

Deux fichiers suffisent

/*
Theme Name:  STJO Enfant
Template:    twentytwentyone
Version:     1.0.0
Text Domain: stjo-enfant
*/

<?php

add_action('wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'stjo-enfant',
        get_stylesheet_uri(),
        ['twenty-twenty-one-style'],
        wp_get_theme()->get('Version')
    );
});

wp_enqueue_style déclare une feuille au lieu de l’écrire à la main dans l’en-tête. WordPress gère alors l’ordre, les dépendances — le troisième argument dit « après celle du parent » — et la version, qui sert de cache-buster.

Success: Switched to 'STJO Enfant' theme.

name          version  status
stjo-enfant   1.0.0    active
twentytwentyone  2.8   parent

Pourquoi ce cours enseigne un thème CLASSIQUE

Depuis WordPress 5.9, les thèmes livrés par défaut — twentytwentyfive notamment — sont des thèmes à BLOCS. Leur apparence ne se règle presque plus dans des gabarits PHP, mais dans un fichier theme.json et dans l’éditeur de site.

Ce cours part d’un thème classique, twentytwentyone, pour une raison précise : functions.php, les hooks et la hiérarchie de gabarits sont le socle TRANSFÉRABLE. Ils servent dans un thème classique, dans un greffon, et dans un thème à blocs. theme.json et l’éditeur de blocs sont un sujet à part entière, et feront leur propre cours.

Un greffon, c’est un dossier dans wp-content/plugins/ et un fichier PHP avec un en-tête en commentaire. Rien de plus.

Le fichier principal

<?php
/**
 * Plugin Name: STJO Recettes
 * Description: Déclare le type de contenu « recette », sa taxonomie et son champ de préparation.
 * Version:     1.0.0
 * Author:      Lycée Saint Joseph Lasalle
 * Text Domain: stjo-recettes
 */

if (! defined('ABSPATH')) {
    exit;
}

Plugin Name: est le seul champ obligatoire : c’est lui qui fait reconnaître le fichier comme un greffon.

Activation et désactivation

<?php
register_activation_hook(__FILE__, function () {
    stjo_declarer_recette();
    flush_rewrite_rules();
});

register_deactivation_hook(__FILE__, 'flush_rewrite_rules');

flush_rewrite_rules() recalcule les règles d’URL. Sans cet appel à l’activation, l’adresse /recettes/tarte-aux-pommes/ répond 404 alors que le contenu existe — c’est le grand classique du type de contenu personnalisé. Ne l’appelez QUE là : c’est une opération coûteuse, et l’exécuter à chaque chargement de page ralentit tout le site.

wp plugin activate stjo-recettes

Success: Activated 1 of 1 plugins.

Un article et une page ne suffisent pas toujours. Une recette a une durée, une saison, une image — et elle n’a rien à faire dans le flux des actualités.

Déclarer le type

<?php
add_action('init', 'stjo_declarer_recette');

function stjo_declarer_recette(): void
{
    register_post_type('recette', [
        'labels' => [
            'name'          => 'Recettes',
            'singular_name' => 'Recette',
            'add_new_item'  => 'Ajouter une recette',
        ],
        'public'       => true,
        'has_archive'  => true,
        'menu_icon'    => 'dashicons-food',
        'supports'     => ['title', 'editor', 'thumbnail', 'excerpt'],
        'rewrite'      => ['slug' => 'recettes'],
        'show_in_rest' => true,
    ]);
}

Les réglages qui comptent vraiment

La taxonomie qui va avec

Une taxonomie classe. saison est hiérarchique — comme les catégories, avec des parents ; une taxonomie non hiérarchique se comporte comme les étiquettes.

<?php
register_taxonomy('saison', 'recette', [
    'labels'       => ['name' => 'Saisons', 'singular_name' => 'Saison'],
    'public'       => true,
    'hierarchical' => true,
    'rewrite'      => ['slug' => 'saison'],
    'show_in_rest' => true,
]);

name      public  has_archive
recette   1       1

name      object_type
saison    recette

Le type existe, il a des contenus, et il s’affiche… avec le gabarit des articles. Il faut maintenant comprendre comment WordPress choisit le fichier qui rend une page.

Du plus précis au plus général

Pour une recette isolée, WordPress cherche dans cet ordre et s’arrête au premier fichier trouvé :

single-recette.php    # ce type précisément
single.php            # n'importe quel contenu isolé
singular.php          # isolé, article ou page
index.php             # le dernier recours, toujours présent

Le principe vaut partout : archive-recette.php avant archive.php, taxonomy-saison.php avant taxonomy.php. Créer le fichier suffit — il n’y a rien à déclarer.

Le gabarit d’une recette

<?php get_header(); ?>

<main id="primary" class="site-main">
    <?php while (have_posts()) : the_post(); ?>
        <article <?php post_class(); ?>>
            <h1><?php the_title(); ?></h1>

            <?php $minutes = get_post_meta(get_the_ID(), '_stjo_minutes', true); ?>
            <?php if ($minutes) : ?>
                <p class="preparation">
                    Préparation : <?php echo esc_html($minutes); ?> minutes
                </p>
            <?php endif; ?>

            <?php the_terms(get_the_ID(), 'saison', 'Saison : ', ', '); ?>

            <div class="entry-content"><?php the_content(); ?></div>
        </article>
    <?php endwhile; ?>
</main>

<?php get_footer(); ?>

Vérifier ce que WordPress a choisi

On n’a pas à deviner : le filtre template_include reçoit le chemin du fichier retenu, juste avant qu’il soit inclus.

<?php
add_filter('template_include', function ($gabarit) {
    echo 'Gabarit retenu : ' . str_replace(ABSPATH, '', $gabarit) . "\n";
    return $gabarit;
}, 999);

Gabarit retenu : wp-content/themes/stjo-enfant/single-recette.php
Préparation : 45 minutes
Saison : automne

Chaque page WordPress commence par une requête, faite avant même que votre gabarit s’exécute. La boucle ne fait que parcourir son résultat.

La boucle

<?php
while (have_posts()) :
    the_post();
    the_title('<h2>', '</h2>');
    the_excerpt();
endwhile;

the_post() avance d’un cran et prépare les fonctions the_*(). Sans lui, the_title() renvoie toujours le même contenu — ou rien.

Une requête secondaire

<?php
$q = new WP_Query([
    'post_type'      => 'recette',
    'posts_per_page' => 3,
    'tax_query'      => [[
        'taxonomy' => 'saison',
        'field'    => 'slug',
        'terms'    => 'automne',
    ]],
]);

echo $q->found_posts . " recette(s) trouvée(s)\n";
while ($q->have_posts()) {
    $q->the_post();
    echo '- ' . get_the_title() . "\n";
}
wp_reset_postdata();

1 recette(s) trouvée(s)
- Tarte aux pommes

Modifier la requête principale

Pour changer ce que la page affiche déjà, on ne lance pas une seconde requête : on modifie la première, avant qu’elle parte.

<?php
add_action('pre_get_posts', function (WP_Query $query) {
    if (is_admin() || ! $query->is_main_query() || ! $query->is_home()) {
        return;
    }
    $query->set('post_type', ['post', 'recette']);
});

Ne jamais interroger la base directement

La tentation existe, $wpdb est là. Mais une requête SQL écrite à la main saute les permissions, les statuts de publication, le cache d’objets, les filtres des greffons et le support multisite. WP_Query fait tout cela. Sur les rares cas qu’elle ne couvre pas, $wpdb->prepare() est obligatoire — la concaténation est une injection SQL.

Un greffon, c’est du PHP exposé sur le Web. WordPress fournit quatre mécanismes, et ils ne sont pas interchangeables : chacun répond à une question différente. Les voici tous les quatre sur une seule boîte de l’éditeur — celle qui enregistre la durée d’une recette.

1. Échapper à l’AFFICHAGE

La règle : échapper le plus tard possible, et dans le contexte exact où la donnée est écrite. Il y a une fonction par contexte.

<?php
esc_html($x)      // dans du texte
esc_attr($x)      // dans un attribut
esc_url($x)       // dans un href ou un src
esc_textarea($x)  // dans un <textarea>
wp_kses_post($x)  // du HTML autorisé, filtré sur la liste des balises d'article

<?php
$titre = "Tarte <script>alert(1)</script>";
echo "sans échappement : $titre\n";
echo "avec esc_html    : " . esc_html($titre) . "\n";

sans échappement : Tarte <script>alert(1)</script>
avec esc_html    : Tarte &lt;script&gt;alert(1)&lt;/script&gt;

2. Sanitiser à l’ENTRÉE

Échapper protège l’affichage ; sanitiser décide de la FORME de ce qu’on stocke. Les deux sont nécessaires, à deux moments différents.

<?php
absint($x)                 // un entier positif, et rien d'autre
sanitize_text_field($x)    // du texte sur une ligne, balises ôtées
sanitize_email($x)
sanitize_key($x)           // un identifiant : minuscules, chiffres, - et _
wp_kses_post($x)           // du HTML restreint

3. Le nonce : d’où vient cette requête ?

Un nonce est un jeton à usage limité qui prouve que le formulaire soumis vient bien de la page que vous avez servie. C’est la protection contre le CSRF, la même idée que le jeton du cours sur la sécurisation des formulaires — WordPress la fournit en deux fonctions.

4. Les capacités : cette personne a-t-elle le droit ?

current_user_can() interroge le rôle. Ne testez jamais le rôle lui-même (administrator) : testez la CAPACITÉ (edit_post), qui survit aux rôles personnalisés.

Les quatre ensemble, sur la recette

<?php
add_action('add_meta_boxes', function () {
    add_meta_box('stjo-preparation', 'Préparation', 'stjo_afficher_boite', 'recette', 'side');
});

function stjo_afficher_boite(WP_Post $post): void
{
    // 1. Le nonce : il prouve que le formulaire vient bien de cette page.
    wp_nonce_field('stjo_enregistrer_preparation', 'stjo_nonce');

    $minutes = get_post_meta($post->ID, '_stjo_minutes', true);

    // 2. Échapper à l'AFFICHAGE, dans le contexte exact — ici un attribut.
    printf(
        '<label for="stjo-minutes">Durée en minutes</label>
         <input type="number" id="stjo-minutes" name="stjo_minutes" min="1" value="%s">',
        esc_attr($minutes)
    );
}

add_action('save_post_recette', function (int $id) {
    // 3. Les capacités : cette personne a-t-elle le DROIT de modifier ceci ?
    if (! current_user_can('edit_post', $id)) {
        return;
    }
    if (! isset($_POST['stjo_nonce'])
        || ! wp_verify_nonce($_POST['stjo_nonce'], 'stjo_enregistrer_preparation')) {
        return;
    }
    if (defined('DOING_AUTOSAVE') && DOING_AUTOSAVE) {
        return;
    }

    // 4. Sanitiser à l'ENTRÉE : on décide de la forme, on ne la subit pas.
    $minutes = absint($_POST['stjo_minutes'] ?? 0);
    $minutes > 0
        ? update_post_meta($id, '_stjo_minutes', $minutes)
        : delete_post_meta($id, '_stjo_minutes');
});

Success: Updated custom field '_stjo_minutes'.
45

Le préfixe, et le tiret bas

• Préfixez TOUT ce que vous déclarez — stjo_ ici. Fonctions, méta, options, hooks : tout vit dans le même espace global, partagé avec des dizaines de greffons.
• Une méta dont la clef commence par un tiret bas (_stjo_minutes) n’apparaît pas dans la liste des champs personnalisés de l’éditeur. C’est ce qu’on veut pour un champ qui a déjà sa propre boîte.

Pour aller plus loin

Ces quatre gestes sont les OUTILS de WordPress. Le FOND — pourquoi le XSS fonctionne, ce qu’est vraiment une attaque CSRF, comment une injection SQL se construit — est traité ailleurs, et vaut pour tout PHP.

• 🛡️ Comprendre les failles
• 🔐 Sécuriser du PHP hors WordPress