Rechercher et trier la médiathèque par métadonnées personnalisées

Un studio de photographie qui alimentait sa médiathèque WordPress avec plusieurs centaines de visuels par mois avait besoin de retrouver rapidement une image à partir de son numéro de référence interne, enregistré en meta lors de l’import. La recherche native de la médiathèque, elle, ne porte que sur le titre, la légende et le texte alternatif : un numéro de référence stocké en champ personnalisé restait invisible pour cette recherche, quel que soit le nombre de caractères tapés dans le champ.

La médiathèque, qu’elle soit affichée en grille dans l’écran dédié ou dans le sélecteur de média ouvert depuis l’éditeur, repose sur une requête AJAX qu’il est possible d’étendre pour inclure une recherche sur un champ personnalisé.

Comprendre la requête concernée

La médiathèque en mode grille interroge le point d’entrée AJAX query-attachments, dont les arguments transitent par le filtre ajax_query_attachments_args avant l’exécution de la requête WP_Query sous-jacente :

add_filter( 'ajax_query_attachments_args', function ( $args ) {
    if ( ! empty( $_REQUEST['query']['s'] ) ) {
        $recherche = sanitize_text_field( $_REQUEST['query']['s'] );

        // Recherche à la fois dans les champs natifs et dans la meta référence
        $args['meta_query'] = [
            'relation' => 'OR',
            [
                'key'     => 'reference_studio',
                'value'   => $recherche,
                'compare' => 'LIKE',
            ],
        ];
    }

    return $args;
} );

Ne pas exclure la recherche native au passage

Le piège de cette approche : en ajoutant un meta_query, le mot-clé s reste actif dans $args et continue de filtrer sur le titre. Sur cette recherche combinée, WordPress applique une intersection (ET logique) entre la recherche texte native et le meta_query ajouté, ce qui exclut les résultats qui correspondent uniquement à la référence et pas au titre. La solution consiste à retirer le mot-clé natif et à reproduire sa logique dans le meta_query :

add_filter( 'ajax_query_attachments_args', function ( $args ) {
    if ( empty( $_REQUEST['query']['s'] ) ) {
        return $args;
    }

    $recherche = sanitize_text_field( $_REQUEST['query']['s'] );
    unset( $args['s'] ); // On retire la recherche native pour la reproduire nous-mêmes

    add_filter( 'posts_where', function ( $where ) use ( $recherche ) {
        global $wpdb;
        $where .= $wpdb->prepare(
            " OR ({$wpdb->posts}.post_title LIKE %s)",
            '%' . $wpdb->esc_like( $recherche ) . '%'
        );
        return $where;
    } );

    $args['meta_query'] = [
        [
            'key'     => 'reference_studio',
            'value'   => $recherche,
            'compare' => 'LIKE',
        ],
    ];

    return $args;
} );

Trier par métadonnée plutôt que seulement filtrer

Au-delà de la recherche, un tri par référence peut aussi être utile, en s’appuyant sur meta_key et orderby dans les mêmes arguments, à condition que la médiathèque affiche une option de tri correspondante côté interface, ce qui demande un script supplémentaire pour ajouter cette option au menu déroulant de tri natif :

add_filter( 'ajax_query_attachments_args', function ( $args ) {
    if ( ! empty( $_REQUEST['query']['orderby'] ) && 'reference_studio' === $_REQUEST['query']['orderby'] ) {
        $args['meta_key'] = 'reference_studio';
        $args['orderby']  = 'meta_value';
        $args['order']    = 'ASC';
    }

    return $args;
} );

Vérifier les deux points d’entrée de la médiathèque

• L’écran Médiathèque classique, accessible depuis le menu d’administration, utilise ce même filtre AJAX en mode grille.
• Le sélecteur de média ouvert depuis l’éditeur de blocs (bloc Image, Galerie) passe par le même point d’entrée, ce qui rend ce filtre utile aux deux endroits sans code supplémentaire.
• La médiathèque en mode liste, plus ancienne, repose sur une requête classique côté serveur et non sur cette requête AJAX : un filtre distinct sur pre_get_posts serait nécessaire pour ce mode d’affichage.

Une médiathèque de plusieurs centaines de fichiers sans recherche par référence interne n’est plus une médiathèque, c’est une pile d’images qu’on retrouve à la mémoire ou pas du tout.

En résumé

Le filtre ajax_query_attachments_args permet d’étendre la recherche native de la médiathèque à n’importe quel champ personnalisé, à condition de gérer soi-même la combinaison avec la recherche texte native pour ne pas exclure de résultats par inadvertance. Ce réglage, invisible pour l’utilisateur final, change concrètement la façon dont une équipe retrouve ses fichiers au quotidien.