Trouver des entrées utilisant un type de bloc Matrix dans Craft CMS

Cette lacune dans les fonctionnalités de recherche intégrées de Craft prend plusieurs développeurs au dépourvu. L'indexation recherche le contenu des blocs Matrix, pas les identifiants de type de bloc. Cela signifie que chercher « callToAction » ne trouvera pas les entrées contenant ce type de bloc.

Nous avons constaté que ce problème revient régulièrement avant toute refactorisation majeure d'un champ Matrix. Ce guide vous présente les approches pratiques pour identifier l'utilisation des types de blocs à travers votre contenu, couvrant Craft 3/4 ainsi que les changements architecturaux de Craft 5.

Prérequis

Avant d'implémenter ces approches, vous aurez besoin de :

• Accès à vos gabarits Craft CMS (fichiers Twig)
• Familiarité de base avec les requêtes d'éléments Craft
• Connaissance de l'identifiant de votre champ Matrix et de l'identifiant du type de bloc recherché
• Accès administrateur ou développeur à votre installation Craft

Pour l'approche par base de données, vous aurez également besoin d'un accès direct à la base de données. Comprendre les fondamentaux des requêtes d'éléments Matrix dans Craft CMS vous aidera à adapter ces techniques à votre configuration spécifique.

Comprendre le problème

Les requêtes d'entrées Craft CMS peuvent filtrer les champs Matrix de quelques façons :

• :empty: trouve les entrées où le champ Matrix n'a pas de contenu
• :notempty: trouve les entrées où le champ Matrix contient des blocs
• Des identifiants de bloc spécifiques comme 100 ou [100, 200] filtrent par instances de bloc connues

Ce qui manque, c'est la capacité de dire « trouver toutes les entrées contenant au moins un bloc de type X ». L'identifiant du type de bloc n'est pas un paramètre recherchable sur les requêtes d'entrées.

L'approche qui fonctionne : interroger d'abord les blocs Matrix, puis remonter pour trouver leurs propriétaires.

Implémentation étape par étape pour Craft 3 et 4

Étape 1 : Créer un gabarit de diagnostic

Créez un fichier gabarit temporaire, quelque chose comme templates/_dev/block-finder.twig. Cela garde votre code de diagnostic séparé des gabarits de production.

Étape 2 : Interroger les blocs Matrix par type

Utilisez craft.matrixBlocks() avec le paramètre type pour trouver tous les blocs correspondant à votre type cible :

{% set targetBlocks = craft.matrixBlocks()
    .fieldId(123)
    .type('callToAction')
    .all() %}

Remplacez 123 par l'ID de votre champ Matrix, et 'callToAction' par l'identifiant de votre type de bloc. Cette approche de requête craft.matrixBlocks est la base pour suivre l'utilisation des types de blocs Matrix dans Craft CMS à travers votre site.

Étape 3 : Extraire les informations du propriétaire

Chaque bloc Matrix connaît son propriétaire. Parcourez les blocs et collectez les entrées parentes :

{% set ownerIds = [] %}
{% for block in targetBlocks %}
    {% set ownerIds = ownerIds|merge([block.ownerId]) %}
{% endfor %}

{% set ownerIds = ownerIds|unique %}

Étape 4 : Interroger les entrées propriétaires

Maintenant, récupérez les données réelles des entrées pour l'affichage :

{% set entries = craft.entries()
    .id(ownerIds)
    .all() %}

<h2>Entrées utilisant le bloc "callToAction" ({{ entries|length }} trouvées)</h2>
<ul>
{% for entry in entries %}
    <li>
        <a href="{{ entry.cpEditUrl }}">{{ entry.title }}</a>
        (ID: {{ entry.id }}, Section: {{ entry.section.name }})
    </li>
{% endfor %}
</ul>

Exemple complet fonctionnel

Voici le gabarit complet combinant toutes les étapes :

