Comment travailler avec WordPress Term Meta API de métadonnées de termes

Le premier article de cette série a jeté les bases de la compréhension des taxonomies, des termes et de leurs relations dans le contexte de WordPress. Si vous ne l'avez pas encore lu et que vous êtes un débutant dans le développement WordPress, je vous recommande vivement de le lire car cet article s'appuiera sur tout ce qui est traité dans cet article.

En outre, lorsque nous parlons de plusieurs types de métadonnées, il est important de passer en revue les séries précédentes dans lesquelles nous avons traité:

Publier des métadonnées
Métadonnées de l'utilisateur
Métadonnées de commentaires

La raison pour laquelle il vaut la peine de revoir ces articles est que cet article ressemblera à certaines des techniques abordées dans ces articles et s'appuiera également sur certaines des stratégies permettant de travailler avec des API similaires..

Ce didacticiel vise avant tout à expliquer comment utiliser l'une des API de métadonnées les plus récentes disponibles dans WordPress..

Un déni de responsabilité pour les développeurs

Comme mentionné précédemment, cet article s’adresse davantage à ceux qui se lancent dans le développement de WordPress ou qui souhaitent développer leurs compétences. Donc, si vous êtes un développeur avancé, le contenu couvert dans cet article risque de ne pas vous intéresser le plus..

Au cours de ce didacticiel, nous devons nous rappeler que le code ne doit pas être utilisé dans un environnement de production. C'est-à-dire qu'il est uniquement destiné à étudier l'API et à comprendre son fonctionnement.

Le code que nous écrivons n'est pas destiné à être utilisé dans un projet destiné à un public ou à un groupe d'utilisateurs. La raison principale en est qu'il existe des sujets tels que la désinfection, la validation, l'échappement, etc., qui sortent du cadre des séries précédentes ainsi que de cette série..

Après avoir rédigé cet article, nous allons passer à des rubriques plus avancées telles que celles-ci, mais pour le moment, nous allons nous concentrer uniquement sur l'API de métadonnées des termes..

Un rappel sur les taxonomies et les termes

Avant de parler de l'API de métadonnées, assurez-vous que nous sommes tous sur la même page en ce qui concerne la terminologie utilisée. Plus précisément, nous devons nous assurer de comprendre les taxonomies, les termes et la relation entre les deux..

Premièrement, le Codex définit les taxonomies comme suit:

Dans WordPress, une "taxonomie" est un mécanisme de regroupement de certains messages (ou liens ou types de messages personnalisés)..

Dans une installation par défaut de WordPress, vous pouvez les considérer comme catégories et Mots clés. Ils peuvent être hiérarchiques, comme des catégories, ou non hiérarchiques, comme des balises..

Les termes, en revanche, sont définis comme suit:

Dans WordPress, un terme est une classification, un groupe ou un sous-ensemble d'une taxonomie, ce dernier pouvant être une catégorie, un tag ou une taxonomie personnalisée. Par défaut, les termes ont un titre, une limace et une description. Les taxonomies hiérarchiques telles que les catégories peuvent définir un terme parent.

Enfin, la relation entre taxonomies et termes est telle qu’une ne peut pas exister sans l’autre (en particulier dans les taxonomies hiérarchiques). C'est-à-dire qu'une taxonomie de catégorie doit avoir au moins un terme associé; cependant, les taxonomies non hiérarchiques ne doivent pas nécessairement suivre que.

Cela dit, commençons à travailler avec l'API Term Metadata..

Travailler avec l'API

Comme pour les autres API de métadonnées disponibles, nous allons pouvoir effectuer des tâches telles que:

ajouter
mettre à jour
récupérer
effacer

Et comme il s'agit d'une nouvelle API, les avantages de cette API ne sont pas toujours clairs. Bien que nous allons seulement explorer certaines des bases de cet article, il est utile d’envisager quelques-unes des choses que nous pouvons faire..

Par exemple:

Associer des couleurs ou des images à un terme
Restreindre certains messages appartenant à un terme
Ajoutez des données binaires, telles que des documents ou des PDF, pour un terme pouvant être mis à disposition sur le serveur frontal.
… et plus.

