Aller au contenu principal
Version: 26.0.10.0

Taxonomy

Principalement utilisée lors de la création d'un post type pour y lier une taxonomy.

app/PostTypes/MyCustomPostType.php
public function taxonomies()
{
    $this->addTaxonomy('ingredients', 'Ingrédients')
        ->isMale()
        ->setLabels([
            'plural' => 'ingrédients',
            'singular' => 'ingrédient',
        ])
        ->register();
}

Propriétés disponibles​

PropriétéTypeDescription
slugstringSlug de la taxonomy
postTypePostTypeObjet PostType associé (typé depuis 26.0.10.0)
currentPostPostPost courant (pour récupérer les termes)
post_termsarrayTermes du post courant
termsarrayTous les termes de la taxonomy
labelsarrayLabels de la taxonomy

Méthodes​

isMale() et isFemale()​

Permet de définir si la taxonomy est masculine ou féminine.

Exemple :

$taxonomy->isMale();  // "le" Ingredient
$taxonomy->isFemale(); // "la" Catégorie

setLabels(array $labels)​

Définit les labels de la taxonomy.

Paramètres :

  • $labels : Tableau associatif avec les clés singular et plural

Exemple :

$taxonomy->setLabels([
    'singular' => 'ingrédient',
    'plural' => 'ingrédients'
]);
remarque

Les méthodes setSingular() et setPlural() sont également disponibles si vous préférez éviter le tableau.


register()​

Finalise l'enregistrement de la taxonomy au sein du post type.

Retourne : $this - Permet le chaînage

Exemple :

$taxonomy->register();

// Chaînage
$taxonomy->setLabels([...])->register();

addContainerFields(string $title, array $fields)​

Ajoute des champs Carbon Fields à la taxonomy.

Paramètres :

  • $title : Titre du conteneur
  • $fields : Tableau de champs Field::make()

Exemple :

use Carbon_Fields\Field;

$taxonomy->addContainerFields('Informations', [
    Field::make('text', 'ingredient_origin', 'Origine'),
    Field::make('textarea', 'ingredient_description', 'Description'),
]);

registerTaxonomyContainers()​

Enregistre les conteneurs de champs Carbon Fields pour la taxonomy.

attention

Cette méthode doit être appelée après addContainerFields().

Exemple :

$taxonomy
    ->addContainerFields('Informations', [
        Field::make('text', 'ingredient_origin', 'Origine'),
    ])
    ->registerTaxonomyContainers();

getTerms(bool $includeFields = true)​

Récupère tous les termes de la taxonomy.

Paramètres :

  • $includeFields : Si true, inclut les champs Carbon Fields dans les termes (défaut : true)

Retourne : array - Tableau des termes

Exemple :

// Récupère tous les termes avec leurs champs
$terms = $taxonomy->getTerms();

foreach ($terms as $term) {
    echo $term->name;
    echo $term->fields['ingredient_origin'] ?? '';
}

// Récupère tous les termes sans les champs
$terms = $taxonomy->getTerms(includeFields: false);

La méthode peut être appelé via get_terms() dans twig.


getPostTerms(Post|int|\WP_Post|null $post = null, bool $includeFields = true)​

Récupère les termes de la taxonomy pour un post spécifique.

Paramètres :

  • $post : Le post cible (objet Post, WP_Post, ID, ou null pour le post courant)
  • $includeFields : Si true, inclut les champs Carbon Fields (défaut : true)

Retourne : array - Tableau des termes du post

Exemple :

// Récupère les termes du post courant
$terms = $taxonomy->getPostTerms();

// Récupère les termes d'un post spécifique
$terms = $taxonomy->getPostTerms(42);

// Récupère les termes sans les champs
$terms = $taxonomy->getPostTerms(post: 42, includeFields: false);

// Avec un objet Post
use Elementum\Facades\Post;
$post = new Post(42);
$terms = $taxonomy->getPostTerms($post);

Dans Twig :

{# Récupère les termes du post courant #}
{% set terms = taxonomy.get_post_terms() %}

{% for term in terms %}
    <span>{{ term.name }}</span>
    {% if term.fields %}
        <small>{{ term.fields.ingredient_origin }}</small>
    {% endif %}
{% endfor %}

Utilisation dans Twig​

Via la façade Post​

{# Récupère une taxonomy depuis un post #}
{% set category = post.taxonomy('category') %}

{% if category %}
    <h2>{{ category.name }}</h2>

    {# Récupère les termes avec champs #}
    {% for term in category.get_terms() %}
        <span>{{ term.name }}</span>
    {% endfor %}
{% endif %}

Récupérer les termes d'un post​


{# Affiche les termes #}
{% if post.taxonomies('category') %}
    {% for term in post.taxonomies('category').get_terms() %}
        <span class="term">{{ term.name }}</span>
    {% endfor %}
{% endif %}

Avec les champs personnalisés​

{% for term in post.taxonomies('category').get_terms() %}
    <div class="term">
        <h3>{{ term.name }}</h3>
        {% if term.fields %}
            <p>Origine : {{ term.fields.ingredient_origin }}</p>
            <p>Description : {{ term.fields.ingredient_description }}</p>
        {% endif %}
    </div>
{% endfor %}

Exemples complets​

Post Type avec taxonomy et champs​

app/PostTypes/Recipe.php
use Elementum\Abstract\PostType;
use Carbon_Fields\Field;

class Recipe extends PostType
{
    public function slug(): string
    {
        return 'recipe';
    }

    public function labels(): array
    {
        return [
            'singular' => 'Recette',
            'plural' => 'Recettes'
        ];
    }

    public function taxonomies()
    {
        $this->addTaxonomy('ingredients', 'Ingrédients')
            ->isMale()
            ->setLabels([
                'plural' => 'Ingrédients',
                'singular' => 'Ingrédient',
            ])
            ->addContainerFields('Informations', [
                Field::make('text', 'ingredient_origin', 'Origine'),
                Field::make('textarea', 'ingredient_description', 'Description'),
            ])
            ->registerTaxonomyContainers()
            ->register();
    }
}

Controller avec taxonomy​

app/Controllers/RecipeController.php
use Elementum\Facades\Query;
use Elementum\Attributes\Template;

class RecipeController
{
    #[Template('single/recipe.html.twig')]
    public function show(int $id): array
    {
        $post = Query::find($id, 'recipe');

        // Charge les taxonomies
        $post->chargeTax(['ingredients']);

        return [
            'post' => $post,
            'ingredients' => $post->taxonomies['ingredients']
        ];
    }
}
views/single/recipe.html.twig
{% extends 'base.html.twig' %}

{% block content %}
    <article class="recipe">
        <h1>{{ post.title }}</h1>

        <div class="ingredients">
            <h2>Ingrédients</h2>

            {% if ingredients %}
                <ul>
                    {% for term in ingredients.terms %}
                        <li>
                            <strong>{{ term.name }}</strong>

                            {% if term.fields %}
                                <div class="term-details">
                                    {% if term.fields.ingredient_origin %}
                                        <span class="origin">
                                            Origine : {{ term.fields.ingredient_origin }}
                                        </span>
                                    {% endif %}

                                    {% if term.fields.ingredient_description %}
                                        <span class="description">
                                            {{ term.fields.ingredient_description }}
                                        </span>
                                    {% endif %}
                                </div>
                            {% endif %}
                        </li>
                    {% endfor %}
                </ul>
            {% endif %}
        </div>

        <div class="content">
            {{ post.content|raw }}
        </div>
    </article>
{% endblock %}

Bonnes pratiques​

  1. Typage fort : Depuis 26.0.10.0, $postType est typé PostType — utilisez-le pour accéder aux méthodes du post type
  2. Contexte post : Utilisez setCurrentPost() pour lier une taxonomy à un post spécifique
  3. Champs inclus par défaut : getTerms() et getPostTerms() incluent automatiquement les champs — utilisez includeFields: false pour désactiver
  4. Chaînage : La méthode register() retourne $this — profitez-en pour chaîner les appels

Voir aussi​