# Mutations WPGraphQL : créer et modifier des contenus depuis le front

> WPGraphQL ne sert pas qu'à lire. Voici comment écrire des mutations pour créer ou modifier du contenu depuis un front, avec authentification et gestion des erreurs.

- Auteur : Clément Hadrot
- Publié le : 2021-07-23
- Mis à jour le : 2021-07-23
- Catégorie : Headless & API
- URL : https://wpmoderne.dev.wordpress-developpement.fr/headless/mutations-wpgraphql-creer-modifier-contenus-front/

## L’essentiel

- Une mutation par action, avec input et payload typés
- Authentification obligatoire pour toute écriture
- Gestion fine des erreurs de permission

La plupart des articles sur WPGraphQL se concentrent sur la lecture de contenu, parce que c'est l'usage le plus fréquent en headless. Mais un formulaire de contribution, un espace membre qui permet de modifier son profil, ou un système d'avis client nécessitent d'écrire dans WordPress depuis le front, pas seulement d'y lire. C'est le rôle des mutations GraphQL, l'équivalent des requêtes `POST`/`PUT` en REST.

Cet article couvre l'écriture de mutations avec WPGraphQL, l'authentification nécessaire pour qu'elles fonctionnent, et la gestion des erreurs de permission — sans aborder WPGraphQL for ACF, qui mérite un traitement séparé pour la gestion des champs personnalisés dans ces mêmes mutations.

## Anatomie d'une mutation WPGraphQL

Chaque mutation native de WPGraphQL suit la même convention : un objet `input` contenant les données à écrire, et un objet `payload` en retour, qui inclut l'objet créé ou modifié. La mutation `createPost` illustre ce schéma :

```
mutation CreerArticle($titre: String!, $contenu: String!) {
  createPost(
    input: {
      title: $titre
      content: $contenu
      status: DRAFT
    }
  ) {
    post {
      id
      databaseId
      title
      status
    }
  }
}
```

Le statut `DRAFT` plutôt que `PUBLISH` n'est pas anodin dans cet exemple : pour un contenu généré depuis un formulaire public (une candidature, un témoignage), il est presque toujours préférable de le créer en brouillon et de laisser un humain valider la publication, plutôt que de publier automatiquement du contenu non modéré.

## Authentifier la requête

Sans authentification, une mutation comme `createPost` échoue avec une erreur de permission, WPGraphQL respectant les mêmes capacités WordPress qu'une action équivalente dans l'administration. L'authentification passe généralement par un jeton JWT, obtenu via l'extension WPGraphQL JWT Authentication, transmis dans l'en-tête `Authorization` :

> L'essentiel à retenir : Une mutation par action, avec input et payload typés ; Authentification obligatoire pour toute écriture ; Gestion fine des erreurs de permission

```
const reponse = await fetch('https://exemple.fr/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${jetonJWT}`,
  },
  body: JSON.stringify({
    query: MUTATION_CREER_ARTICLE,
    variables: { titre: 'Mon titre', contenu: 'Le contenu de l\'article.' },
  }),
});

const { data, errors } = await reponse.json();
```

Notez que la réponse GraphQL renvoie systématiquement un code HTTP 200, même en cas d'erreur applicative : c'est le tableau `errors` dans le corps de la réponse qui signale un échec, jamais le code de statut HTTP seul. C'est une différence importante avec l'API REST, où une erreur de permission renvoie un 401 ou 403 explicite.

## Gérer les erreurs de permission

Une mutation qui échoue pour cause de permission insuffisante renvoie un message d'erreur dans le tableau `errors`, avec une catégorie identifiable dans les `extensions` de l'erreur :

```
{
  "errors": [
    {
      "message": "Sorry, you are not allowed to create posts as this user.",
      "extensions": { "category": "user" }
    }
  ],
  "data": { "createPost": null }
}
```

Côté front, il faut systématiquement vérifier la présence du tableau `errors` avant de considérer la mutation comme réussie, même si `data` contient une structure a priori valide :

```
if (errors && errors.length > 0) {
  throw new Error(errors[0].message);
}

if (!data.createPost.post) {
  throw new Error('La création a échoué sans message explicite.');
}
```

## Modifier un contenu existant

La mutation `updatePost` suit le même principe, en ajoutant l'identifiant de l'objet à modifier dans l'input :

```
mutation ModifierArticle($id: ID!, $titre: String!) {
  updatePost(input: { id: $id, title: $titre }) {
    post {
      id
      title
      modified
    }
  }
}
```

L'utilisateur authentifié doit disposer de la capacité `edit_post` sur l'article ciblé, exactement comme pour une modification via l'administration classique : WPGraphQL ne contourne jamais les capacités WordPress natives, il les applique simplement dans un contexte GraphQL.

## Un cas concret : un formulaire de témoignage client

Sur un front dédié aux témoignages clients, j'ai mis en place un formulaire public qui crée un CPT `temoignage` en statut brouillon via une mutation personnalisée, enregistrée côté WordPress avec `register_graphql_mutation()` plutôt que d'utiliser `createPost` directement, pour appliquer une validation métier spécifique (longueur minimale, filtrage anti-spam) avant l'écriture.

```
register_graphql_mutation( 'creerTemoignage', array(
    'inputFields' => array(
        'nomClient' => array( 'type' => 'String' ),
        'message'   => array( 'type' => 'String' ),
    ),
    'outputFields' => array(
        'succes' => array( 'type' => 'Boolean' ),
    ),
    'mutateAndGetPayload' => function ( $input ) {
        if ( strlen( $input['message'] ) < 20 ) {
            throw new \GraphQL\Error\UserError( 'Le message est trop court.' );
        }

        wp_insert_post( array(
            'post_type'    => 'temoignage',
            'post_title'   => sanitize_text_field( $input['nomClient'] ),
            'post_content' => sanitize_textarea_field( $input['message'] ),
            'post_status'  => 'draft',
        ) );

        return array( 'succes' => true );
    },
) );
```

> Une mutation personnalisée coûte plus cher à écrire qu'un appel direct à `createPost`, mais elle permet d'appliquer une validation métier avant l'écriture plutôt qu'après, ce qui évite de publier puis de corriger a posteriori un contenu non conforme.

## En résumé

Les mutations WPGraphQL permettent d'écrire dans WordPress depuis un front découplé, à condition de gérer l'authentification par jeton et de vérifier systématiquement le tableau `errors` plutôt que de se fier au seul code HTTP. Pour une logique métier au-delà d'une simple création ou modification, une mutation personnalisée via `register_graphql_mutation()` offre un contrôle bien plus fin que les mutations génériques.