Bien sûr, il y a beaucoup plus de possibilités. Mais pour le moment, voyons comment intégrer cela dans notre travail.

Préparer le thème

Afin de commencer, assurons-nous que nous sommes sur la même longueur d'ondes sur ce que nous allons utiliser pour faire ce travail. Plus précisément, voici ce dont vous avez besoin et ce que j'utilise.

un IDE-je vais utiliser Atom
une base de données front-end, je vais utiliser Sequel Pro
une version de WordPress-je vais utiliser WordPress 4.4.2
un thème de base, je vais utiliser vingt-six

Une fois que tout est configuré, nous serons prêts à commencer. Si vous avez besoin d'aide pour configurer votre environnement de développement, consultez cette série d'articles..

Commencer

La première chose à faire est de créer un fichier qui contiendra tout le travail que nous allons faire dans ce tutoriel..

Tout d'abord, nous devons créer tutsplus-term-metadata.php à la racine du vingt-six répertoire de thèmes.

Ensuite, nous devons ajouter la ligne de code suivante au fichier functions.php du thème. Cela garantira que nous incluons notre travail dans le thème.

Lorsque vous rechargez votre navigateur, vous devriez voir quelque chose comme l’image suivante:
Il ne devrait y avoir aucune sortie d'erreur, et cela devrait fonctionner comme si rien n'avait changé. Enfin, si vous travaillez avec une nouvelle installation de WordPress, le tableau de métadonnées des termes doit paraître complètement vide:
Ensuite, afin de vous assurer que nous avons une catégorie avec laquelle nous travaillons, allez-y et créez une nouvelle catégorie dans votre installation WordPress. Je vais en créer un appelé Principale et assurez-vous que Bonjour le monde est estampillé avec cette.
Une fois cela fait, jetez un coup d’œil à la table de termes de la base de données afin d’obtenir la term_id. Dans mon cas, le term_id est 2. Les vôtres peuvent varier, mais le fait est que vous connaissez l'identifiant du terme en question:
Prenez note que nous allons utiliser cela tout au long du tutoriel..
Ajout de métadonnées
Pour commencer, il est important de reconnaître que add_term_meta fonction peut servir à deux fins:
 La fonction peut créer des valeurs non uniques associées à un seul identifiant de terme et à une seule clé méta..
 La fonction peut créer des valeurs uniques associées à un seul ID de terme et à une seule clé méta..
 
