25.2 Quelques fonctions utiles

Langage PHP

Pour développer un thème ou une extension WordPress, vous devez coder en PHP. Ce langage met à votre disposition une foule de fonctionnalités pour :

• poser des conditions, faire des boucles ( ex : if, while, for, foreach )
• effectuer des opérations (ex : comparaison ( == ), assignation ( = ), concaténation ( . ), addition (+ ) )
• envoyer du texte au navigateur ( ex : echo )
• manipuler les chaînes de caractères ( ex : substr(), str_replace(), md5(), addslashes(), explode() )
• manipuler des dates ( ex : getdate(), dateformat() )
• manipuler des tableaux ( ex : array(), count(), sort() )
• manipuler les URL ( ex : parse_url(), urlencode() )
• etc.

Fonctions spécifiques à WordPress

Vous aurez en plus accès aux fonctions spécifiques à WordPress, dont voici un petit échantillon.

• get_bloginfo() et bloginfo() : informations générales sur le site Web. La première permet de manipuler ces informations alors que la seconde les affiche directement dans le navigateur.

  Ex :

  WordPress (PHP)

  <?php 

     $blog_title = get_bloginfo( 'name' );   // retient l'info qui a été entrée comme nom du site Web

  ?>

  WordPress (PHP)

  <h1><?php bloginfo( 'name' ); ?></h1> 

• get_site_url() et site_url() : retrouver ou afficher l'URL du site Web, tel que codé dans le panneau de configuration sous « Adresse web de WordPress ». On utilisera site_url() lorsqu'on a besoin d'accéder à des fichiers comme les feuilles de style, le JavaScript, les images, etc.

  WordPress (PHP)

  $url = get_site_url();   // retient l'URL du site pour accéder à un fichier, sous le format https://mondomaine.com

• get_home_url() et home_url() : retrouver ou afficher l'URL du site Web, tel que codé dans le panneau de configuration sous « Adresse web du site ». On utilisera home_url() lorsqu'on a besoin d'accéder à des articles, à des pages, à des archives, etc.

  WordPress (PHP)

  $url = get_home_url();   // retient l'URL du site pour naviguer vers une page, sous le format https://mondomaine.com

  Attention : dans la majorité des sites WordPress, l'adresse web du site sera la même que l'adresse web de WordPress. Donc, get_site_url() retournera la même information que get_home_url(). Vous devez donc vérifier quel type d'information vous souhaitez retrouver afin de vous assurer que votre code fonctionnera correctement si ces deux informations étaient différentes.

  

• admin_url() : retrouver l'URL de la page d'administration du site Web. L'URL se termine par une barre oblique.

  WordPress (PHP)

  $adminUrl = admin_url();   // Ex : https://mondomaine.com/wp-admin/

  Note : il existe également la fonction get_admin_url(). Mais contrairement au modèle retrouvé dans les autres fonctions, la différence entre admin_url() et get_admin_url() ne se situe pas au niveau de l'affichage. get_admin_url() est conçue pour être utilisée dans le contexte d'une installation WordPress multisites. Elle reçoit comme premier paramètre l'id du site pour lequel on désire retrouver l'URL de la page d'administration.

• Constante ABSPATH : retrouver le dossier racine du site Web. Attention : il s'agit d'un chemin et non d'un URL.

  WordPress (PHP)

  require_once( ABSPATH . 'wp-admin/includes/image.php' );

• get_the_title() et the_title() : retrouver ou afficher le titre d'un article ou d'une page.

  WordPress (PHP)

  $parent_title = get_the_title( $post->post_parent );

• get_the_content() et the_content() : retrouver ou afficher le contenu d'un article ou d'une page.

  WordPress (PHP)

  $content = get_the_content( 'Read more' );

• plugin_dir_path() : retrouver le dossier d'un fichier. Le nom porte à confusion car la fonction peut être utilisée pour retrouver le dossier de n'importe quel fichier, qu'il fasse partie d'une extension (plugin) ou pas.

  Attention : plugin_dir_path() ne retourne pas un URL. Cette fonction retourne le chemin du fichier sur le serveur avec une barre oblique à la fin.

  Exemple pour un site en développement : C:\Program Files\AMPPS\www\monsiteweb\wp-content\plugins\monextension/

  Exemple pour un site en ligne : C:\inetpub\wwwroot\monsiteweb\wp-content\plugins\monextension/

  On passera généralement en paramètre une constante PHP spéciale nommée __FILE__. Cette constante fait référence au fichier dans lequel l'instruction est inscrite.

  Dans cet exemple, le code doit faire un require_once sur un fichier placé dans le même dossier que le fichier contenant cette instruction.

  WordPress (PHP)

  require_once plugin_dir_path( __FILE__ ) . 'monfichier.php';

