Les fonctions WordPress PHP utiles pour développeurs

Publié le 19 mars 2020 Développement WordPress

Le cœur du CMS permet de faire pas mal d’actions lors de nos créations et refontes de site. Malheureusement on passe souvent à côté de fonctions très utiles pour les développeurs WordPress.

Chez SeoMix, on a donc décidé de créer cette page de ressources pour retrouver toutes les fonctions WordPress méconnues ou peu utilisées, ainsi que quelques fonctions PHP réellement utiles :

Thèmes et rendu HTML

wp_unique_id()

Fonction très utile, elle vous permet de générer un ID unique à chaque fois que vous l’appelez. Imaginons que vous insérez un même bloc Gutenberg dans une page mais que vous voudriez un ID HTML unique pour chaque bloc : cette fonction est faites pour vous !

wp_unique_id : Exemple

echo '<hr id="' . wp_unique_id() . '"/>';

// RENDU :
// "<hr id="1"/>"
// "<hr id="2"/>"
// Etc.

La page officielle : wp_unique_id()

make_clickable()

Comme son nom l’indique, la fonction rend « cliquable » tout ce qui est censé l’être : les liens et les emails. Par défaut, cela ajoute l’attribut nofollow aux liens (pour le supprimer, vous devrez agir sur le hook « make_clickable_rel« ).

make_clickable : exemple

$data 	= "Super texte avec email contact@seomix.fr ainsi qu'une URL https://www.seomix.fr";
$rendu 	= make_clickable( $data );
echo $rendu;

// RENDU :
"Super texte avec email <a href="mailto:contact@seomix.fr&quot;>contact@seomix.fr&lt;/a> ainsi qu'une URL <a href="https://www.seomix.fr" rel="nofollow">https://www.seomix.fr</a>"

La page officielle : make_clickable()

get_theme_file_uri()

La fonction renvoie l’URL du thème actuellement actif. On peut ainsi récupérer l’URL complète du thème enfant si vous avez un thème enfant, sinon celui du thème WordPress parent. La fonction sera utile pour appeler dans une fonction un fichier précis. Par exemple, cela pourrait renvoyer : https://www.seomix.fr/wp-content/themes/nom-du-super-theme/

get_theme_file_uri : Exemple

$uri = get_theme_file_uri();
// $uri = https://www.seomix.fr/wp-content/themes/nom-theme/

La page officielle : get_theme_file_uri()

wp_body_open()

Cette petite fonction devrait se trouver dans TOUS les thèmes WordPress. Elle sert à d’autres fonctions de votre thème ou de vos extensions, à ajouter du code juste au début du contenu de vos pages (donc juste après <body>).

Par exemple, cela peut être utile pour les Tags Managers pour ajouter certaines balises.

wp_body_open() : insertion

<body>
    <?php wp_body_open(); ?>

La page officielle : wp_body_open()

human_time_diff()

Cette fonction est très pratique : elle permet d’afficher de façon « humaine » la différence de temps entre deux dates. Cela permet notamment d’afficher le temps passé depuis la mise en ligne d’un contenu : Article publié « il y a 5 heures »

La page officielle : human_time_diff()

Sécurité & spam

antispambot()

Transforme le code HTML de vos adresses email pour réduire le spam, mais en gardant le côté pratique et visuel classique d’une adresse email. En résumé, cela encode certains caractères sans pour autant enlever la possibilité pour l’utilisateur de copier/coller ou de cliquer sur ces emails.

AntiSpamBot : exemple

$email = 'test@test.fr';
echo antispambot( $email );

// RENDU :
// "test&#64;tes&#116;.&#102;&#114;"

La page officielle : antispambot()

wp_safe_redirect()

Un équivalent plus sécurisé de wp_redirect(), dans le sens où le nom d’hôte de destination peut être filtré. Par défaut, seul le nom de domaine d’origine est autorisé. Vous ne pouvez donc faire que des redirections internes par défaut avec cette fonction WordPress. D’autres noms de domaines peuvent être ajoutés via le hook allowed_redirect_hosts.

La page officielle : wp_safe_redirect()

fIchiers

wp_ext2type()