La fonction accepte un ID de terme, une clé méta, une méta valeur et une valeur booléenne facultative qui détermine si la valeur stockée est unique ou non..
Valeurs uniques
Commençons par créer une valeur unique dans la base de données. Entrez le code suivant dans votre éditeur, actualisez Bonjour le monde, puis voir le termmeta table. 
term_id; if (1 === get_the_ID () && 2 === $ term_id) add_term_meta ($ term_id, 'my_meta_key', 'my_meta_value', true);  return $ content;  
Vous devriez voir vos informations.
Si vous modifiez la méta-valeur et actualisez la page, vous remarquerez que la valeur dans la base de données a ne pas modifié. En effet, vous avez dit que cela devrait être une valeur unique et que la première valeur écrite ne sera ni modifiée ni remplacée.. 
Ceci peut être réalisé avec update_term_meta, mais nous allons regarder ce code momentanément.
Valeurs non uniques
Avant de voir comment mettre à jour la méta de terme, voyons comment ajouter plusieurs valeurs à la même clé de méta et au même identifiant de terme. Le code ci-dessous est similaire au code ci-dessus, sauf que nous ne passons pas true dans la fonction..
term_id; if (1 === get_the_ID () && 2 === $ term_id) pour ($ i = 0; $ i < 3; $i++ )  $meta_value = "my_meta_value_$i"; add_term_meta( $term_id, 'non_unique_key', $meta_value );   return $content; 
Rafraîchir Bonjour le monde à quelques reprises, puis jetez un coup d’œil à la base de données. Vous devriez voir quelque chose comme ça:
Avoir un sens? En gros, lorsque vous dites que vous voulez avoir une valeur unique, la première valeur que vous entrez persistera en tant que seulement valeur (sauf si vous la mettez à jour ou la supprimez). 
Si, par contre, vous ne spécifiez pas que vous voulez que ce soit une valeur unique, vous pouvez stocker autant de valeurs que vous le souhaitez avec l'ID du terme et la clé méta..
Ceci, cependant, ouvre la voie à la récupération d'informations et à la suppression d'informations différemment de la base de données; nous verrons cela plus en détail plus tard dans l'article.
Mise à jour des métadonnées
La fonction API update_term_meta nous offre quelques options intéressantes. Premièrement, cela nous donne la possibilité d’ajouter une entrée unique à la base de données sans avoir à utiliser le quatrième paramètre de add_post_meta.
Deuxièmement, cela nous permet de mettre à jour une métadonnée spécifique tant que nous savons quelle était la valeur précédente. Jetons un coup d'oeil à ces deux cas étant donné l'état actuel de notre base de données.
Ajout de données uniques
Pour ajouter des métadonnées uniques, nous pouvons faire un appel très similaire à ce que nous avons vu dans le premier exemple. add_term_meta. Au lieu de cela, cette fois, nous utilisons update_term_meta. Par exemple, examinez le code suivant:
term_id; if (1 === get_the_ID () && 2 === $ term_id) update_term_meta ($ term_id, 'update_key', 'my_unique_update_value');  return $ content; 
Rafraîchir Bonjour le monde à quelques reprises et quel que soit le nombre de fois que vous l'actualisez, une seule valeur est entrée dans la base de données. Si vous suivez le code, vous devriez voir quelque chose comme ceci:
Mais que se passe-t-il quand il y a plusieurs enregistrements avec la même clé méta et que nous voulons les mettre à jour??
Mise à jour d'un enregistrement non unique
Pour mettre à jour un enregistrement comportant le même identifiant de terme et la même clé méta, il est important de connaître la valeur précédente. Dans notre cas, nous savons que nous avons une valeur appelée my_meta_value_1. 
À cette fin, nous pouvons mettre à jour cette ligne spécifique en spécifiant la nouvelle valeur et l'ancienne valeur dans update_term_meta une fonction. Pour ce faire, examinez le code suivant:
term_id; if (1 === get_the_ID () && 2 === $ term_id) update_term_meta ($ term_id, 'non_unique_key', 'my_meta_value_1_updated', 'my_meta_value_1');  return $ content; 
Et puis rafraichir Bonjour le monde. Une fois cela fait, la méta valeur mise à jour devrait ressembler à ceci:
Si vous ne voyez pas le même résultat, assurez-vous que vous avez correctement spécifié le nom de la fonction correcte dans votre hook, l'ID du terme d'écriture, la bonne clé méta et la méta-valeur précédente droite..
Récupérer les métadonnées
Pour obtenir les métadonnées que nous avons récupérées, nous pouvons utiliser le get_term_meta une fonction. 
Notez cependant que lorsque nous récupérons des métadonnées de terme, nous pouvons avoir affaire à une méta clé à laquelle plusieurs valeurs sont associées. Ou nous pouvons avoir affaire à une méta clé qui n'a qu'une seule valeur.
En fonction de la situation, nous devrons spécifier différentes informations pour la fonction.. 
Récupérer toutes les métadonnées
La récupération de toutes les métadonnées associées à un terme unique est facile, comme le montre le code ci-dessous. L'important, c'est que les résultats soient renvoyés dans un tableau.. 
Dans l'exemple ci-dessous, nous allons utiliser le non_unique_key comme notre clé méta car il a plusieurs valeurs qui lui sont associées.
term_id; if (1 === get_the_ID () && 2 === $ term_id) get_term_meta ($ term_id, 'non_unique_key');  return $ content; 
Vous pouvez choisir de renvoyer les résultats à l'écran, d'utiliser var_dump ou d'utiliser un débogueur pour afficher les informations. Dans tous les cas, vous devriez voir quelque chose comme ce qui suit:
array (3) [0] => chaîne (15) "my_meta_value_0" [1] => chaîne (23) "my_meta_value_1_updated" [2] => chaîne (15) "my_meta_value_2"
Étant donné cette sortie, vous pouvez choisir de la stocker dans une variable, puis d'extraire une certaine valeur d'un index donné. Ou peut-être préféreriez-vous parcourir les données et les lire ou les manipuler.
Quel que soit votre cas d'utilisation, voici comment vous pouvez récupérer toutes les informations associées à une clé méta.
Récupération d'une seule pièce de métadonnées
Lorsque nous parlons de récupérer une seule métadonnée, nous voulons généralement dire que nous cherchons à extraire un enregistrement de plusieurs (comme dans notre exemple ci-dessus); Cependant, il peut arriver que nous voulions récupérer une seule méta-valeur associée à une seule méta-clé..
Nous parlerons de la dernière affaire dans un instant. Mais d'abord, couvrons le cas où nous voulons récupérer une valeur unique à partir d'un ensemble de données ayant le même identifiant de terme et la même clé méta..
Remarquez dans le code ci-dessous, nous passons une quatrième valeur, vrai:
term_id; if (1 === get_the_ID () && 2 === $ term_id) get_term_meta ($ term_id, 'non_unique_key', true);  return $ content; 
Et voici ce qui est retourné:
string (15) "my_meta_value_0"
Notez que ceci retourne la première valeur qu'il trouve et il le fait sous la forme d'une chaîne.
Et s'il n'y a qu'un seul enregistrement?
S'il n'y a qu'un seul enregistrement, vous avez alors deux options:
 Vous pouvez récupérer les informations sans spécifier vrai.
 Vous pouvez récupérer les informations en spécifiant vrai.
 