{# Block Finder - Find all entries using a specific Matrix block type #}

{% set fieldHandle = 'contentBlocks' %}
{% set blockTypeHandle = 'callToAction' %}

{# Get the field ID from the handle #}
{% set field = craft.app.fields.getFieldByHandle(fieldHandle) %}

{% if field %}
    {% set targetBlocks = craft.matrixBlocks()
        .fieldId(field.id)
        .type(blockTypeHandle)
        .all() %}
    
    {% set ownerIds = [] %}
    {% for block in targetBlocks %}
        {% set ownerIds = ownerIds|merge([block.ownerId]) %}
    {% endfor %}
    
    {% set ownerIds = ownerIds|unique %}
    
    {% if ownerIds|length %}
        {% set entries = craft.entries()
            .id(ownerIds)
            .all() %}
        
        <h2>Entrées utilisant "{{ blockTypeHandle }}" ({{ entries|length }} trouvées)</h2>
        <table>
            <thead>
                <tr>
                    <th>Titre</th>
                    <th>Section</th>
                    <th>ID</th>
                    <th>Modifier</th>
                </tr>
            </thead>
            <tbody>
            {% for entry in entries %}
                <tr>
                    <td>{{ entry.title }}</td>
                    <td>{{ entry.section.name }}</td>
                    <td>{{ entry.id }}</td>
                    <td><a href="{{ entry.cpEditUrl }}">Modifier</a></td>
                </tr>
            {% endfor %}
            </tbody>
        </table>
    {% else %}
        <p>Aucune entrée trouvée utilisant le type de bloc "{{ blockTypeHandle }}".</p>
    {% endif %}
{% else %}
    <p>Champ "{{ fieldHandle }}" introuvable.</p>
{% endif %}

Alternative : Approche par boucle simplifiée

Si vous préférez une approche plus directe qui ne nécessite pas de connaître l'ID du champ :

{% set entries = craft.entries.section('blog').all() %}

{% for entry in entries %}
    {% for block in entry.contentBlocks.all() %}
        {% if block.type.handle == 'callToAction' %}
            <p>{{ entry.title }} (ID: {{ entry.id }}) utilise ce bloc</p>
            {% break %}
        {% endif %}
    {% endfor %}
{% endfor %}

Cette approche est plus facile à lire mais moins performante sur les gros sites parce qu'elle charge toutes les entrées et tous leurs blocs.

Considérations pour Craft 5

Craft 5 a introduit un changement architectural important : les blocs Matrix ont été convertis en entrées lors de la mise à niveau. Les champs Matrix contiennent maintenant des entrées imbriquées avec des types d'entrées plutôt que les traditionnels « types de blocs ». Comprendre la migration des blocs Matrix vers Craft 5 est essentiel si vous effectuez une mise à niveau depuis des versions antérieures.

Cela signifie que l'approche de requête craft.matrixBlocks() de Craft 3/4 pourrait ne pas fonctionner de la même façon. À la place, vous interrogerez des entrées imbriquées et filtrerez par type d'entrée.

Notre expérience montre que le chemin de migration varie selon comment votre projet a été mis à niveau. Le concept de base reste le même cependant : interroger les éléments imbriqués par type, puis remonter vers leurs propriétaires. Consultez la documentation de Craft 5 pour la syntaxe de requête actuelle qui correspond à votre configuration.

Erreurs courantes à éviter

Oublier les brouillons et révisions

Par défaut, les requêtes de blocs Matrix dans Craft 4.x incluent des paramètres comme allowOwnerDrafts et allowOwnerRevisions. Si vous voulez seulement trouver l'utilisation dans le contenu publié, vous devrez peut-être exclure explicitement les brouillons :

{% set targetBlocks = craft.matrixBlocks()
    .fieldId(field.id)
    .type(blockTypeHandle)
    .allowOwnerDrafts(false)
    .allowOwnerRevisions(false)
    .all() %}

Résultats en double sur les installations multi-sites

Sur les installations multi-sites, la même entrée logique existe à travers les sites avec différentes versions spécifiques au site. Sans délimitation appropriée, vos résultats peuvent inclure des doublons. Ajoutez des contraintes de site si vous avez besoin de résultats spécifiques à un site :

{% set targetBlocks = craft.matrixBlocks()
    .fieldId(field.id)
    .type(blockTypeHandle)
    .siteId(currentSite.id)
    .all() %}

Exécuter en production sans pagination

Sur les sites avec des milliers d'entrées, charger tous les blocs et entrées d'un coup peut causer des problèmes de mémoire ou des délais d'expiration. Pour les gros ensembles de données, considérez :

• Exécuter la requête comme commande console au lieu d'une requête web
• Ajouter de la pagination pour traiter les blocs par lots
• Utiliser l'approche par requête de base de données pour les comptages bruts

Vérifier le mauvais champ

Si vous avez plusieurs champs Matrix avec des identifiants de type de bloc similaires, assurez-vous d'interroger le bon champ. Spécifiez toujours le paramètre fieldId pour éviter la confusion.

Tests et vérification

Après avoir exécuté votre gabarit de diagnostic :

1. Vérifiez quelques résultats : Ouvrez 3-5 des entrées signalées dans le panneau de contrôle et vérifiez qu'elles contiennent réellement le type de bloc recherché.

2. Vérifiez le compte : Si vous vous attendiez à environ 50 entrées utilisant ce type de bloc et que la requête en retourne 3, quelque chose ne va probablement pas avec votre identifiant de champ ou de type de bloc.

3. Testez avec une entrée connue : Trouvez une entrée que vous savez utiliser le type de bloc cible. Exécutez votre requête et confirmez que cette entrée apparaît dans les résultats.

4. Vérifiez les résultats vides : Si la requête ne retourne aucun résultat, revérifiez vos identifiants de champ et de type de bloc. Les fautes de frappe sont la cause la plus courante d'ensembles de résultats vides.

Alternatives avec des extensions

Si vous préférez ne pas écrire de requêtes personnalisées, quelques extensions peuvent aider :

• Craft Inspector et des extensions d'audit similaires peuvent visualiser l'utilisation des champs à travers votre contenu
• Related Elements fournit une fonctionnalité de recherche inversée pour les relations d'éléments

Ces extensions ne vous donneront pas nécessairement une fonctionnalité directe « trouver les entrées par type de bloc », mais elles peuvent aider avec les flux de travail d'audit de contenu.

Résumé

Trouver des entrées par type de bloc Matrix nécessite une recherche inversée : interroger d'abord les blocs par type, puis identifier leurs entrées parentes. L'approche fonctionne de manière fiable dans Craft 3 et 4, tandis que les changements architecturaux de Craft 5 nécessitent une adaptation au nouveau modèle d'entrées imbriquées.

Travailler avec des équipes nous a appris qu'exécuter ce genre d'audit avant toute refactorisation de champ Matrix fait gagner des heures de débogage par la suite. Les quelques minutes passées à vérifier l'utilisation des blocs préviennent les situations « quelque chose a brisé et on ne sait pas pourquoi » qui déraillent les projets.

Si vous planifiez une refactorisation importante de champ Matrix ou vous préparez pour une migration vers Craft 5, avoir des données précises sur votre structure de contenu actuelle est important. Nous aidons régulièrement des équipes à auditer leurs installations Craft CMS et à planifier des changements de modèle de contenu qui ne brisent pas les pages existantes. Contactez-nous si vous aimeriez de l'aide pour cartographier votre utilisation Matrix actuelle ou planifier votre approche de migration.