Une petite fonction utile pour connaître le type de fichier. Par exemple, la fonction renvoie « audio » pour mp3 ou « image » pour jpeg.

wp_ext2type : exemple

$files = array (
	'test.jpeg',
	'toto.png',
	'top.woff2',
	'essai.mp3',
	'essai.jenexistepas',
	'test.doc',
	'https:///www.seomix.fr/test.xls',
	'hola.mp4',
	'wordpress.avi'
);

foreach ( $files as $type ) {
	$ext = pathinfo( $type, PATHINFO_EXTENSION );
	echo $type . ' : ' . wp_ext2type( $ext ) .'<br>';
}

Rendu :

test.jpeg : image
toto.png : image
top.woff2 :
essai.mp3 : audio
essai.jenexistepas :
test.doc : document
https:///www.seomix.fr/test.xls : spreadsheet
hola.mp4 : video
wordpress.avi : video

Dans mon exemple, j’utilise la fonction PHP Pathinfo pour extraire l’extension du fichier et/ou de l’URL.

Sachez également que cette fonction ne reconnaît pas certains types de fichiers, comme la police d’écriture .woff2. C’est parce que WordPress utilise dans cette fonction une autre appelée wp_get_ext_types(), et cette dernière liste les formats reconnus par défaut. Vous pourrez les filtrer via le hook « ext2type ».

Les pages officielles :

size_format()

Convertit un chiffre en bytes pour le rendre plus lisible pour l’humain. Par exemple, la fonction transformera « 1048576 bytes » en « 1 Mo ». Pratique, et efficace comme fonction WordPress :

Exemple de Size_format

$file_size = 1229; // filesize in bytes
echo size_format( $file_size, $decimals = 2 );

// RENDU
// "1.20 Kb"
// PS : exemple tiré du codex

La page officielle : size_format()

get_dirsize()

Son nom est relativement explicite : cette fonction WordPress vous retourne le poids d’un dossier complet. C’est utile par exemple pour connaître le poids des fichiers présents dans un dossier précis.

Exemple de Get_dirsize

$upload_dir = wp_upload_dir()['basedir'];
$mb = get_dirsize( $upload_dir ); // quel est le poids du dossier Uploads de WordPress ?
echo size_format( $mb, 2 ); 

// RENDU 
// "1.40 MB"

Attention, la fonction a une mise en cache native d’une heure. Il faut supprimer le transient « dirsize_cache » pour avoir la donnée en temps réel (mais attention dans ce cas, la fonction peut être gourmande en ressources).

La page officielle : get_dirsize()

Entêtes HTTP

wp_remote_retrieve_response_code()

La fonction wp_remote_get() permet de récupérer tout le contenu et les entêtes d’une URL (une sorte de file_get_content() amélioré). Mais si l’on souhaite extraire uniquement le code de réponse d’une adresse web, wp_remote_retrieve_response_code() est fait pour vous.

wp_remote_retrieve_response_code : Exemple

$response = wp_remote_get( 'https://www.seo-key.com/' ); // Je récupère tout le contenu HTML et les headers
$response_code = wp_remote_retrieve_response_code( $response );
echo $response_code;

// RENDU
// "200"

La page officielle : wp_remote_retrieve_response_code()

get_status_header_desc()

La fonction vous renvoie une description textuelle d’un entête HTTP. Elle va par exemple renvoyer « Page non trouvée » pour l’entête 404. Donc en prenant l’exemple donné juste avant, voici ce que cela donne :

Get_status_header_desc : Exemple

echo get_status_header_desc( $response_code );

// RENDU
// "OK"

La page officielle : get_status_header_desc()

URL et liens

url_shorten()

Une fonction WordPress simple permettant de raccourcir à 35 caractères maximum une URL, en enlevant au passage le protocole HTTP/HTTPS et le sous-domaine « www » :

URL_shorten : exemple

$url = "https://www.seomix.fr/ceci-est-une-superbe-url-trop-longue/";
echo url_shorten( $url );
// RENDU
// "seomix.fr/ceci-est-une-superbe-u…"

La page officielle : url_shorten()

