Quand vous développez un thème ou une extension, vous avez souvent envie d’écrire des URL dans votre code. Par exemple, dans une extension vous pouvez avoir besoin d’utiliser vos propres fichiers CSS et dans un thème vous voudrez surement faire un lien vers la page d’accueil dans l’en-tête.

Il peut être tentant d’écrire simplement l’URL comme on le ferait sur un site statique mais c’est une mauvaise idée. Dans ce tutoriel je vous expliquerais pourquoi vous ne devez pas le faire et je vous montrerais les fonctions à utiliser pour créer des URL dynamiques.

Pourquoi vous ne devez pas écrire vos URL en dur dans vos thèmes et extensions

Commençons par les thèmes. Si vous développez un thème pour l’utiliser sur un site en particulier, cela peut sembler correct d’ajouter le nom de domaine de ce site dans les fichiers du thème mais il y a quand même quelques risques et inconvénients :

• Si vous décidez de changer le nom de domaine du site vous devrez modifier toutes les URL que vous avez écrit en dur.
• Si vous travaillez sur une version de développement du site que vous transférerez sur un serveur de production vous devrez changer toutes ces URL.
• Si vous souhaitez utiliser ce thème sur un autre site, vous aurez à éditer toutes ces URL.
• Si vous décidez de partager votre thème, ça ne fonctionnera pas.
• Si vous utilisez ce thème comme thème de base pour un autre thème que vous développez, vous devrez modifier ces URL.
• Si votre site est dans un sous-dossier de votre domaine mais que vous avez dit à WordPress d’utiliser le répertoire parent pour l’URL vos URL écrites en dur pourraient pointer vers le mauvais endroit.
• Si vous oubliez de faire une des étapes précédentes votre site sera plein d’erreurs 404 et les liens vers les images ou les feuilles de styles seront brisés.

Alors ne le faites pas!

Mais les extensions alors? C’est encore plus risqué. C’est assez courant de développer un thème uniquement pour un site mais la plupart des extensions seront utilisées sur plusieurs sites. Il est peu probable que vous ayez écrit en dur une URL complète dans une extension, mais vous pourriez avoir envie d’utiliser une fonction pour récupérer l’URL du site et ensuite écrire le chemin d’accès au dossier de l’extension. Encore une fois, c’est risqué :

• Si votre extension est déplacée dans un autre dossier alors tous les liens seront brisés.
• Si votre extension est installée dans un réseau Multisite qui utilise une ancienne version de WordPress, vos liens seront brisés.
• Si votre extension est installée sur un site utilisant une arborescence de fichiers différente de celle que vous avez utilisé pour vos URL, encore une fois les liens seront brisés.

Toutes ces raisons peuvent faire que votre extension ne fonctionne pas du tout.

Donc, que faire pour éliminer les URL écrites en dur dans WordPress?

Les fonctions à utiliser à la place des URL écrites en dur

Il existe une multitude de fonctions WordPress que vous pouvez utiliser pour éviter ces URL. Je vais les regrouper dans cinq catégories :

• les fonctions pour récupérer la page d’accueil du site
• les fonctions pour récupérer le lien vers d’autres page de la partie publique (les articles, les pages, les fichiers joints et les archives)
• les fonctions pour récupérer les URL des pages de la partie administration
• les fonctions pour récupérer les URL des fichiers de votre extension et des répertoires de votre thème
• les fonctions pour récupérer les feuilles de styles et les scripts

Débutons par les fonctions qui récupèrent et affichent un lien vers la page d’accueil.

Récupérer l’URL de la page d’accueil

Les marqueurs de modèle suivants récupèrent ou affiche l’URL de la page d’accueil de votre site :

