WordPress avec Pods et WPGraphQL¶

Configurez un backend WordPress pour Silex avec des types de contenu personnalisés et une API GraphQL.

Aperçu¶

WordPress est le principal backend CMS pour Silex. En utilisant deux plugins, vous pouvez définir des types de contenu personnalisés, des champs personnalisés et les exposer via GraphQL :

Pods — Créer des types de publication personnalisés et des champs personnalisés (100% open source, GPL)
WPGraphQL — API GraphQL pour WordPress

Pourquoi Pods ?¶

Nous recommandons Pods parce qu'il est 100% open source (GPL), en cohérence avec la philosophie libre de Silex. Pods gère les types de publication personnalisés, les champs personnalisés et les taxonomies personnalisées — tout dans un seul plugin, sans extension supplémentaire.

L'alternative populaire, ACF (Advanced Custom Fields), a une version gratuite aux fonctionnalités limitées et une version Pro commerciale (~99$/an). Silex étant un projet libre et open source, nous préférons recommander des outils qui partagent les mêmes valeurs. Voir Utiliser ACF à la place si vous l'utilisez déjà.

Cette approche permet aux designers de lier des composants Silex aux données WordPress sans coder.

Prérequis¶

WordPress 5.9 ou ultérieur
PHP 7.4 ou ultérieur
Accès administrateur WordPress
Instance Silex avec le CMS activé (par défaut)

Installation¶

1. Installer et activer les plugins¶

Dans l'administration WordPress :

Allez dans Extensions → Ajouter
Recherchez et installez :
Pods (gratuit, open source)
WPGraphQL (gratuit)
Activez les deux

Ou via WP-CLI :

wp plugin install pods --activate
wp plugin install wp-graphql --activate

2. Installer WPGraphQL pour Pods (si nécessaire)¶

Les champs Pods peuvent ne pas apparaître dans GraphQL par défaut. Ajoutez le plugin d'intégration :

wp plugin install wpgraphql-for-pods --activate

Ou recherchez « WPGraphQL for Pods » dans le répertoire des plugins.

Définir les types de contenu¶

Créer un type de publication personnalisé¶

Avec Pods :

Allez dans Pods Admin → Edit Pods
Cliquez sur Add New
Sélectionnez Custom Post Type et configurez :
Pod Name : blog_post (sans espaces, minuscules)
Plural Label : Blog Posts
Singular Label : Blog Post
Description : Blog posts and articles
Cochez : Show in REST API et Show in GraphQL
Cliquez sur Save Pod

Créer des champs personnalisés avec Pods¶

Les champs personnalisés sont gérés directement dans la définition du Pod :

Allez dans Pods Admin → Edit Pods
Sélectionnez le pod auquel vous souhaitez ajouter des champs (par ex. Blog Post)
Cliquez sur Add Field et configurez chaque champ :
Featured Image (champ File / Image)
Author Name (champ Plain Text)
Excerpt (champ Paragraph Text)
Categories (champ Relationship, lié à la catégorie)
Pour chaque champ, assurez-vous que Show in GraphQL est activé dans les paramètres du champ
Cliquez sur Save Pod

Mapper les champs vers GraphQL¶

Avec WPGraphQL + Pods (et le plugin WPGraphQL for Pods si nécessaire), les champs sont exposés automatiquement. Dans l'explorateur GraphQL, ils apparaissent directement sous les champs du type de publication :

{
  blogPosts {
    edges {
      node {
        id
        title
        content
        featuredImage {
          sourceUrl
        }
        authorName
        excerpt
        categories {
          edges {
            node {
              name
            }
          }
        }
      }
    }
  }
}

Contrats de données¶

Un contrat de données définit la forme des données attendues par votre site Silex. Documentez les contrats avant de construire le site.

Exemple : Contrat d'article de blog¶

