Création de points de terminaison personnalisés pour l'API REST WordPress –

Ce tutoriel vous guide dans la création d'un point de terminaison personnalisé WP-API . Nous allons d'abord créer un thème enfant du thème par défaut «Twenty Seventeen» ce qui nous permettra d'ajouter des fonctionnalités à notre thème, puis nous allons enregistrer notre point de terminaison API personnalisé.

The WordPress REST L'API vous fournit plus qu'un simple ensemble d'itinéraires intégrés. Vous pouvez également créer des itinéraires et des points de terminaison personnalisés à l'aide des mêmes API utilisées pour créer des itinéraires par défaut (par exemple, la fonction register_rest_route () et la classe WP_Rest_Controller etc.). Avec WP-API, vous aurez la possibilité d'intégrer WordPress à d'autres écosystèmes, ce qui fait de WordPress une plate-forme de développement d'applications puissante et moderne.

Vous pouvez créer ou enregistrer des points de terminaison personnalisés dans des plugins ou des thèmes.

Création d'un Thème enfant

Dans votre dossier d'installation WordPress, créez un dossier pour votre thème enfant. Appelons-le vingt-sept ans :

 cd / var / www / html / wp-content / themes
mkdir vingt-sept enfant

Créez ensuite un fichier style.css :

 touch style.css.

Et ajoutez les informations d'en-tête suivantes:

 / *
 Nom du thème: Thème Twenty Seventeen Child
 description: Un thème enfant du thème WordPress Twenty Seventeen
 Auteur: Ahmed Bouchefra
 Modèle: vingt-sept
 Version: 1.0.0
* /

Le champ Modèle fait référence au nom du dossier du thème parent.

Accédez à Apparence -> Thèmes dans l'administrateur WordPress et choisissez votre thème pour enfant:

Cliquez ensuite sur le bouton Activer pour activer le thème enfant:

.

Dans le dossier des thèmes, ajoutez un fichier functions.php avec le code initial suivant:

 <? Php
// Ajoute le code ici.

Création d'un point de terminaison WP-API personnalisé

Nous souhaitons créer un nouvel itinéraire qui nous permettra de récupérer les publications les plus récentes par catégorie avec le format suivant:

 http: // localhost / wp-json / mytwentyseventeentheme / v1 / latest-posts / 

À ce stade, si nous visitons l'URL ci-dessus dans notre navigateur, nous obtiendrons une erreur 404 avec le message "Aucun itinéraire ne correspond à l'URL et à la méthode de requête" :

En effet, nous n'avons pas réellement cette route.

Dans le fichier functions.php de votre thème ajoutez le code suivant:

 add_action ('rest_api_init', function () {
  register_rest_route ('mytwentyseventeentheme / v1', 'latest-posts / (? P   d +)', tableau (
                'méthodes' => 'GET',
                'callback' => 'get_latest_posts_by_category'
      ));
});

Nous utilisons register_rest_route () avec les paramètres suivants:

• un espace de noms, mytwentyseventeentheme / v1
• un chemin de ressources avec un regex pour saisir l'identificateur de catégorie, latest-posts / (? P d +)
• un tableau d'options dans lequel nous spécifions la méthode GET et une fonction de rappel get_latest_posts_by_category () qui gère la demande.

Un espace de nom permet à deux plugins ou thèmes d'utiliser les mêmes chemins de route sans conflit et aux clients de détecter le support de votre API personnalisée en utilisant simplement l'API / wp-json / wp / v2 et en vérifiant les espaces de nom Champ .

Vous pouvez voir sur la capture d'écran que le mytwentyseventeentheme / v1 que nous avons utilisé pour notre itinéraire personnalisé est ajouté au . espace de noms (cette capture d'écran est réalisée après la mise en œuvre complète de notre terminal personnalisé;

Remarquez la partie ? P d + . Cela nous permettra de récupérer l'ID de catégorie de la demande en cours. C'est simplement une expression rationnelle, vous pouvez donc utiliser la logique des expressions rationnelles normales pour créer un motif.

Implémentation de la fonction de rappel

À ce stade, si nous visitons notre URL précédente, WordPress reconnaît l'itinéraire, car nous l'avons défini. Cependant, nous avons toujours une erreur 500 avec le message "Le gestionnaire de la route est invalide" .

. la route personnalisée et en spécifiant la fonction get_latest_posts_by_category () en tant que rappel appelé pour le traitement et la gestion de la requête GET, implémentons-la réellement:

 function get_latest_posts_by_category ($ request) {

    $ args = array (
            'category' => $ request ['category_id']
    )

    $ posts = get_posts ($ args);
    if (vide ($ posts)) {
    return new WP_Error ('empty_category', 'il n'y a pas de publication dans cette catégorie', array ('status' => 404));

    }

    $ response = new WP_REST_Response ($ posts);
    $ response-> set_status (200);

    return $ response;
}

Nous récupérons tout d'abord l'argument category_id du paramètre $ request par accès direct. Nous créons ensuite un tableau $ args avec la clé de la catégorie définie sur la valeur de category_id qui sera extraite de la route.

Nous l'appelons ensuite le get_posts () méthode permettant de rechercher des publications avec l'ID de catégorie spécifié. Si nous obtenons un tableau de messages vide, nous renvoyons un message d'erreur comprenant un code empy_category un message il n'y a pas de message dans cette catégorie et un code d'état 404 - qui sont tous transmis. au constructeur de la classe WP_Error .

Voici une capture d'écran que nous obtenons si nous avons une catégorie vide:

Nous finissons par créer une nouvelle instance de la classe WP_REST_Response ; nous passons dans le tableau $ posts ; nous avons défini le code de statut 200; et nous retournons la réponse REST. Nous pouvons également renvoyer directement le tableau $ posts et il sera automatiquement converti en JSON.

Les classes WP_Error et WP_REST_Response permettent de s'assurer que le noeud final renvoie une réponse JSON valide.

Maintenant, si nous revenons à notre navigateur et visitons par exemple cette URL:

 http: //  / wp-json / mytwentyseventeentheme / v1 / latest-posts / 1

… nous obtiendrons soit un tableau vide, soit les messages appartenant à la catégorie ID 1 .

Vous pouvez également fournir des rappels d'assainissement et de validation en plus de votre rappel principal.

Vous pouvez définir des arguments pour chaque route sous forme de tableau avec l'option args tout comme l'option callback . Dans le tableau, vous pouvez ajouter plusieurs arguments. La clé est le nom de l'argument et la valeur est un tableau d'options pour cet argument, telles que sanitize_callback ou validate_callback .

• validate_callback est une fonction de rappel pour valider l'argument. Il faut une fonction qui recevra la valeur de l'argument et devrait retourner true si la valeur est valide ou false sinon.
• sanitize_callback est une fonction de rappel utilisée pour assainir la valeur de l'argument avant de le transmettre au fonction de rappel . La valeur est transmise en tant que paramètre à cette fonction.

Désinfection et validation des paramètres de noeud final

Vous pouvez valider les paramètres transmis au noeud final - dans notre cas, l'ID de catégorie - à l'aide de validate_callback () . fonction:

 'args' => [
  'category_id' => array(
      'validate_callback' => function($value, $request, $param) {
              return $value >= 6;
      })
]

Le paramètre est le premier argument transmis au rappel. Nous utilisons l'expression $ value> = 6 pour vérifier si l'ID de catégorie transmis est supérieur ou égal à six. Si nous passons une valeur inférieure à six, une erreur Paramètre (s) invalide (s): category_id sera renvoyée.

L'assainissement vous permet de nettoyer le fichier. paramètres. Pour assainir les données, vous devez utiliser la fonction sanitize_callback () de la manière suivante:

 'args' => [
    'category_id' => array(
      'sanitize_callback' => function($value, $request, $param) {
              if($value < 6){
         return 6;
    };
      })
],

Si l'ID de catégorie est inférieur à six, nous en renvoyons simplement six. De cette manière, nous nous assurons de ne recevoir un événement de valeur acceptable que si le client transmet une valeur non prise en charge par l'API. Cet exemple est un peu artificiel, car nous n'avons pas réellement besoin de restreindre l'ID de catégorie à un nombre supérieur ou égal à six, mais uniquement pour démontrer les deux fonctions de rappel.

Le rappel de validation aura priorité. sur le rappel de désinfection. Dans notre exemple, si vous utilisez les deux callbacks et soumettez une valeur non valide ( <6 ) pour l'ID de catégorie, vous obtiendrez l'erreur Paramètre non valide: category_id ce qui ne donnera pas à la sanitize_callback () la chance d'être renvoyée et de désinfecter les données.

Veuillez noter que vous n'aurez peut-être pas besoin d'ajouter de validation ou de sanitisation, car le motif regex que vous utilisez la route peut être suffisante. Par exemple, dans notre cas, le ? P d + définit une URL qui accepte uniquement les nombres positifs. erreur

Restriction de l'accès aux points d'extrémité

Vous pouvez restreindre l'accès aux points d'extrémité à l'aide de la touche . permission_callback () qui vérifie si l'utilisateur dispose de l'autorisation requise pour effectuer l'action avant l'appel du rappel du gestionnaire principal. Cela vous permet d'indiquer au client les actions qu'il est capable d'effectuer sur une URL spécifique sans avoir à tenter d'abord de répondre à la demande.

La fonction permission_callback () doit renvoyer une valeur true ou false ou une instance. de la classe WP_Error .

Vous devez simplement passer la fonction permission_callback à la register_rest_route () qui vous permet d’ajouter des autorisations au contrôle. le point final. Par exemple:

 add_action ('rest_api_init', function () {

  register_rest_route ('mytwentyseventeentheme / v1', 'latest-posts / (? P   d +)', tableau (

      'méthodes' => 'GET',
      'callback' => 'get_latest_posts_by_category',
      'permission_callback' => function () {
          return current_user_can ('edit_posts');
      }

  ));

});

Le rappel des autorisations appelle la fonction current_user_can () pour vérifier si l'utilisateur est authentifié et dispose de la capacité requise ( edit_posts ) pour effectuer l'action. Donc, si le client n'est pas authentifié une erreur sera générée.

Si vous ne disposez pas des autorisations, vous obtiendrez une erreur rest_forbidden :

Nous pouvons également renvoyer true de la fonction permission_callback pour autoriser l'accès à tous sans authentification.

Utilisation du modèle de contrôle

. 19659005] Pour travailler avec des points de terminaison complexes, il est recommandé d'utiliser le modèle de contrôleur au lieu de définir des itinéraires personnalisés de la manière décrite dans l'exemple précédent.

Le modèle de contrôleur implique simplement l'extension du WP_REST_Controller intégré. qui implémente la fonctionnalité de base nécessaire au traitement des requêtes HTTP et vous permet de tirer parti d'un code robuste, utilisant les meilleures pratiques, utilisé par les points de terminaison WP-API intégrés

. En utilisant le modèle de contrôleur, vous devez utiliser le registre er_routes () pour enregistrer vos itinéraires personnalisés et la get_items () get_item () create_item () update_item () et delete_item () méthodes pour implémenter les requêtes GET, POST, PUT et DELETE.

Voyons maintenant un exemple simple en convertissant notre exemple précédent pour utiliser le modèle de contrôleur. Dans le fichier functions.php ajoutez:

 la classe Latest_Posts_Controller étend WP_REST_Controller {}.

Ensuite, vous devez implémenter la méthode register_routes () où vous souhaitez enregistrer vos itinéraires:

 class Latest_Posts_Controller étend WP_REST_Controller {
  fonction publique register_routes () {
    $ namespace = 'mytwentyseventeentheme / v1';
    $ path = 'latest-posts / (? P   d +)';

    register_rest_route ($ namespace, '/'. $ path, [
      array(
        'methods'             => 'GET',
        'callback'            => array( $this, 'get_items' ),
        'permission_callback' => array( $this, 'get_items_permissions_check' )
            ),

        ]);
    }
}

Nous appelons simplement la méthode intégrée register_rest_route () pour enregistrer un itinéraire pour une demande GET.

Vous devez remplacer la get_items_permissions_check () et . get_items () méthodes dans votre contrôleur:

 fonction publique get_items_permissions_check ($ request) {
    retourne vrai;
  }

Cette méthode vérifie les autorisations requises pour l'itinéraire. Nous retournons simplement true pour laisser tout le monde accéder à la route.

Ensuite, nous substituons la méthode get_items () :

 public function get_items ($ request) {

    $ args = array (
            'category' => $ request ['category_id']
    )

    $ posts = get_posts ($ args);


    if (vide ($ posts)) {

            return new WP_Error ('empty_category', 'il n'y a pas de publication dans cette catégorie', array ('status' => 404));
    }
    retourne le nouveau WP_REST_Response ($ posts, 200);
  }

Cette méthode est presque identique à notre fonction précédente get_latest_posts_by_category () .

Ce sont les deux méthodes que nous devons remplacer dans notre exemple. Dans des scénarios plus complexes, vous devez remplacer les autres méthodes pour créer un système CRUD entièrement opérationnel, à savoir le create_item () update_item () delete_item () et get_item () .

Enfin, nous devons créer une instance de notre Latest_Posts_Controller et l'appeler par sa register_routes () . méthode dans un crochet d'action rest_api_init :

 add_action ('rest_api_init', function () {
     $ latest_posts_controller = new Latest_Posts_Controller ();
    $ latest_posts_controller-> register_routes ();
}

Dans cet exemple simple, le modèle de contrôleur peut sembler peu utile, mais pour des scénarios plus complexes - par exemple, lorsque vous avez un type de publication personnalisé et que vous devez fournir une API RESTful personnalisée pour lire, créer, mettre à jour et supprimer éléments avec plusieurs itinéraires et points de terminaison - vous bénéficierez des concepts de la programmation orientée objet et du modèle de contrôleur pour mieux organiser votre code et tirer parti des classes existantes.

Conclusion

Dans ce didacticiel, nous avons vu comment créer votre propres itinéraires personnalisés pour WP-API. Cela vous permettra de créer des clients Web et mobiles pour votre site Web WordPress pouvant également interagir avec vos types de publication personnalisés pas seulement avec les types WordPress intégrés (tels que les publications et les catégories, etc.). ] Ahmed Bouchefra " class="avatar avatar-96 wp-user-avatar wp-user-avatar-96 alignnone photo"/>