• bloginfo( 'url' ) : affiche l’URL de la page d’accueil comme spécifiée dans les Réglages généraux de l’interface d’administration.
• get_bloginfo( 'url' ) : récupère l’URL du site sans l’afficher.
• home_url() : récupère l’URL de la page d’accueil sans l’afficher : utilisez echo esc_url( home_url( '/' ) ); pour afficher l’URL de la page d’accueil avec un slash à la fin. Cette fonction prend deux paramètres : $path si vous voulez ajouter un chemin vers une page spécifique ou ajouter un slash à la fin, et $scheme pour spécifier le format de l’URL (http, https ou relative).
• get_home_url() récupère l’URL de la page d’accueil et supporte le Multisite : vous pouvez inclure l’ID du blog comme paramètre.
• site_url() : l’URL où est stocké WordPress, donc si votre installation de WordPress est dans le sous dossier wordpress, la fonction renvoie : http://mysite.com/wordpress.
• get_site_url() : récupère l’URL du site sans l’afficher. Peut être utilisé avec des paramètres pour afficher l’URL d’un site dans un réseau Multisite, ajouter un chemin et utiliser un format spécifique.
• network_home_url() : l’URL de la page d’accueil du site principal du réseau Multisite, utile si vous voulez inclure un lien vers le site principal dans le pied de page de chaque site du réseau.
• network_site_url() : l’URL du site principal du réseau Multisite.

Comme vous pouvez le voir, il y a plusieurs modèles que vous pouvez utiliser pour afficher l’URL. Laquelle utiliser dépend de plusieurs critères :

• Voulez-vous seulement récupérer l’URL ou l’afficher?
• Voulez-vous ajouter un chemin après l’URL de la page d’accueil? (vous pouvez éviter cela dans la plupart des cas en utilisant une fonction de la section suivante.)
• Voulez-vous spécifier le format?
• Voulez-vous récupérer l’URL de la page d’accueil ou celle du site, si elles sont différentes?
• Voulez-vous récupérer l’URL d’un site dans un réseau Multisite?

Vous devez utiliser une de ces fonctions dans les fichiers de votre thème lorsque vous voulez insérer un lien vers la page d’accueil, par exemple si le logo dans l’en-tête de votre site renvoie vers la page d’accueil. Il y a aussi des cas dans lesquels l’extension aura besoin de récupérer ou d’afficher l’URL de la page d’accueil.

Récupérer les URL d’autres pages de la partie publique

Comme pour l’URL de la page d’accueil, vous aurez besoin d’avoir le lien vers d’autres pages de votre site. Cela inclus les pages, les articles, les fichier joints et les custom post types. Voici les fonctions que vous pouvez utiliser :

• post_permalink() affiche le lien vers un article, avec l’ID de l’article comme paramètre.
• get_page_link() récupère (mais n’affiche pas) le lien vers une page, avec l’ID de la page comme paramètre.
• get_permalink() récupère (mais n’affiche pas) le lien permanent vers un article ou un page, avec l’ID de l’article ou de la page en paramètre.
• get_category_link() récupère le lien vers les archives d’une catégorie, avec l’ID de la catégorie en paramètre.
• get_tag_link() récupère le lien vers les archives d’un tag, avec l’ID du tag en paramètre.
• get_post_type_archive_link() récupère le lien vers les archives d’un post type, avec le post type en paramètre.
• get_term_link() récupère le lien vers un terme de taxonomie, avec le terme et la taxonomie en paramètres.
• the_attachment_link() affiche le lien vers un fichier joint, avec l’ID du fichier joint comme premier paramètre. Utilisez les autres paramètres pour définir les dimensions de l’image et si le lien doit mener au fichier lui-même ou vers sa page.
• get_attachment_link() récupère le lien vers un fichier joint, avec l’ID du fichier en paramètre.
• wp_get_attachment_link() récupère aussi le lien vers un fichier joint, mais vous permet d’affiche l’image si le fichier est une image aux dimensions que vous spécifiez.
• get_search_link() récupère le lien vers la page de recherche. Vous pouvez définir une requête en paramètre, ou la laisser vide.

Récupérer des URL de la partie administration

Si vous créez une extension ou un thème avec des écrans de paramétrage dans la partie administration de WordPress, ou si vous modifiez des écrans d’administration, vous pourrez vouloir ajouter des liens vers les écrans administration. Encore une fois, vous ne devriez pas écrire vos URL en dur mais utiliser un de ces modèles :

• admin_url() récupère (mais n’affiche pas) une URL de l’administration.  Vous devez inclure le chemin vers l’URL en tant que paramètre et pouvez aussi inclure un format. Par exemple, pour affiche l’URL de la page de création d’un nouvel article, vous utiliserez echo admin_url( 'post-new.php' );.
• get_admin_url() est similaire à admin_url() mais supporte les réseaux Multisite : vous pouvez inclure l’ID du blog en paramètre.
• edit_post_link() affiche un lien vers la page d’édition d’un article. Cette fonction peut être utilisé dans la boucle ou à l’extérieur de la boucle avec l’ID de l’article en paramètre.
• get_edit_post_link() récupère le lien vers la page d’édition d’un article avec l’ID de l’article en paramètre.