Si vous optez pour le premier cas, vous récupérerez un tableau avec un seul index et une seule valeur. En tant que tel, vous aurez besoin de saisir la valeur du résultat en faisant quelque chose comme: $ valeur = $ résultat [0] en supposant que vous stockiez le résultat de l'appel de fonction dans $ résultat.
Par contre, si vous optez pour la deuxième option, vous pouvez vous attendre à recevoir le résultat sous forme de chaîne.
On peut soutenir que la chose la plus importante à noter pour aborder les valeurs de cette stratégie particulière est que les valeurs sont uniques en raison de leur méta-clé.
Suppression de métadonnées
Enfin, nous devons examiner la possibilité de supprimer les métadonnées associées. Et, pour rester cohérent avec le reste de nos exemples, cela dépend de la présence de plusieurs métadonnées associées à une clé méta ou d'une seule méta-valeur associée à une méta clé..
Suppression de tous les enregistrements
Si vous savez qu'il existe une seule clé méta à laquelle plusieurs valeurs sont associées, vous pouvez utiliser le code suivant:
term_id; if (1 === get_the_ID () && 2 === $ term_id) delete_term_meta ($ term_id, 'non_unique_key');  return $ content;  
Et cela mettra à jour la table de base de données de telle sorte qu’elle se présente comme suit:
Si vous avez suivi, alors vous savez que cela a supprimé toutes les données associées à la non_unique_key clé méta.
Supprimer un seul enregistrement
Si vous souhaitez supprimer un seul enregistrement, vous pouvez le faire de deux manières:
 Vous connaissez la méta-valeur associée à la clé méta que vous souhaitez supprimer.
 La valeur associée à la clé méta spécifiée est unique en ce que la clé méta et la valeur méta sont uniques..
 