// Data contract: Blog Post
{
  type: "BlogPost",
  fields: {
    id: { type: "string", description: "Post ID" },
    title: { type: "string", description: "Post title" },
    slug: { type: "string", description: "Post slug (URL)" },
    content: { type: "string", description: "Post content (HTML)" },
    excerpt: { type: "string", description: "Short description" },
    date: { type: "date", description: "Publication date" },
    author: {
      type: "object",
      fields: {
        name: { type: "string" },
        avatar: { type: "string" },
      }
    },
    featuredImage: {
      type: "object",
      fields: {
        sourceUrl: { type: "string", description: "Image URL" },
        altText: { type: "string", description: "Alt text" },
      }
    },
    categories: {
      type: "array",
      items: {
        type: "object",
        fields: {
          name: { type: "string" },
          slug: { type: "string" },
        }
      }
    }
  }
}

Créer les champs Pods correspondant au contrat¶

Dans Pods, créez des champs correspondant à votre contrat en allant dans Pods Admin → Edit Pods → sélectionnez votre pod :

Nom du champ	Type de champ	Paramètres Pods
Excerpt	Paragraph Text	Max length 200
Featured Image	File / Image	Single file
Author Name	Plain Text	Required
Categories	Relationship	Related to: Category

Requêter WordPress via GraphQL¶

Accéder à l'API GraphQL¶

Après avoir activé WPGraphQL, accédez au endpoint GraphQL :

https://your-wordpress.com/graphql

Ou utilisez l'explorateur GraphiQL :

https://your-wordpress.com/graphql?enable=true

Exemples de requêtes¶

Requêter tous les articles de blog :

query GetBlogPosts {
  blogPosts(first: 10) {
    edges {
      node {
        id
        title
        slug
        excerpt
        date
        featuredImage {
          sourceUrl
          altText
        }
        authorName
      }
    }
  }
}

Requêter par catégorie :

query GetPostsByCategory {
  blogPosts(
    first: 10
    where: {
      categoryName: "news"
    }
  ) {
    edges {
      node {
        id
        title
        slug
      }
    }
  }
}

Requêter un seul article :

query GetPost {
  blogPostBy(slug: "my-first-post") {
    id
    title
    content
    authorName
    featuredImage {
      sourceUrl
    }
  }
}

Configurer Silex pour utiliser WordPress¶

Dans l'éditeur Silex¶

Allez dans Settings → Page → CMS
Cliquez sur Add Data Source
Configurez :
Name : WordPress
Type : GraphQL
URL : https://your-wordpress.com/graphql
Backend : wordpress
Cliquez sur Save

Dans la configuration client¶

Ou configurez dans votre fichier de configuration client :

// client-config.js
export default async function (config) {
  config.cmsConfig.dataSources = [
    {
      id: 'wordpress',
      type: 'graphql',
      url: 'https://my-wordpress.com/graphql',
      backend: 'wordpress',
    },
  ]
}

Configuration côté serveur (optionnel)¶

Si vous devez ajouter de la logique personnalisée côté serveur :

// .silex.js
module.exports = async function (config) {
  // WordPress is built-in, no special config needed
  // But you can customize if needed
}

Lier les données dans Silex¶

Dans l'éditeur, créez des états qui se lient aux données WordPress :

Boucler sur les articles¶

Ajoutez un composant Div (se répétera pour chaque article)
Panneau de droite → Data → Add State
Configurez :
Name : posts
Type : Query (GraphQL)

Expression :

query GetPosts {
  blogPosts(first: 10) {
    edges {
      node {
        id
        title
        slug
        authorName
      }
    }
  }
}

Définissez Loop Over : posts.edges

Le composant se répète pour chaque article.

Lier du texte au titre de l'article¶

Ajoutez un composant Text à l'intérieur du div répétitif
Panneau de droite → Data → Add State
État innerHTML :
Expression : node.title

Le texte affiche le titre de l'article.

Afficher l'image mise en avant¶

Ajoutez un composant Image
Panneau de droite → Data → Add State
État src :
Expression : node.featuredImage.sourceUrl

Authentification et permissions¶

Accès public (sans authentification)¶

Par défaut, WPGraphQL autorise les requêtes publiques. Cela convient pour la lecture d'articles publics.

Restreindre aux utilisateurs authentifiés¶

Pour limiter les requêtes aux utilisateurs connectés, dans WordPress :

Installez WPGraphQL Smart Cache (optionnel)

Ajoutez dans wp-config.php :