Cette petite fonction WordPress permet de transformer des liens relatifs en liens absolus en rajoutant les éléments manquants (le nom de domaine et le protocole). C’est très pratique quand on copie ou que l’on importe des contenus ayant des URL relatives (donc celles sans le nom de domaine)

Links_add_base_url : Exemple

$url = "Ceci est un contenu avec un lien relatif <a href='/ceci-est-une-superbe-url-trop-longue/'>Test</a>";
echo links_add_base_url( $url, home_url() );

// RENDU
// "Ceci est un contenu avec un lien relatif <a href='https://www.seomix.fr/ceci-est-une-superbe-url-trop-longue/'>Test</a>"

La page officielle : links_add_base_url()

user_trailingslashit()

Fonction méconnue, elle permet de modifier si besoin est une URL pour qu’elle corresponde au paramétrage utilisé par son WordPress. Si dans « Réglages > Permaliens« , vous avez un slash à la fin, alors la fonction le rajoute s’il est manquant. Si à l’inverse il n’y a pas de slash de fin dans votre paramétrage, la fonction le retire s’il est présent.

User_trailingslashit : exemple

// Mon paramétrage WordPress est /%postname%/
$url = "https://www.seomix.fr/ceci-est-une-superbe-url"; // sans slash de fin
echo user_trailingslashit( $url );
// RENDU
// "https://www.seomix.fr/ceci-est-une-superbe-url/"

Cette fonction WordPress est souvent indispensable quand vous avez besoin de récupérer ou générer une URL interne pour l’utilisateur.

La page officielle : user_trailingslashit()

Ajoute l’attribut « target » aux liens. S’ils en possèdent déjà un, il sera remplacé. Avec le troisième paramètre, on peut d’ailleurs appliquer cette fonction à d’autres éléments HTML que les liens <a href>.

Links_add_target : exemple

$url = "Ceci est un contenu avec un lien <a href='https://www.seomix.fr/ceci-est-une-superbe-url-trop-longue/'>Test</a>";
echo links_add_target( $url, '_blank' );
// RENDU
// "<a href='https://www.seomix.fr/ceci-est-une-superbe-url-trop-longue/' target="_blank">Test</a>"

La page officielle : links_add_target()

Les fonctions pour développeurs

Mise en cache

WordPress dispose d’une série de fonctions pour avoir une mise en cache de données (par défaut, il est non persistant), c’est-à-dire un cache temporaire.

ATTENTION CEPENDANT : ce cache peut devenir persistant dès lors que vous avez une configuration spécifique, par exemple si vous utilisez Memcached sur votre serveur. Cela veut dire qu’en aucun cas vous ne devez utiliser ces fonctions pour le stockage de données sensibles, ou de fonctionnalités et de données nécessitant certains privilèges (être auteur, être administrateur, etc.). Plus d’informations sont disponibles ici : WP Object Cache.

L’objectif de ces fonctions est de mettre en cache des données pour les réutiliser plus tard, ou dans d’autres fonctions et fichiers lors du chargement de la page :

  • wp_cache_add
  • wp_cache_set
  • wp_cache_get
  • wp_cache_delete

À chaque changement de page, le cache créé par ses fonctions est réinitialisée (les données sont stockées dans la mémoire) dans le cadre d’une cache non persistant. Attention là encore, en fonction de votre serveur, ce cache peut être permanent si vous ne faites pas de wp_cache_delete. Cela ne remplace donc pas les transients de WordPress (qui incluent une durée de vie et qui est toujours persistant) ou une vraie mise en cache en front office comme le ferait WP Rocket.

Ces fonctions sont utiles dans plusieurs cas, notamment :

  • En cas de cache persistant, permettre au serveur de garder en cache la donnée de manière bien performant que le cache WordPress (notamment les transients) ;
  • Ne pas recalculer une donnée lors du chargement d’une page ou d’une fonction, le tout sans avoir à écrire cette donnée en base (comme le ferait un transient, une option ou une méta qui déclencheraient des requêtes SQL) ;
  • Partager facilement les données mise en cache entre différents fichiers, là encore sans appel en base de données. On pourrait imaginer le scénario suivant : le fichier A de mon extension fait un cache_add d’une information et le fichier B de mon thème WordPress fait un cache_get juste après.

