L'API de réécriture les bases

Il s’agit de la première partie d’une série de deux articles consacrés à l’API Rewrite de WordPress. Dans ce didacticiel, nous examinons le fonctionnement des réécritures et les méthodes de base disponibles pour créer des règles de réécriture personnalisées..

Qu'est-ce que la réécriture??

WordPress, comme tous les systèmes de gestion de contenu, décide du contenu à afficher en fonction des variables (généralement appelées variables de requête) qui lui sont transmises. Par exemple: http://example.com/index.php?category=3 indique à WordPress que nous recherchons des publications dans une catégorie avec un ID de 3 et http://example.com/index.php?feed=rss indique à WordPress que nous voulons le flux du site au format RSS.

Malheureusement, cela peut nous laisser avec des URL plutôt laides:

http://example.com/index.php?post_type=portfolio&taxonomy=wordpress&portfolio=my-fancy-plugin

C'est ici qu'intervient la réécriture de WordPress. Elle nous permet de remplacer ce qui précède par:

http://example.com/portoflio/wordpress/my-fancy-plugin

Ce qui est maintenant non seulement beaucoup plus lisible (et mémorable) mais aussi plus convivial pour le référencement. Voilà, en un mot, ce que font les réécritures.

Comment ça marche?

À présent http://example.com/portoflio/wordpress/my-fancy-plugin n'existe pas en tant que répertoire ou fichier. Alors, comment WordPress diffuse-t-il le bon contenu? Lorsque WordPress reçoit un "joli lien permanent" comme ci-dessus, il doit le convertir en quelque chose qu’il comprend, à savoir un objet de requête. Plus simplement, il doit prendre la jolie URL et mapper les parties appropriées à la bonne variable de requête. Donc pour notre exemple:

http://example.com/portoflio/wordpress/my-fancy-plugin

Type de poste est réglé sur 'portfolio'
taxonomie de portefeuille est réglé sur 'wordpress'
portefeuille est réglé sur 'my-fancy-plugin' (le nom de l'article)

Alors WordPress sait que nous sommes après des posts de type 'portefeuille', dans le 'wordpress"taxonomie de portefeuille'terme de taxonomie avec nom'mon-fantaisie-plugin'. (Comme vous l'avez peut-être deviné, les deux premiers sont en réalité redondants). WordPress effectue ensuite cette requête, choisit le modèle approprié avec lequel afficher les résultats, puis le transmet au spectateur. Mais clairement, WordPress ne se contente pas de deviner comment interpréter les URL, il faut le savoir…

Cela commence par .htaccess

En supposant que vous puissiez et avez activé de jolis permaliens sur votre page Paramètres -> Permaliens (voir Codex pour la configuration minimale requise - pour WordPress sur les serveurs Nginx, ce plug-in existe) - .htaccess fichier. Il joue un rôle simple mais important. WordPress inclut quelque chose de similaire au suivant dans ce fichier:

 # COMMENCE WordPress  RewriteEngine sur RewriteBase / RewriteRule ^ index \ .php $ - [L] RewriteCond% REQUEST_FILENAME! -F RewriteCond% REQUEST_FILENAME! -D RewriteRule. /index.php [L]  # FIN WordPress

Ceci vérifie simplement si le fichier ou le répertoire existe réellement - et si tel est le cas, vous êtes simplement dirigé là. Par exemple:

http://example.com/blog/wp-content/uploads/2012/04/my-picture.png

Je vous prendrais simplement la pièce jointe PNG 'my-picture.png'. Mais, comme dans le cas de:

http://example.com/blog/portoflio/wordpress/my-fancy-plugin

Où le répertoire n'existe pas - vous êtes amené à votre WordPress ' index.php fichier. C'est ce fichier qui lance WordPress.

Interpréter l'URL

À ce stade, WordPress ne sait pas encore ce que vous recherchez. Après un certain chargement initial de WordPress et de ses paramètres, il lance le demande parse méthode du WP classe (située dans le class-wp.php fichier). C'est cette méthode qui prend la / portoflio / wordpress / my-fancy-plugin et le convertit en un objet requête compréhensible par WordPress (presque, il définit réellement la query_vars tableau et ensuite $ wp-> query_posts transforme cela en une requête).

En bref, cette fonction compare l’URL reçue (/ portoflio / wordpress / my-fancy-plugin) avec un tableau de 'expressions régulières'. C'est le réécrire le tableau - et cela ressemblera à quelque chose comme ça:

 category /(.+?)/ page /? ([0-9] 1,) /? $ => index.php? category_name = $ correspond [1] & paginé = $ correspond à [2] catégorie /(.+ ?) /? $ => index.php? category_name = $ correspond à la balise [1] / ([^ /] +) / page /? ([0-9] 1,) /? $ => index.php ? tag = $ correspond à [1] & paged = $ correspond à [2] tag / ([^ /] +) /? $ => index.php? tag = $ correspond à [1] ([0-9] 4) / ([0-9] 1,2) / ([0-9] 1,2) /? $ => Index.php? Année = $ correspondances [1] & monthnum = $ correspondances [2] & jour = $ correspond à [3] (. +?) (/ [0-9] +)? /? $ => index.php? nom_page = $ correspond à [1] & page = $ correspond à [2]

Les clés de ce tableau sont des expressions régulières et l'URL reçue est comparée l'une après l'autre jusqu'à ce qu'il y ait correspondance avec le modèle de l'URL reçu. La valeur correspondante est la façon dont l'URL est ensuite interprétée. le $ correspondances tableau contient les valeurs capturées (indexées à partir de 1) de la correspondance.

Par exemple, visiter www.example.com/blog/tag/my-tag, WordPress cherchera le premier motif qui correspondtag / mon-tag'. Avec le tableau ci-dessus, il correspond au troisième motif: tag / ([^ /] +) /? $. Cela indique à WordPress d'interpréter l'URL comme www.example.com/blog/index.php?tag=my-tag et en conséquence le 'mon tag'archive est servi.

Bien sûr, WordPress vous permet de personnaliser ce tableau, et le reste de ce tutoriel est consacré à vous montrer comment.

Personnalisation des règles de réécriture

Paramètres -> Permaliens

Votre première escale devrait être la page de paramètres «Permalink». Cette page vous permet de modifier les règles pour la valeur par défautposter'type de poste et'Catégorie' et 'Mots clés'taxonomies. L’option 'default' a de jolis permaliens désactivés, mais vous pouvez choisir dans une liste de structures prédéfinies ou créer une structure personnalisée. Veuillez noter que les structures personnalisées ne doivent pas contenir l'URL de votre site.. WordPress vous permet de modifier votre structure de permalien en ajoutant des balises fournies telles que %après le nom% (le nom de la poste), %année% (l'année de publication du message) et %auteur% (l'auteur du post). Une structure permalien telle que:

/% année% /% auteur% /% postname% /

Produirait un lien post tel que:

www.example.com/2012/stephen/my-post

La documentation de ces options se trouve dans le Codex WordPress. (Plus tard, je vous montrerai comment créer vos propres balises personnalisées).

Cependant, les options fournies sont assez limitées. Dans ce tutoriel, je me concentrerai sur les fonctions fournies par WordPress qui offrent un meilleur contrôle sur les structures de permalien et sur leur interprétation. Je ne traiterai pas des options de réécriture disponibles pour les types de publication personnalisés ou les taxonomies, car cela sera traité dans la partie 2..

Pourquoi effacer les règles de réécriture?

Après toute modification des règles de réécriture (par exemple, en appliquant l'une des méthodes suivantes ou en enregistrant un type de publication personnalisé ou une taxonomie), vous constaterez que les nouvelles règles ne prennent pas effet. En effet, vous devez vider les règles de réécriture. Cela peut être fait de deux manières:

Il suffit de visiter la page Paramètres -> Permalink
Appel flush_rewrite_rules () (couvert dans la partie 2)

Qu'est-ce que cela fait? Rappelons que le demande parse La méthode compare la demande à un tableau de réécriture. Ce tableau vit dans la base de données. Le vidage des règles de réécriture met à jour la base de données pour refléter vos modifications - et tant que vous ne le ferez pas, elles ne seront pas reconnues. Mais demande parse également écrit au .htaccess fichier. Cela en fait une opération coûteuse. Donc, même si je ne couvrirai pas l'utilisation de flush_rewrite_rules () jusqu'à la partie 2, je vous donnerai cet avertissement: Ne pas appeler flush_rewrite_rules à chaque chargement de page. Les plug-ins ne doivent appeler que lorsque le plug-in est activé ou désactivé.

Ajouter une règle de réécriture

le add_rewrite_rule vous permet d'ajouter des règles supplémentaires au tableau de réécriture. Cette fonction accepte trois arguments:

règle - une expression régulière avec laquelle comparer l'URL de la requête avec
récrire - la chaîne de requête utilisée pour interpréter la règle. le $ correspondances tableau contient les correspondances capturées et commence à partir de l'index '1'.
position - 'Haut' ou 'bas'. Où placer la règle: en haut du tableau de réécriture ou en bas. WordPress analyse du haut vers le bas et s’arrête dès qu’il trouve une correspondance. Pour que vos règles aient priorité sur les règles existantes, vous devez définir ce paramètre sur 'Haut'. La valeur par défaut est 'bas'.

Remarque: si tu utilises add_rewrite_rule plusieurs fois, chacun avec position 'Haut' - la premier appel a priorité sur les appels suivants.

Supposons que nos publications soient associées à une date d'événement et que nous souhaitons avoir cette structure: www.example.com/blog/the-olympics-begin/2012-07-27 interprété comme www.example.com/blog/index.php?postname=the-olympics-begin&eventdate=2012-07-27 alors nous pouvons ajouter cette règle comme suit:

 fonction wptuts_add_rewrite_rules () add_rewrite_rule ('^ ([^ /] *) / / [0-9] 4 - [0-9] 2 - [0-9] 2) /? $' / / Chaîne suivie d'une barre oblique, suivie d'une date sous la forme '2012-04-21', suivie d'une autre barre oblique 'index.php? Pagename = $ matches [1] & eventdate = $ matches [2]', 'top' )  add_action ('init', 'wptuts_add_rewrite_rules');

Ce qui suit interpréterait www.example.com/olympics/2012/rowing comme www.example.com/index.php?p=17&olymyear=2012&game=rowing

 add_rewrite_rule ('^ olympics / ([0-9] 4) / ([^ /] *)', 'index.php? p = 17 & olymyear = $ correspondances [1] & game = $ correspondances [2]', ' Haut' );

Si vous n'êtes pas sûr de vos expressions régulières, cette introduction et cet outil peuvent vous être utiles..

Ajouter une balise de réécriture

Vous pouvez penser que la valeur de date de l'événement (2012-07-27 dans l'exemple ci-dessus), olymyear et Jeu peut être accessible depuis les internes de WordPress via le get_query_var (de la même manière que get_query_var ('paginé') obtient le numéro de page sur lequel vous vous trouvez). Cependant, WordPress ne reconnaît pas automatiquement la variable date de l'événement même si cela est interprété comme une variable GET. Il existe plusieurs façons de faire en sorte que WordPress reconnaisse les variables personnalisées. On est d'utiliser le query_vars filtrer comme indiqué dans la section "Ajouter un point de terminaison personnalisé" ci-dessous. Alternativement, nous pouvons aller plus loin et utiliser add_rewrite_tag enregistrer une balise personnalisée comme celle par défaut %après le nom% et %année%

Cette fonction accepte trois arguments:

nom de tag - (avec% de début et de fin), par exemple: %date de l'événement%
regex - Expression régulière pour valider la valeur, par ex. '([0-9] 4 - [0-9] 2 - [0-9] 2)'
question - (facultatif) Comment la balise est interprétée, par ex. 'eventdate ='. Si fourni, doit se terminer par un '='.

 fonction wptuts_register_rewrite_tag () add_rewrite_tag ('% eventdate%', '(' 0-9] 4 - [0-9] 2 - [0-9] 2) ');  add_action ('init', 'wptuts_register_rewrite_tag');

Non seulement get_query_var ('date d'événement') renvoyer la valeur de la date dans l'URL, mais vous pouvez utiliser la balise %date de l'événement% dans les Paramètres -> Lien permanent (avec le paramètre par défaut %année%, %après le nom% etc.) et WordPress l'interprétera correctement. Malheureusement lors de la génération du lien permanent d'un article, WordPress ne sait pas comment le remplacer %date de l'événement% avec la valeur appropriée: nos post permaliens se terminent ainsi:

www.example.com/the-olympics-begin/%eventdate%

Nous devons remplacer %date de l'événement% avec une valeur appropriée, et nous pouvons le faire en utilisant le post_link filtre. (Dans cet exemple, je supposerai que la valeur est stockée dans un champ personnalisé 'date de l'événement').

 function wp_tuts_filter_post_link ($ permalink, $ post) // Vérifie si la balise% eventdate% est présente dans l'URL: if (false === strpos ($ permalink, '% eventdate%')) renvoie $ permalink; // Récupère la date de l'événement stockée dans post meta $ event_date = get_post_meta ($ post-> ID, 'eventdate', true); // Malheureusement, si aucune date n'est trouvée, nous devons fournir une "valeur par défaut". $ event_date = (! empty ($ event_date)? $ event_date: '2012-01-01'); $ event_date = urlencode ($ event_date); // Remplacez '% eventdate%' $ permalink = str_replace ('% eventdate%', $ event_date, $ permalink); return $ permalink;  add_filter ('post_link', 'wp_tuts_filter_post_link', 10, 2);

Dans la partie 2 de cette série, je couvrirai les balises personnalisées pour les types de publication personnalisés..

Ajouter un point de terminaison personnalisé

Les points finaux sont des balises qui sont ajoutées à l'URL (/ trackback / [valeur] est le plus commun). Il a plusieurs autres utilisations potentielles: affichage de modèles différents en fonction de la valeur définie, notifications personnalisées et affichage de messages dans différents "formats" (imprimable, XML, JSON, etc.)..

Vous pouvez créer des points de terminaison avec add_rewrite_endpoint. Cette fonction accepte deux arguments:

prénom - Le nom du noeud final, par exemple 'JSON','forme', etc.
où - Masque de noeud final spécifiant où le noeud final doit être ajouté. Ce doit être l'une des constantes EP_ * répertoriées ci-dessous (ou une combinaison utilisant des opérateurs au niveau des bits). Lorsque vous enregistrez des types de publication personnalisés, vous pouvez créer un masque pour ce type de publication:

Les masques de noeud final par défaut sont les suivants:

EP_PERMALINK - pour post permaliens
EP_ATTACHMENT - pour les pièces jointes
EP_DATE - pour les archives de date
EP_YEAR - pour les archives de l'année
EP_MONTH - pour les archives du mois
EP_DAY - pour 'jour' archives
EP_ROOT - pour la racine du site
EP_COMMENTS - pour les commentaires
EP_SEARCH - pour les recherches
EP_CATEGORIES - pour les catégories
EP_TAGS - pour les tags
EP_AUTHORS - pour les archives des publications de l'auteur
EP_PAGES - pour les pages
EP_ALL - pour tout

Les points finaux sont extrêmement flexibles. Vous pouvez les utiliser avec des opérateurs au niveau des bits. Par exemple, vous pouvez ajouter un point final à poster et des liens permanents de page avec EP_PERMALINK | EP_PAGES.

 fonction wptuts_add_endpoints () add_rewrite_endpoint ('myendpoint', EP_PERMALINK); // Ajoute un point final aux permaliens add_rewrite_endpoint ('anotherendpoint', EP_AUTHORS | EP_SEARCH); // Ajoute le point de terminaison aux URL des auteurs ou des résultats de recherche add_action ('init', 'wptuts_add_endpoints');

En résumé, les points de terminaison peuvent être utiles pour les soumissions de formulaires. Supposons que nous ayons une page de formulaire de contact avec le nom formulaire de contact et avec permalien: www.example.com/contact et veulent les URL:

www.example.com/contact/submission/success - pour refléter une soumission de formulaire réussie
www.example.com/contact/submission/error - refléter une soumission de formulaire infructueuse

Cela peut être fait avec les points finaux. Voici un exemple très simple d'utilisation des points de terminaison. Le formulaire est donc incroyablement basique dans ses vérifications (et ne fait en réalité rien avec les données). Normalement, un formulaire comme celui-ci fonctionnerait mieux dans un plug-in, en utilisant des codes abrégés - mais pour les besoins de cet exemple, créez une page avec le modèle suivant et le reste du code que vous pouvez insérer dans votre code. functions.php

  Mon formulaire de contact simple 
   Votre message a été envoyé! 
   Oops! Il semble y avoir eu une erreur… 
     Votre message:        Confirmation de l'émail:

(Au cas où vous vous le demanderiez, le miel fait référence à cette méthode très basique d'attraper le spam décrite ici. Ce n'est certainement pas infaillible, mais le traitement approprié du formulaire et la protection anti-spam sont hors sujet ici). Maintenant, nous créons notre point final:

 fonction wptuts_add_endpoint () add_rewrite_endpoint ('form', EP_PAGES);  add_action ('init', 'wptuts_add_endpoint');

Ensuite nous ajoutons notre 'forme'variable au tableau de variables reconnues:

 fonction wptuts_add_queryvars ($ query_vars) $ query_vars [] = 'form'; return $ query_vars;  add_filter ('query_vars', 'wptuts_add_queryvars');

Enfin, nous fournissons un gestionnaire de formulaire, qui traitera les données, soumettra le formulaire, puis redirigera vers la page de contact avec la valeur de point de terminaison pertinente ajoutée..

 function wptuts_form_handler () // Voulons-nous traiter le formulaire if (! isset ($ _POST ['action']) || 'wptuts_send_message'! = = _POST ['action']) return; // ID de la page du formulaire de contact $ form_id = 2163; $ redirect = get_permalink ($ form_id); // Vérifier les données $ data = $ _POST ['wptuts_contact']; if (! isset ($ _ POST ['wptuts_contact_nonce']) ||! wp_verify_nonce ($ _ POST ['wptuts_contact_nonce'], 'wptuts_send_message')) // Echec de la non-vérification de la vérification $ redirect. = 'formulaire / erreur'; wp_redirect ($ redirect); sortie();  if (! empty ($ data ['confirmation']))) // Abeilles dans le miel… $ redirect. = 'formulaire / erreur'; wp_redirect ($ redirect); sortie();  // Santize et valider les données, etc. // Ensuite, faites quelque chose avec les données assainies // Succès! $ redirect. = 'form / success'; wp_redirect ($ redirect); sortie();  add_action ('init', 'wptuts_form_handler');

Bien sûr, même cet exemple pourrait être grandement amélioré en fournissant des messages d'erreur plus détaillés indiquant le motif de l'échec..

Ajout d'un flux personnalisé

Avec de jolis permaliens activés, WordPress crée automatiquement de jolies URL pour le flux de votre site: www.example.com/feed/rss. le add_feed Cette fonction vous permet de créer un flux personnalisé qui, si de jolis permaliens sont activés, aura également une "jolie" URL. Cette fonction accepte deux arguments:

nom du fil - Le nom du flux tel qu’il apparaîtra dans flux / [nom du flux]
rappel de flux - La fonction responsable de l'affichage du contenu du flux.

Ce qui suit est destiné à servir d’exemple de add_feed, et fournit un flux personnalisé très basique.

 function wptuts_events_feed_callback () $ custom_feed = new WP_Query (array ('meta_key' => 'eventdate')); header ('Content-Type:'. feed_content_type ('rss-http'). '; charset = ". get_option (" blog_charset "), true); écho ''; ?>   Mon flux personnalisé     have_posts ()):?> have_posts ()): $ custom_feed-> the_post (); ?>  <?php the_title_rss() ?>    ]]>       Après avoir nettoyé les permaliens, l’alimentation sera disponible à www.example.com/feed/events.
 
 Vérification des règles de réécriture
 Une fois que vous avez ajouté certaines de vos propres règles de réécriture (et les avez supprimées), vous voudrez probablement vérifier si elles fonctionnent correctement - et si elles ne le sont pas, découvrez ce qui ne va pas. Pour cela, j'ai fortement recommandé le plug-in Monkeyman Rewrite Analyzer, un plug-in gratuit disponible dans le référentiel WordPress. Une fois activé, ce plug-in ajoute une page à votre section "Outils", qui répertorie toutes vos règles de réécriture..
  Vous pouvez également tester les règles en lui donnant un exemple d'URL. Le plug-in filtrera les règles afin d'afficher uniquement les modèles correspondants et en indiquant comment WordPress interpréterait l'URL..
  Amusez-vous et gardez un œil sur la partie 2, à venir!
  Remarque: il existe actuellement un bogue dans notre surligneur de syntaxe qui affiche "vide()"comme"emptyempty ()". N'oubliez pas d'ajuster votre code en conséquence.
 



		
			
	   
	




Code