• get_template_directory() : retrouver le dossier du thème. Dans le cas où le site WordPress utilise un thème enfant, get_template_directory() retournera le dossier de son thème parent.

  Ici encore, ce n'est pas un URL.

  Attention : get_template_directory() n'ajoute pas de barre oblique à la fin du chemin. De plus, la valeur de retour contient un mélange de barres obliques et de barres obliques inverses.

  Ex : C:\Program Files\www\monsiteweb\wp-content\themes\twentysixteen

  WordPress (PHP)

  require_once( get_template_directory() .'/framework/lib/models.php' );

  Attention : lorsque vous recherchez des extraits de code sur le Web, vous verrez parfois l'utilisation de la constante TEMPLATEPATH. Ceci est à éviter car cette constante est obsolète. Il faut remplacer cette constante par un appel à get_template_directory() ou, si vous désirez retrouver le dossier du thème enfant, get_stylesheet_directory().

• get_stylesheet_directory() : retrouver le dossier du thème et ce, même s'il s'agit d'un thème enfant. On obtiendra un chemin et non un URL.

  Autrement dit, get_template_directory() et get_stylesheet_directory() retourneront la même chose lorsqu'un thème parent est activé mais retourneront des dossiers différents lorsqu'un thème enfant est activé : dossier du thème parent pour get_template_directory() et dossier du thème enfant pour get_stylesheet_directory().

  WordPress (PHP)

  $feuilleDeStyle = get_stylesheet_directory() . '/style.css';

• plugins_url() : retrouver l'URL du dossier des extensions.

  WordPress (PHP)

  $urlExtensions = plugins_url();   // retient un URL sous la forme https://mondomaine.com/wp-content/plugins

  Il est également possible de retrouver l'URL pour une extension en particulier. On utilisera généralement la constante __FILE__ pour retrouver l'URL de l'extension dans laquelle on est en train de travailler. Dans l'exemple suivant, on obtiendra une balise sous la forme <img src="http://mondomaine.com/wp-content/plugins/monextension/images/ajout.png" ... />.

  WordPress (PHP)

  <img src="<?php echo plugins_url('images/ajout.png', __FILE__) ?>" ... />

• get_template_directory_uri() : retrouver l'URL du thème. Dans le cas ou un thème enfant est activé, get_template_directory_uri() retournera l'IURL de son thème parent.

  WordPress (PHP)

  $path = get_template_directory_uri();   // retient une chaîne sous la forme https://mondomaine.com/wp-content/themes/twentyfourteen

• get_stylesheet_directory_uri() : retrouver l'URL du thème et ce, même s'il s'agit d'un thème enfant.

  On retrouve la même logique entre get_stylesheet_directory_uri() et get_template_directory_uri() qu'entre get_stylesheet_directory() et get_template_directory(). Les fonctions avec le mot stylesheet seront différentes de celles avec le mot template seulement lorsqu'un thème enfant est activé.

  WordPress (PHP)

  wp_enqueue_style( 'monprefixe_bouton', get_stylesheet_directory_uri() . '/css/monprefixe-bouton.css' );

• is_page() : vérifier s'il s'agit de l'affichage d'une page complète (par rapport à une liste d'articles ou à un article complet).

  Ex :

  WordPress (PHP)

  if ( is_page() ) {

     ...   // traitement spécifique pour les pages

  }

• is_single() : vérifier s'il s'agit de l'affichage d'un article complet (par rapport à une liste d'articles ou à une page).

  Ex :

  WordPress (PHP)

  if ( is_single() ) {

     ...   // traitement spécifique pour les articles

  }

• Autres fonctions pour vérifier l'état de ce qui sera affiché (marqueurs conditionnels ou conditional tags).

Pour plus d'information

« fr:Fonctions de référence ». Codex WordPress. http://codex.wordpress.org/fr:Fonctions_de_r%C3%A9f%C3%A9rence

« Référence des fonctions ». PHP Manual. http://www.php.net/manual/fr/funcref.php

« Beginning WordPress Development: A Look at Common Functions ». Six Revisions. http://sixrevisions.com/wordpress/beginning-wordpress-development-a-look-at-common-functions/

« Formatting PHP Strings with printf and sprintf ». Elated. http://www.elated.com/articles/formatting-php-strings-printf-sprintf/