Exemples de caches non persistants (mais potentiellement persistants)

// Ajouter une donnée en cache
wp_cache_add( "SeoMix mon option", "La superbe donnée à mettre en cache" );

// Mettre à jour la donnée
wp_cache_set( "SeoMix mon option", "Vive le chocolat" );

// Affiche une valeur en cache
echo wp_cache_get( "SeoMix mon option" );
// RENDU
// "Vive le chocolat"

// On supprime notre option
wp_cache_delete( "SeoMix mon option" );

// Affiche une valeur non existante en cache
echo wp_cache_get( "SeoMix mon option" );
// rendu vide

// On vide tout le cache, quels que soient les noms utilisés
wp_cache_flush();

wp_list_sort()

Comme le nom l’indique, cette fonction de WordPress permet de trier une liste d’objets selon une clé ou un paramètre précis.

Exemple natif de wp_list_sort

// Trier une liste d'articles selon leurs dates de publication
wp_list_sort( $posts, 'post_date', 'DESC' )

Si vous avez votre propre liste d’objets, voici ce que l’on peut faire en utilisant un paramètre commun à notre liste d’objets :

Code avancé de wp_list_sort (tiré du codex)

$animals = [
    'alligator' => [ 'name' => 'alligator', 'fly' => false, 'class' => 'reptile' ],
    'dog'       => [ 'name' => 'dog',       'fly' => false, 'class' => 'mammal' ],
    'cat'       => [ 'name' => 'cat',       'fly' => false, 'class' => 'mammal' ],
    'falcon'    => [ 'name' => 'falcon',    'fly' => true,  'class' => 'bird' ],
    'bat'       => [ 'name' => 'bat',       'fly' => true,  'class' => 'mammal' ],
];
 
var_dump ( wp_list_sort( $animals, 'name', 'ASC' )) ;
// [
//   0 => [ 'name' => 'alligator', ... ]
//   1 => [ 'name' => 'bat', ... ]
//   2 => [ 'name' => 'cat', ... ]
//   3 => [ 'name' => 'dog', ... ]
//   4 => [ 'name' => 'falcon', ... ]
// ]
 
var_dump ( wp_list_sort( $animals, 'name', 'ASC', true ) ) ;
// [
//   'alligator' => [ 'name' => 'alligator', ... ]
//   'bat'       => [ 'name' => 'bat', ... ]
//   'cat'       => [ 'name' => 'cat', ... ]
//   'dog'       => [ 'name' => 'dog', ... ]
//   'falcon'    => [ 'name' => 'falcon', ... ]
// ]

La page officielle : wp_list_sort()

wp_list_pluck()

Cette fonction permet de « nettoyer » un tableau pour ne conserver qu’une clé précise de chaque élément :

wp_list_pluck : Exemple

$mes_animaux = [
    'alligator' => [ 'name' => 'alligator', 'fly' => false, 'class' => 'reptile' ],
    'dog'       => [ 'name' => 'dog',       'fly' => false, 'class' => 'mammal' ],
    'cat'       => [ 'name' => 'cat',       'fly' => false, 'class' => 'mammal' ],
    'falcon'    => [ 'name' => 'falcon',    'fly' => true,  'class' => 'bird' ],
    'bat'       => [ 'name' => 'bat',       'fly' => true,  'class' => 'mammal' ],
];
 
var_dump ( wp_list_pluck( $mes_animaux, 'fly' ) ) ;
// RENDU
// array (size=5)
//   'alligator' => boolean false
//   'dog' => boolean false
//   'cat' => boolean false
//   'falcon' => boolean true
//   'bat' => boolean true

La page officielle : wp_list_pluck()

wp_array_slice_assoc()

Permet d’extraire des données d’un tableau, en l’occurrence des clés précises. C’est très utile quand votre tableau contient un grand nombre de données et que vous ne voulez en conserver que certaines bien précises connues à l’avance (par exemple, je récupère une option qui contient un tableau de valeurs et seules certaines me seront utiles).

wp_array_slice_assoc : Exemple