À cette fin, examinons le premier exemple de cette section et examinons le deuxième exemple de cette section..
Pour supprimer un seul enregistrement dans lequel nous connaissons la méta-valeur associée, nous pouvons écrire un code spécifiant à la fois la clé et la méta-clé. Par exemple:
term_id; if (1 === get_the_ID () && 2 === $ term_id) delete_term_meta ($ term_id, 'my_meta_key', 'my_meta_value');  return $ content; 
Cela supprimera la ligne associée à ces informations de la base de données..
Supprimer un enregistrement unique
Enfin, s'il existe un seul enregistrement dans lequel vous connaissez la clé méta mais vous ne connaissez pas la méta-valeur, vous pouvez toujours supprimer cet enregistrement de la base de données..
Tout ce que vous devez spécifier dans le code source est la clé méta. Voir dans la fonction suivante:
term_id; if (1 === get_the_ID () && 2 === $ term_id) delete_term_meta ($ term_id, 'update_key');  return $ content; 
Les lecteurs astucieux comprendront probablement que la fonction ci-dessus correspond à la même définition que celle que nous avons fournie lors de la suppression d'enregistrements contenant plusieurs valeurs. Et c'est parce qu'ils sont le même.
La différence, cependant, est le intention de la fonction. L'intention d'une fonction détermine souvent comment nous nommons la fonction. Dans le cas précédent, nous voulions supprimer toutes les métadonnées du terme. Dans ce cas, nous voulions supprimer un seul morceau de métadonnées de terme.
Cela a des implications pour l'écriture de code qualité et l'écriture de tests unitaires.
Le code source complet
Ici, vous allez trouver tout le code que nous avons utilisé tout au long de ce post ainsi que des commentaires supplémentaires expliquant ce qui se passe dans le code. Rappelez-vous que toutes ces fonctions sont reliées à le contenu, ce qui signifie que les fonctions se déclencheront chaque fois que le poste est chargé.
En tant que tel, le add_filter les appels sont commentés afin que vous puissiez les activer au besoin.
term_id; if (1 === get_the_ID () && 2 === $ term_id) add_term_meta ($ term_id, 'my_meta_key', 'my_meta_value_changed', true);  return $ content;  // add_filter ('the_content', 'tutsplus_add_term_metas'); / ** * Si nous en sommes au premier message et dans la catégorie ayant le * ID de '2', nous ajoutons plusieurs méta-valeurs avec la même * clé méta au terme métadonnées. * * @param string $ content Contenu de la publication. * @return string Le contenu de la publication. * / function tutsplus_add_term_metas ($ content) $ category = get_the_category (); $ term_id = $ category [0] -> term_id; if (1 === get_the_ID () && 2 === $ term_id) pour ($ i = 0; $ i < 3; $i++ )  $meta_value = "my_meta_value_$i"; add_term_meta( $term_id, 'non_unique_key', $meta_value );   return $content;  //add_filter( 'the_content', 'tutsplus_update_term_meta' ); /** * Updates the term meta value with the specified key. If the value * doesn't exist, then the record will be created. This will only * be added if the 'Hello World' page is loaded with the category * having the ID of '2'. * * @param string $content The post content. * @return string The post content. */ function tutsplus_update_term_meta( $content )  $category = get_the_category(); $term_id = $category[0]->term_id; if (1 === get_the_ID () && 2 === $ term_id) update_term_meta ($ term_id, 'update_key', 'my_unique_update_value');  return $ content;  // add_filter ('the_content', 'tutsplus_update_term_metas'); / ** * Met à jour la valeur existante pour les métadonnées ayant la clé méta 'non_unique_key' * avec la méta valeur spécifiée. Cela ne se produit que si nous sommes sur le * post avec l'ID d'un et qu'il a l'ID de catégorie '2'. * * @param string $ content Contenu de la publication. * @return string Le contenu de la publication. * / function tutsplus_update_term_metas ($ content) $ category = get_the_category (); $ term_id = $ category [0] -> term_id; if (1 === get_the_ID () && 2 === $ term_id) update_term_meta ($ term_id, 'non_unique_key', 'my_meta_value_1_updated', 'my_meta_value_1');  return $ content;  // add_filter ('the_content', 'tutsplus_get_term_metas'); / ** * Si nous sommes sur le premier post et que le post a l'identifiant de catégorie '2', alors * récupère le terme méta sous la forme d'un tableau. * * @param string $ content Contenu de la publication. * @return string Le contenu de la publication. * / function tutsplus_get_term_metas ($ content) $ category = get_the_category (); $ term_id = $ category [0] -> term_id; if (1 === get_the_ID () && 2 === $ term_id) get_term_meta ($ term_id, 'non_unique_key');  return $ content;  // add_filter ('the_content', 'tutsplus_get_term_meta'); / ** * Si nous sommes sur le premier message et que le message a l'ID de catégorie '2', * récupère la première valeur des métadonnées sous forme de chaîne. * * @param string $ content Contenu de la publication. * @return string Le contenu de la publication. * / function tutsplus_get_term_meta ($ content) $ category = get_the_category (); $ term_id = $ category [0] -> term_id; if (1 === get_the_ID () && 2 === $ term_id) get_term_meta ($ term_id, 'non_unique_key', true);  return $ content;  // add_filter ('the_content', 'tutsplus_delete_term_metas'); / ** * Si nous sommes sur le premier post et que le post a l'identifiant de catégorie '2', * supprime les méta-valeurs associées à la clé spécifiée. * * @param string $ content Contenu de la publication. * @return string Le contenu de la publication. * / function tutsplus_delete_term_metas ($ content) $ category = get_the_category (); $ term_id = $ category [0] -> term_id; if (1 === get_the_ID () && 2 === $ term_id) delete_term_meta ($ term_id, 'non_unique_key');  return $ content;  // add_filter ('the_content', 'tutsplus_delete_term_meta'); / ** * Si nous sommes sur le premier message et que le message a l'ID de catégorie '2', * supprime la méta valeur spécifiée associée à la clé méta spécifiée. * * @param string $ content Contenu de la publication. * @return string Le contenu de la publication. * / function tutsplus_delete_term_meta ($ content) $ category = get_the_category (); $ term_id = $ category [0] -> term_id; if (1 === get_the_ID () && 2 === $ term_id) delete_term_meta ($ term_id, 'my_meta_key', 'my_meta_value');  return $ content;  // add_filter ('the_content', 'tutsplus_delete_single_term_meta'); / ** * Si nous sommes sur le premier post et que le post a l'identifiant de catégorie '2', * supprime les méta-valeurs associées à la clé spécifiée. * * @param string $ content Contenu de la publication. * @return string Le contenu de la publication. * / function tutsplus_delete_single_term_meta ($ content) $ category = get_the_category (); $ term_id = $ category [0] -> term_id; if (1 === get_the_ID () && 2 === $ term_id) delete_term_meta ($ term_id, 'update_key');  return $ content;  
Il n’est pas rare de trouver des fonctions comme celle-ci accrochées à un autre crochet comme save_post ou quelque chose de similaire. C’est quelque chose que nous verrons plus en détail dans un tutoriel avancé plus tard dans l’année..
Conclusion
Pour ceux qui ont suivi cette série et les séries précédentes travaillant avec le reste de l'API de métadonnées, une grande partie du matériel couvert dans cette série ne devrait pas être trop difficile à saisir..
La partie la plus difficile du travail avec cette API consiste peut-être à faire preuve de créativité pour utiliser de nombreuses manières. Mais depuis que nous avons couvert Comment travailler avec l'API, le mettre au travail ne devrait pas être terriblement difficile.
N'oubliez pas que dans les semaines à venir, nous allons examiner des techniques avancées et appropriées pour écrire et lire des informations dans la base de données, afin de pouvoir les utiliser dans un environnement de production.
En attendant, si vous recherchez d'autres utilitaires pour vous aider à développer votre ensemble croissant d'outils pour WordPress ou pour que le code soit étudié et approfondi dans WordPress, n'oubliez pas de voir ce que nous avons disponible dans Envato. Marché.
N'oubliez pas que vous pouvez voir tous mes cours et tutoriels sur ma page de profil et vous pouvez me suivre sur mon blog et / ou Twitter à @tommcfarlin, où je parle de diverses pratiques de développement de logiciels et de la façon dont nous pouvons les utiliser dans WordPress..
S'il vous plaît n'hésitez pas à laisser des questions ou des commentaires dans le flux ci-dessous, et je vais essayer de répondre à chacun d'eux.
Ressources associées
  Les champs personnalisés
 get_the_category
 add_term_meta
 update_term_meta
 get_term_meta
 delete_term_meta
 écho
 var_dump
 



		
			
	   
	




Code