define('GRAPHQL_ENABLED', true);
define('GRAPHQL_PUBLIC', false); // Require auth

Puis dans Silex, authentifiez-vous avec les identifiants WordPress.

Protection des données personnelles (RGPD)¶

Si vous requêtez des données utilisateur, assurez-vous :

Que les utilisateurs consentent à l'exposition de leurs données
Que les requêtes n'incluent pas de champs sensibles
Que la politique de confidentialité divulgue l'utilisation des données

Dépannage¶

Le endpoint GraphQL retourne une erreur 404¶

Vérifiez :

Le plugin WPGraphQL est activé
L'URL est correcte : https://your-wordpress.com/graphql
Les permaliens sont définis (Réglages WordPress → Permaliens)

Essayez de visiter /graphql directement dans le navigateur.

Les champs Pods ne sont pas dans GraphQL¶

Assurez-vous :

Le plugin WPGraphQL for Pods est installé et activé (si les champs n'apparaissent pas automatiquement)
Show in GraphQL est activé dans les paramètres du Pod pour chaque pod et chaque champ
WPGraphQL est activé pour le type de publication

Allez dans Pods Admin → Edit Pods, sélectionnez le pod et vérifiez que chaque champ a « Show in GraphQL » activé.

Les requêtes retournent null ou vide¶

Vérifiez :

Les articles existent : /wp-admin/edit.php?post_type=blog_post
Les champs Pods sont remplis
La syntaxe de la requête GraphQL est correcte (utilisez GraphiQL pour tester)

Erreurs d'authentification dans Silex¶

Si les requêtes échouent avec des erreurs d'authentification :

Vérifiez si WPGraphQL est public : essayez de requêter sans authentification
Si l'authentification est requise, vous devrez peut-être passer des identifiants à Silex (contactez le support)

Problèmes de performance¶

WordPress peut être lent avec de grands ensembles de données. Optimisez :

Paginez les requêtes :

query GetPosts($first: Int!, $after: String) {
  blogPosts(first: $first, after: $after) {
    pageInfo { endCursor hasNextPage }
    edges { node { id title } }
  }
}

Limitez les champs : Ne requêtez que les champs nécessaires
Mettez en cache les résultats : Utilisez le plugin WPGraphQL Smart Cache
Améliorez l'hébergement : Plus de CPU/RAM aide

Bonnes pratiques¶

Conventions de nommage¶

Slug du type de publication : minuscules avec underscores (blog_post, team_member)
Noms de champs : minuscules avec underscores (featured_image, author_name)
Taxonomie personnalisée : minuscules au pluriel (blog_categories, tags)

Organisation des champs¶

Groupez les champs liés dans votre définition de Pod :

Contenu : titre, contenu, extrait
Média : image mise en avant, galerie
Métadonnées : auteur, date, catégories

Validation des données¶

Utilisez les paramètres des champs Pods :

Champs obligatoires : Empêcher les articles incomplets
Limites de champs : Longueur maximale des zones de texte
Logique conditionnelle : Afficher des champs selon d'autres champs

Documentation¶

Documentez votre contrat de données :

## WordPress Data Structure

### BlogPost post type
- `title` (string): Post title
- `content` (HTML): Main content
- `featuredImage.sourceUrl` (URL): Hero image
- `authorName` (string): Author name
- `categories[].name` (array): Post categories

Utiliser ACF à la place¶

Si vous préférez ACF (Advanced Custom Fields), la configuration est similaire. Installez ACF + WPGraphQL for ACF au lieu de Pods + WPGraphQL for Pods. ACF Pro est un plugin commercial (~99$/an) qui gère également les champs personnalisés et les types de publication. La structure des requêtes GraphQL diffère légèrement : les champs ACF apparaissent sous un wrapper acfFields (par ex. acfFields.featuredImage.sourceUrl au lieu de featuredImage.sourceUrl).

Voir aussi¶

Configuration client et plugins — Paramètres CMS de la configuration client
Configuration WordPress — Guide WordPress pour les designers
Lier les données — Liaison de données dans l'éditeur
WPGraphQL docs — Référence complète de l'API
Pods docs — Documentation du framework Pods

Éditer cette page sur GitLab