Custom Post Types + ACF : le combo qui m a fait gagner 20h par semaine

Quand j ai commencé à faire du WordPress sur mesure en 2015, je passais un temps fou à bricoler des pages avec des page builders. Chaque modification du client cassait la mise en page, chaque nouveau contenu demandait un copier-coller laborieux. Et puis j ai découvert le duo Custom Post Types + Advanced Custom Fields. Onze ans plus tard, c est toujours la base de 90 % de mes projets clients. Je vous explique pourquoi, comment, et surtout comment éviter les pièges que j ai rencontrés.

Pourquoi les Custom Post Types changent tout

Par défaut, WordPress propose deux types de contenus : les articles (posts) et les pages. C est suffisant pour un blog, mais dès qu un client veut gérer un catalogue de produits, un annuaire de membres, des réalisations, des témoignages ou des événements, on se retrouve à tout entasser dans les articles avec des catégories bricolées. Résultat : un back-office illisible et un front ingérable.

Les Custom Post Types (CPT) résolvent ce problème en créant des types de contenus dédiés, chacun avec son propre menu dans l administration, ses propres URLs, et ses propres règles d affichage. Concrètement, quand je crée un CPT « Réalisations » pour un photographe, il voit apparaître dans son menu admin un onglet « Réalisations » aussi clair que l onglet « Articles ». Il n a plus aucune raison de se tromper d endroit pour publier.

Comme l explique la documentation officielle WordPress sur les Post Types, un CPT est un citoyen de première classe dans l écosystème WordPress. Il hérite de toutes les fonctionnalités natives : révisions, brouillons, planification, recherche, API REST. On ne bricole rien ; on étend proprement le CMS.

Pour un freelance, l avantage est aussi commercial. Un client qui voit un back-office structuré et intuitif comprend immédiatement la valeur de votre travail. Fini les formations de deux heures pour expliquer « non, il faut aller dans Articles, puis catégorie Projets, puis cocher la bonne case ». Le CPT impose une logique claire dès le départ.

ACF : le plugin qui transforme WordPress en CMS sur mesure

Un CPT sans champs personnalisés, c est une coquille vide. WordPress natif ne propose que le titre, l éditeur de contenu et l image mise en avant. Si votre client doit renseigner un prix, une adresse, une date d événement, un lien vidéo ou une galerie spécifique, il faut des champs sur mesure.

C est là qu intervient Advanced Custom Fields (ACF). Ce plugin, maintenu par WP Engine depuis le rachat de Delicious Brains, permet de créer n importe quel type de champ et de l attacher à un CPT, une page, un utilisateur, un terme de taxonomie, voire un bloc Gutenberg. La version gratuite couvre déjà les cas simples : texte, nombre, image, sélecteur de date, vrai/faux, relation entre posts. La version Pro (à partir de 49 $/an pour un site) ajoute les champs Repeater, Flexible Content, Gallery, Clone et les options pages.

Ce qui m a convaincu dès 2016, c est la qualité de l interface d administration. ACF génère des formulaires propres, cohérents avec le design natif de WordPress. Le client remplit des champs étiquetés, avec des aides contextuelles, des conditions d affichage. Il ne touche jamais au HTML. C est un vrai formulaire métier, pas un éditeur visuel détourné.

Depuis la version 6.1, ACF intègre nativement la création de Custom Post Types et de taxonomies directement depuis son interface. Plus besoin d installer Custom Post Type UI en complément ni d écrire du register_post_type() dans functions.php. Tout se fait depuis ACF > Post Types dans le menu admin. Les CPT créés via l interface sont exportables en PHP, ce qui permet de les versionner avec Git ; un point que je détaille dans mon article sur Git pour un développeur WordPress.

Créer un CPT avec ACF depuis zéro

Je vais vous montrer les deux méthodes : via l interface ACF (la plus rapide) et via le code PHP (la plus contrôlable). Dans mes projets, j utilise souvent l interface pour prototyper, puis j exporte en PHP pour le thème final.

Méthode 1 : l interface ACF (depuis ACF 6.1+)

Direction ACF > Post Types > Add New. Renseignez :

• Plural Label : Réalisations
• Singular Label : Réalisation
• Post Type Key : realisation (en minuscules, sans accent, 20 caractères max)

Dans l onglet Supports, cochez ce dont vous avez besoin : Title, Editor, Thumbnail, Excerpt, Revisions. Désactivez ce qui est superflu ; moins il y a de cases inutiles dans l admin, moins le client est perdu.

Dans l onglet Visibility, activez Public, Show in REST (obligatoire pour Gutenberg et l API REST), et configurez le Rewrite Slug (par exemple realisations). N oubliez pas de flusher les permaliens après : Réglages > Permaliens > Enregistrer. Je rappelle ce réflexe dans mon guide sur les réglages SEO technique WordPress.

Méthode 2 : le code PHP (recommandé pour la prod)

Dans votre thème enfant ou votre plugin custom, ajoutez :

add_action( 'init', function() {
    register_post_type( 'realisation', [
        'labels' => [
            'name'          => 'Réalisations',
            'singular_name' => 'Réalisation',
            'add_new_item'  => 'Ajouter une réalisation',
            'edit_item'     => 'Modifier la réalisation',
        ],
        'public'       => true,
        'has_archive'  => true,
        'rewrite'      => [ 'slug' => 'realisations' ],
        'show_in_rest' => true,
        'supports'     => [ 'title', 'editor', 'thumbnail', 'excerpt', 'revisions' ],
        'menu_icon'    => 'dashicons-portfolio',
    ]);
});

Ce code est versionnable, testable, déployable via WP-CLI. D ailleurs, avec la commande wp post-type list, vous pouvez vérifier en une seconde que votre CPT est bien enregistré. Pour aller plus loin avec WP-CLI, consultez mon article sur les 12 commandes WP-CLI indispensables.

Ajouter une taxonomie personnalisée

Un CPT sans taxonomie, c est comme un classeur sans onglets. Pour notre exemple de réalisations, on crée une taxonomie « Type de projet » :

add_action( 'init', function() {
    register_taxonomy( 'type_projet', 'realisation', [
        'labels' => [
            'name'          => 'Types de projet',
            'singular_name' => 'Type de projet',
        ],
        'public'       => true,
        'hierarchical' => true,
        'show_in_rest' => true,
        'rewrite'      => [ 'slug' => 'type-projet' ],
    ]);
});

Le paramètre hierarchical => true donne un comportement de catégorie (avec cases à cocher). Passez-le à false pour un comportement de tag (saisie libre).

Les champs ACF indispensables par type de projet

Après des dizaines de projets, j ai identifié des patterns récurrents de groupes de champs ACF selon le type de CPT. Voici les combinaisons que je réutilise le plus souvent :

Portfolio / Réalisations

• Gallery (Pro) : galerie d images du projet
• URL : lien vers le site en ligne
• Date Picker : date de réalisation
• Taxonomy : technologies utilisées
• Textarea : description courte affichée en listing
• True/False : projet mis en avant oui/non

Annuaire / Membres

• Text : nom, prénom, fonction
• Email : adresse email
• Image : photo de profil
• Google Map (Pro) : localisation
• Repeater (Pro) : réseaux sociaux (nom du réseau + URL)
• Select : statut (actif, ancien membre, honoraire)

Événements

• Date Picker : date de début et date de fin
• Time Picker : heure de début
• Text : lieu
• Number : nombre de places
• URL : lien d inscription
• Flexible Content (Pro) : programme de l événement avec blocs intervenants, pauses, ateliers

Témoignages / Avis

• Textarea : citation
• Text : nom du client
• Text : entreprise
• Image : avatar
• Range : note sur 5
• Post Object : lié à quelle réalisation

Le champ Post Object est particulièrement puissant : il crée des relations entre CPT. Un témoignage lié à une réalisation, un événement lié à un intervenant, une FAQ liée à un service. C est ce qui transforme WordPress d un simple CMS en une vraie base de données relationnelle accessible sans écrire de SQL.

Afficher les données CPT + ACF dans vos templates

Créer des CPT et des champs, c est la moitié du travail. L autre moitié, c est l affichage front-end. Voici les bases essentielles.

Le template single

WordPress cherche automatiquement un fichier single-{post_type}.php dans votre thème. Pour notre CPT « realisation », créez single-realisation.php :

<?php get_header(); ?>

<article class="realisation-single">
    <h1><?php the_title(); ?></h1>
    
    <?php if ( $url = get_field( 'url_projet' ) ) : ?>
        <a href="<?php echo esc_url( $url ); ?>" target="_blank" rel="noopener">
            Voir le site
        </a>
    <?php endif; ?>
    
    <?php if ( $gallery = get_field( 'galerie' ) ) : ?>
        <div class="realisation-gallery">
            <?php foreach ( $gallery as $image ) : ?>
                <img src="<?php echo esc_url( $image['sizes']['large'] ); ?>" 
                     alt="<?php echo esc_attr( $image['alt'] ); ?>" 
                     loading="lazy" />
            <?php endforeach; ?>
        </div>
    <?php endif; ?>
    
    <div class="realisation-content">
        <?php the_content(); ?>
    </div>
</article>

<?php get_footer(); ?>

Deux fonctions ACF à retenir : get_field() retourne la valeur brute, the_field() l affiche directement. Utilisez toujours get_field() quand vous devez traiter la donnée avant affichage (test conditionnel, formatage, échappement). Et n oubliez jamais esc_url(), esc_attr(), esc_html() pour la sécurité ; c est non négociable.

La WP_Query pour les listings

Pour afficher la liste de vos réalisations (page archive, widget, section de la homepage), utilisez WP_Query :

$realisations = new WP_Query([
    'post_type'      => 'realisation',
    'posts_per_page' => 9,
    'orderby'        => 'date',
    'order'          => 'DESC',
    'meta_query'     => [
        [
            'key'   => 'mise_en_avant',
            'value' => '1',
        ],
    ],
]);

if ( $realisations->have_posts() ) :
    while ( $realisations->have_posts() ) : $realisations->the_post();
        // Affichage de chaque réalisation
        $url = get_field( 'url_projet' );
        $date_realisation = get_field( 'date_realisation' );
        get_template_part( 'template-parts/card', 'realisation' );
    endwhile;
    wp_reset_postdata();
endif;

Le wp_reset_postdata() est obligatoire après chaque WP_Query custom. L oublier provoque des bugs subtils et difficiles à tracer, notamment dans les sidebars et les footers.

Pour les projets où le client a besoin de filtrer les réalisations en AJAX, j utilise souvent l API REST de WordPress combinée aux meta fields ACF exposés via show_in_rest. C est plus propre qu un endpoint admin-ajax.php bricolé. J en parle en détail dans mon guide sur l intégration d API dans WordPress.

CPT, ACF et SEO technique

Un CPT bien configuré améliore naturellement votre SEO. Voici pourquoi et comment en tirer le maximum.

Des URLs propres et hiérarchiques. Avec un slug bien choisi, vos réalisations sont accessibles via /realisations/nom-du-projet/. Google comprend immédiatement la structure. Ajoutez une taxonomie, et vous obtenez des pages d archive filtrées comme /type-projet/site-vitrine/, chacune avec son propre title et sa propre meta description si vous utilisez Yoast ou Rank Math.

Du contenu structuré pour Schema.org. Grâce aux champs ACF, vous avez des données typées (dates, URLs, images, notes) que vous pouvez injecter dans un balisage JSON-LD. Pour un CPT « Événement », vous pouvez générer automatiquement un schema Event avec startDate, location, offers. Pour un CPT « Témoignage », un schema Review avec reviewRating. J ai détaillé cette approche dans mon article sur Schema.org pour un site vitrine en 2026.

Des sitemaps segmentés. Les plugins SEO génèrent automatiquement des sitemaps distincts par CPT. Google indexe chaque type de contenu séparément, ce qui améliore la couverture d indexation et facilite le diagnostic dans la Search Console.

Performance et images. Les champs Image d ACF retournent toutes les tailles générées par WordPress. Utilisez toujours la taille adaptée au contexte d affichage, jamais l image originale en pleine résolution. Et activez le lazy loading natif avec loading="lazy". Pour aller plus loin sur l optimisation des images, consultez mon article sur l optimisation WebP et AVIF pour WordPress.

Comparatif ACF vs alternatives en 2026

ACF n est pas le seul plugin de champs personnalisés. Voici comment il se positionne face aux alternatives que j ai testées sur de vrais projets :

Mon choix reste ACF Pro pour la majorité des projets. La documentation officielle ACF est exemplaire, la communauté est massive, et l intégration avec Gutenberg via les blocs ACF fonctionne remarquablement bien. Meta Box est une alternative crédible si vous cherchez de meilleures performances brutes sur des sites à très fort volume de contenus (10 000+ entrées).

Erreurs fréquentes et comment les éviter

En onze ans de pratique, j ai commis (et vu chez d autres devs) des erreurs récurrentes. Voici les plus courantes et comment les contourner.

Erreur 1 : oublier show_in_rest

Sans 'show_in_rest' => true, votre CPT utilise l ancien éditeur classique au lieu de Gutenberg. En 2026, c est inacceptable. Pire, votre CPT est invisible pour l API REST, ce qui bloque toute intégration headless ou AJAX moderne.

Erreur 2 : un slug de CPT trop long ou avec des caractères spéciaux

Le post type key est limité à 20 caractères, en minuscules, sans tirets (underscores autorisés). mes_super_realisations_portfolio ne marchera pas. Restez court : realisation, event, membre.

Erreur 3 : ne pas flusher les permaliens

Après chaque modification de slug de CPT ou de taxonomie, allez dans Réglages > Permaliens et cliquez sur Enregistrer. Sans ça, vos URLs retournent des 404. C est la source de panique numéro un chez les débutants.

Erreur 4 : stocker les champs ACF dans le code au lieu de les synchroniser

Si vous travaillez en équipe ou si vous déployez sur plusieurs environnements (local, staging, prod), activez la synchronisation JSON d ACF. Ajoutez dans votre thème :

add_filter( 'acf/settings/save_json', function() {
    return get_stylesheet_directory() . '/acf-json';
});

add_filter( 'acf/settings/load_json', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/acf-json';
    return $paths;
});

Créez le dossier acf-json dans votre thème. Désormais, chaque modification de groupe de champs génère un fichier JSON versionnable avec Git. C est la base d un workflow professionnel. Je le mets en place systématiquement, comme je l explique dans mon article sur Docker Compose pour WordPress local.

Erreur 5 : utiliser un Repeater quand il faut un CPT

J ai vu des devs créer un Repeater avec 15 sous-champs pour gérer une liste de membres. Le jour où le client veut filtrer, trier, paginer ou lier ces membres à d autres contenus, tout s effondre. Règle simple : si votre contenu a besoin de sa propre URL, de relations avec d autres contenus, ou dépasse 20 entrées, utilisez un CPT. Le Repeater est fait pour des listes courtes et locales (horaires d ouverture, coordonnées de réseaux sociaux, étapes d un processus).

Mon workflow réel sur un projet client

Pour illustrer concrètement, voici comment j ai structuré le site d un cabinet d architectes le mois dernier. Le client avait besoin de gérer ses projets, ses membres d équipe et ses actualités.

Étape 1 : architecture CPT. J ai créé trois CPT : projet, membre, actu. Deux taxonomies : type_projet (résidentiel, tertiaire, public) et competence (pour les membres). Temps : 15 minutes.

Étape 2 : groupes de champs ACF. Pour chaque CPT, un groupe de champs dédié. Le CPT « projet » a reçu 8 champs (galerie, surface, année, localisation, budget, maître d ouvrage, statut, description courte). Le CPT « membre » a reçu 6 champs (fonction, bio courte, photo portrait, email, LinkedIn, ordre d affichage). Temps : 30 minutes.

Étape 3 : templates. Un single-projet.php, un archive-projet.php avec filtres par taxonomie en JavaScript vanilla, et une section équipe sur la page À propos via une WP_Query. Temps : 3 heures.

Étape 4 : SEO et schema. Injection automatique d un schema ArchitectureProject (en réalité CreativeWork avec des propriétés adaptées) depuis les champs ACF. Sitemap dédié pour les projets. Temps : 45 minutes.

Total : environ 4h30 de développement pour une architecture complète, maintenable, performante. Sans CPT + ACF, le même résultat avec un page builder m aurait pris au minimum 12 heures, avec un résultat fragile et difficile à maintenir.

Ce type de workflow est aussi plus simple à sauvegarder et déployer. Tout le code est versionné, les champs ACF sont synchronisés en JSON, et la base de données ne contient que du contenu. Si le client change d hébergeur, un wp export + wp import + git pull suffit. Pour la stratégie de sauvegarde, je détaille mes options dans l article sur les sauvegardes WordPress automatiques.