Récupérer des fichiers dans les dossiers de votre extension ou thème

Comme pour les URL de la partie publique ou d’administration, vous devez aussi utiliser des chemins corrects vers les fichiers dans les dossiers de votre extension ou thème.

Premièrement, voici les fonctions à utiliser dans les fichiers de votre thème :

• get_stylesheet_directory() récupère le chemin complet sur le serveur (pas l’URL) du dossier du thème actuel de votre site. Utilisez cette fonction pour inclure vos fichiers plutot que vous afficher des liens.
• get_stylesheet_directory_uri() récupère l’URL pour le thème actif, sans slash à la fin. Utilisez la dans les fichiers de template pour récupérer des ressources enregistrées dans le dossier de votre thème : par exemple, pour afficher une image enregistrée dans le dossier des images de votre thème, utilisez <img src="<?php echo get_stylesheet_directory_uri(); ?>/images/logo.jpg">.
• get_bloginfo( 'stylesheet_directory' ) récupère l’URL du thème actif : utiliser get_stylesheet_directory_uri() est plus correct.
• get_template_directory_uri() est similaire à  get_stylesheet_directory_uri() mais, si vous utilisez un thème enfant, récupère l’URL du thème parent. De la même manière, get_template_directory()fonctionne de la même manière que get_stylesheet_directory() mais pour le thème parent.

Il y a aussi des fonctions à utiliser dans les fichiers d’extension :

• plugins_url() récupère l’URL absolue vers le dossier des extensions (sans le slash à la fin). Elle prend deux paramètres optionnels : le chemin à ajouter à la fin de l’URL et l’extension à laquelle l’URL fait référence.
• plugin_dir_url() récupère l’URL pour le dossier dans lequel est un fichier (avec un slash à la fin), avec ce fichier en paramètre. Normalement vous utilisez __FILE__ en paramètre pour spécifier le fichier courant.

Voici un exemple pour chacune des fonctions ci-dessus. Premièrement, pour récupérer l’URL d’un fichier dans le dossier de l’extension courante :

Et pour récupérer la même URL en utilisant plugin_dir_url() :

Notez qu’avec le deuxième exemple vous devez afficher le chemin : je préfère la première. N’oubliez pas que la deuxième renvoie le slash à la fin mais pas la première.

Récupérer les feuilles de style et les scripts

Vous ne devez jamais écrire en dur les liens vers les feuilles de style et les scripts dans les templates de vos thèmes ou vos extensions : à la place utiliser une fonction et attachez la au bon hook. Cela évite les problèmes avec des fichiers déplacés, vous assure que vous utilisez le bon script sans duplication et c’est aussi plus efficace.

Pour appeler une feuille de style, utilisez wp_register_style() et wp_enqueue_style() dans une fonction et attachez la au hook wp_enqueue_scripts. La fonction ci-dessous le fait :

Notez que j’ai utilisé __FILE__, qui signifie à WordPress que le chemin vers la feuille de style est relative au fichier courant.

Appeler un script est similaire, mais utiliser wp_register_script() et wp_enqueue_script() dans votre fonction et attachez la au hook wp_enqueue_scripts. L’exemple ci-dessous enregistre un nouveau script et l’appelle :

Si votre script utilise un script fourni par WordPress, comme jQuery, vous devez l’enregistrer; ajouter le à la pile comme ceci :

Apprenez en plus sur les hook wp_enqueue_scripts dans ce tutoriel sur ajouter du JavaScript et du CSS dans vos thèmes et extensions.

Résumé

J’espère vous avoir convaincu que les URL écrites en dur dans WordPress sont une mauvaise idée : cela peut mener à toutes sortes de problèmes dans le future et est moins efficace. Suivant la cible de votre lien WordPress vous fournit une fonction pour remplacer toute URL écrite en dur dans vos thèmes et extensions. Vous pouvez utiliser des fonctions et des marqueurs de modèles pour faire des liens vers les pages de la partie publique de votre site, comme la page d’accueil, vers des écrans de la partie administration de WordPress et vers les fichiers de vos vues ou extensions.

Sources