$mes_cles = array(
   'alligator',
   'dog',
   'bat',
);
var_dump ( wp_array_slice_assoc ( $mes_animaux, $mes_cles ) );
// RENDU
// $animals = [
//     'alligator' => [ 'name' => 'alligator', 'fly' => false, 'class' => 'reptile' ],
//     'dog'       => [ 'name' => 'dog',       'fly' => false, 'class' => 'mammal' ],
//     'bat'       => [ 'name' => 'bat',       'fly' => true,  'class' => 'mammal' ],
// ];

La page officielle : wp_array_slice_assoc()

WP_ENVIRONMENT_TYPE et wp_get_environment_type()

Cette constante et cette fonction sont des incontournables et sont bien trop méconnues. Depuis WordPress 5.5, on peut définir la constante WP_ENVIRONMENT_TYPE dans le fichier de configuration de WordPress pour indiquer quel est le type de site sur lequel on travaille (dans le fichier wp-config.php). Il y a 4 valeurs possibles :

  • Production : votre site en ligne ;
  • Staging : votre version de site avant déploiement ;
  • Development : votre version de travail ;
  • Local : une version de votre site hors ligne sur votre ordinateur (en « local ») ;

Et cela a de l’importance, car certaines fonctionnalités ne devraient pas s’activer en fonction de ces valeurs. Par exemple, il serait malsain d’envoyer des emails aux utilisateurs avec une version en développement ou locale, ou encore il serait inutile de faire certains pings ou certains appels à des API externes tant que l’on n’est pas sur notre vrai site en « production ».

Une fois la constante définie, vous pourrez donc utiliser wp_get_environment_type() pour activer, modifier ou désactiver vos propres fonctionnalités.

L’article d’explication officiel : new wp_get_environment_type() function

Les posts types et les taxonomies

Votre WordPress utilise peut-être des taxonomies ou des post types sur mesure. On a alors parfois besoin de certaines fonctions. En voici une bien utile :

is_post_type_viewable()

Comme son nom l’indique, cette fonction permet de dire si un type de contenu est censé être vu publiquement. Cela prendra la valeur de « Public » pour les post types par défaut et la valeur de publicly_queryable pour tous les customs posts types.

Vérifier si un post type est public

is_post_type_viewable( 'page' );
// Par défaut, va renvoyer true : le post type "Page" est public

La page officielle : is_post_type_viewable()

Les fonctions des Extensions

acf_maybe_get()

Cette fonction de l’extension Advanced Custom Field permet d’extraire si elle existe une clé d’un tableau, et de renvoyer le cas contraire « null » (ou une valeur de son choix utilisée en 3ème paramètre).

Exemple d’acf_maybe_get

$tableau = array ( 
	'test' 		=> '1',
	'toto' 		=> 'yopla',
);
$un    	= acf_maybe_get( $tableau, 'test' );
$deux 	= acf_maybe_get( $tableau, 'test2' );
$trois  = acf_maybe_get( $tableau, 'test3', "donnée à renvoyer si non présente" );
// RENDU
// $un : "1"
// $deux : "null"
// $trois : "donnée à renvoyer si non présente"

Sachez qu’on peut facilement reproduire cette fonction en dehors d’ACF tellement cette dernière est simple :

Détail de la fonction acf_maybe_get()

function acf_maybe_get( $array = array(), $key = 0, $default = null ) {
	return isset( $array[$key] ) ? $array[$key] : $default;
}

acf_unarray()

Petite fonction toute bête, mais pratique : quand vous voulez récupérer une variable de type string, mais que vous n’êtes pas sûr que cela en soit une, cette fonction permet de transformer n’import quel array en string.

Et voici comment elle fonctionne sous le capot :

Détails de la fonction acf_unarray

function acf_unarray( $val ) {
	if ( is_array( $val ) ) {
		return reset( $val );
	}
	return $val;
}

D’autres fonctions PHP ?

Si vous en connaissez d’autres, faites-le savoir en commentaire et nous viendrons étoffer ce guide.

Merci au passage à la communauté WordPress, notamment Pierre Saïkili et Julio Potier pour certaines trouvailles qu’ils ont déjà pu partager dans le passé et qui m’ont permis d’étoffer ce guide pour les développeurs WP.

Daniel Roch

Fondateur, conférencier, auteur, consultant et expert SEO WordPress

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée.