Création de points de terminaison personnalisés pour l’API REST WordPress – SitePoint – Gratuit : Audit complet de votre site internet

Avant de commencer !

Création du dossier de thème enfant
Share on facebook
Share on twitter
Share on pinterest

Ce didacticiel sur l’API REST WordPress vous guide à travers la création d’un point de terminaison WP-API personnalisé. Nous allons d’abord créer un thème enfant par défaut « Vingt-dix-sept » thème, ce qui nous permettra d’ajouter des fonctionnalités à notre thème, puis de procéder à l’enregistrement de notre point de terminaison API personnalisé.

L’API WordPress REST vous offre plus qu’un simple ensemble de routes intégrées. Vous pouvez également créer des itinéraires et des points de terminaison personnalisés à l’aide des mêmes API que celles utilisées pour créer des itinéraires par défaut (par exemple, register_rest_route() fonction et WP_Rest_Controller classe, 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 ça twentyseventeen-child:

cd /var/www/html/wp-content/themes
mkdir twentyseventeen-child

Création du dossier de thème enfant

Créez ensuite un style.css fichier:

touch style.css

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

/*
 Theme Name:  Twenty Seventeen Child Theme
 description: A child theme of the Twenty Seventeen WordPress theme
 Author:       Ahmed Bouchefra
 Template:     twentyseventeen
 Version:      1.0.0
*/

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

Aller à Apparence -> Thèmes dans l’admin WordPress et choisissez votre thème enfant:

Choisir votre thème enfant WordPress dans la section Thèmes WordPress

Ensuite, cliquez sur le Activer bouton pour activer votre thème enfant:

Le bouton Activer

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

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

Nous voulons créer un nouvel itinéraire qui nous permettra de récupérer les derniers messages récents par ID de catégorie au 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 n'a été trouvé correspondant à l'URL et à la méthode de demande":

Message d'erreur 404

C'est parce que nous n'avons pas réellement cette route. Changeons ça!

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

add_action('rest_api_init', function () {
  register_rest_route( 'mytwentyseventeentheme/v1', 'latest-posts/(?Pd+)',array(
                'methods'  => 'GET',
                'callback' => 'get_latest_posts_by_category'
      ));
});

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

  • un espace de noms, mytwentyseventeentheme/v1
  • un chemin de ressource avec une expression régulière pour attraper l'ID de catégorie, latest-posts/(?Pd+)
  • un tableau d'options où nous spécifions la méthode GET et un get_latest_posts_by_category() fonction de rappel qui gère la demande.

Un espace de noms permet à deux plugins ou thèmes d'utiliser les mêmes chemins d'accès sans conflit et aux clients de détecter la prise en charge de votre API personnalisée en utilisant simplement le /wp-json/wp/v2 API et vérification de la espaces de noms champ.

Définition des espaces de noms

Vous pouvez voir sur la capture d'écran, le mytwentyseventeentheme/v1 l'espace de noms que nous avons utilisé pour notre itinéraire personnalisé est ajouté au espaces de noms (cette capture d'écran est prise après la mise en œuvre complète de notre point de terminaison personnalisé; veuillez continuer ci-dessous).

Remarquez le ?Pd+ partie. Cela nous permettra de récupérer l'ID de catégorie de la demande actuelle. Il s'agit simplement d'une expression régulière, vous pouvez donc utiliser une logique d'expression régulière normale pour créer n'importe quel 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. Mais nous obtenons toujours un 500 erreur avec le "Le gestionnaire de l'itinéraire n'est pas valide" message.

Erreur de route 500 non valide

Après avoir enregistré l'itinéraire personnalisé et spécifié le get_latest_posts_by_category() fonctionner comme le rappel qui sera appelé pour le traitement et le traitement de la demande GET, implémentons-la réellement:

function get_latest_posts_by_category($request) {

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

    $posts = get_posts($args);
    if (empty($posts)) {
    return new WP_Error( 'empty_category', 'there is no post in this category', array('status' => 404) );

    }

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

    return $response;
}

Nous récupérons d'abord le category_id argument de la $request paramètre par accès direct. Ensuite, nous créons un $args tableau avec le category clé définie sur la valeur category_id qui sera extrait de l'itinéraire.

Nous appelons ensuite le get_posts() pour 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 composé d'un empy_category code, un there is no post in this category message et code d'état 404 - qui sont tous transmis au constructeur du WP_Error classe.

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

Le résultat d'une catégorie vide

Nous créons enfin une nouvelle instance de la WP_REST_Response classe; on passe dans le $posts tableau; nous définissons le code d'état 200; et nous renvoyons la réponse REST. Nous pouvons également retourner directement le $posts tableau et il sera automatiquement converti en JSON.

le WP_Error et WP_REST_Response Les classes sont utilisées pour 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 articles appartenant à la catégorie d'ID 1.

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

Vous pouvez définir des arguments pour chaque route sous forme de tableau avec le paramètre args option comme la callback option. 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, comme sanitize_callback ou validate_callback.

  • validate_callback est une fonction de rappel pour valider l'argument. Il prend 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 filtrer la valeur de l'argument avant de le passer à la main callback une fonction. La valeur est passée en paramètre à cette fonction.

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

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

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

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

Une erreur de paramètre non valide

La désinfection vous permet de nettoyer les paramètres. Pour nettoyer les données, vous devez utiliser le sanitize_callback() fonctionner 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 renvoyons simplement six. De cette façon, nous nous assurons de n'obtenir 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 en fait pas besoin de restreindre l'ID de catégorie à six ou plus, mais juste pour démontrer les deux fonctions de rappel.

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

Veuillez noter que vous n'aurez peut-être pas besoin d'ajouter de validation ou de nettoyage, car le modèle d'expression régulière que vous utilisez dans l'itinéraire peut être suffisant. Par exemple, dans notre cas, le ?Pd+ définit une URL qui n'accepte que des nombres positifs. Toute autre entrée lancera "Le gestionnaire de l'itinéraire n'est pas valide" Erreur.

Gestionnaire d'itinéraire non valide

Restreindre l'accès aux points de terminaison

Vous pouvez restreindre l'accès aux points de terminaison à l'aide du permission_callback() , qui vérifie si l'utilisateur a l'autorisation requise pour effectuer l'action avant l'appel du rappel du gestionnaire principal. Cela vous permet de dire au client quelles actions il est capable de faire sur une URL spécifique sans avoir à tenter au préalable la demande.

le permission_callback() doit renvoyer une valeur vraie ou fausse ou une instance de la WP_Error classe.

Il vous suffit de passer le permission_callback à la register_rest_route() , qui vous permet d'ajouter des autorisations qui contrôlent l'accès au point de terminaison. Par exemple:

add_action('rest_api_init', function () {

  register_rest_route( 'mytwentyseventeentheme/v1', 'latest-posts/(?Pd+)',array(

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

  ));

});

Le rappel des autorisations appelle le current_user_can() pour vérifier si l'utilisateur est authentifié et dispose des capacités requises (edit_posts) pour faire l'action. Donc, si le client n'est pas authentifié, une erreur sera levée.

Si vous ne disposez pas des autorisations, vous obtiendrez un rest_forbidden Erreur:

Une erreur rest_forbidden

Nous pouvons aussi simplement revenir true du permission_callback fonction pour permettre l'accès à tout le monde sans aucune authentification.

Utilisation du modèle de contrôleur

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 comme nous l'avons vu dans l'exemple précédent.

Le modèle de contrôleur implique simplement d'étendre la fonction intégrée WP_REST_Controller , qui implémente les fonctionnalités de base nécessaires à la gestion des requêtes HTTP et vous permet de bénéficier d'un code robuste, avec 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 register_routes() pour enregistrer vos itinéraires personnalisés et 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 functions.php ajout de fichier:

class Latest_Posts_Controller extends WP_REST_Controller {}

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

class Latest_Posts_Controller extends WP_REST_Controller {
  public function register_routes() {
    $namespace = 'mytwentyseventeentheme/v1';
    $path = 'latest-posts/(?Pd+)';

    register_rest_route( $namespace, "https://www.sitepoint.com/" . $path, [
      array(
        'methods'             => 'GET',
        'callback'            => array( $this, 'get_items' ),
        'permission_callback' => array( $this, 'get_items_permissions_check' )
            ),

        ]);     
    }
}

Nous appelons simplement le intégré register_rest_route() pour enregistrer un itinéraire pour une demande GET.

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

  public function get_items_permissions_check($request) {
    return true;
  }

Cette méthode vérifie les autorisations requises pour l'itinéraire. Nous revenons simplement vrai pour permettre à tout le monde d'accéder à l'itinéraire.

Ensuite, nous remplaçons le get_items() méthode:

  public function get_items($request) {

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

    $posts = get_posts($args);


    if (empty($posts)) {

            return new WP_Error( 'empty_category', 'there is no post in this category', array( 'status' => 404 ) );
    }
    return new WP_REST_Response($posts, 200);
  }

Cette méthode est presque la même que notre précédente get_latest_posts_by_category() une fonction.

C'est ça! 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 pleinement opérationnel, c'est-à-dire create_item(), update_item(), delete_item() et get_item() méthodes.

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

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 ne pas sembler très 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 des éléments avec plusieurs routes et points de terminaison - vous bénéficierez des concepts OOP 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 vos propres itinéraires personnalisés pour WP-API. Cela vous permettra de créer des clients mobiles et Web pour votre site Web WordPress qui peuvent également interagir avec vos types de publication personnalisés, pas seulement les types WordPress intégrés (tels que les publications et les catégories, etc.).

Inscris-toi à notre newsletter !

Partage cet article avec tes amis !

Share on facebook
Share on google
Share on twitter
Share on linkedin