ワードプレスのbuild_queryフィルタの使用方法・解説

概要

build_query フィルタは、連想配列からページ用のクエリー文字列を作る際に使用されます。これは、データベースから情報を取得するために、特定のパラメータをURL形式で構成するために役立ちます。このフィルタを使うことで、開発者はカスタマイズされたクエリー文字列を簡単に生成し、特定の条件に基づいたデータを取得できます。

よく使われる機能

1. カスタムURL生成
2. クエリー引数のフィルタリング
3. SEO最適化のためのURL構造の変更
4. ページネーションのカスタマイズ
5. 特定のユーザー情報によるクエリの調整
6. プラグイン間のURL構造の整合性を保持
7. 外部APIとの連携時のURL生成
8. カスタム投稿タイプのフィルタリングやソート

構文

apply_filters( 'build_query', string $query, array $args );

パラメータ

• $query (string): 作成されたクエリー文字列。
• $args (array): クエリーのための引数を含む連想配列。

戻り値

• (string): 変更されたクエリー文字列。

関連する関数

build_query

使用可能なバージョン

build_query フィルタは、WordPress 2.7 以降のバージョンで使用可能です。

コアファイルのパス

wp-includes/query.php

サンプルコード

サンプル1: カスタムクエリー文字列の生成

add_filter( 'build_query', 'custom_build_query' );

function custom_build_query( $query, $args ) {
    if ( isset( $args['custom_param'] ) ) {
        $query .= '&custom_param=' . esc_attr( $args['custom_param'] );
    }
    return $query;
}

このコードは、カスタムパラメータが存在する場合、そのパラメータをクエリーに追加します。

サンプル2: URLのクリーンアップ

add_filter( 'build_query', 'clean_up_query' );

function clean_up_query( $query, $args ) {
    return str_replace( array( '&&', '&' ), '&', $query );
}

このコードは、クエリー内の重複や不要なエンコードを削除します。

サンプル3: 余分なパラメータの削除

add_filter( 'build_query', 'remove_extra_params' );

function remove_extra_params( $query, $args ) {
    parse_str( $query, $parsed_query );
    unset( $parsed_query['unwanted_param'] );
    return http_build_query( $parsed_query );
}

このコードは、特定の不要なパラメータをクエリーから削除します。

サンプル4: クエリーのデバッグ

add_filter( 'build_query', 'debug_query' );

function debug_query( $query, $args ) {
    error_log( 'Current Query: ' . $query );
    return $query;
}

このコードは、生成されたクエリーをログに出力し、デバッグ作業を容易にします。

サンプル5: POSTリクエスト用のクエリー作成

add_filter( 'build_query', 'post_query_builder' );

function post_query_builder( $query, $args ) {
    if ( isset( $args['post_id'] ) ) {
        $query .= '&post_id=' . intval( $args['post_id'] );
    }
    return $query;
}

このコードは、POSTリクエスト用に追加のパラメータをクエリーに付加します。

この関数のアクションでの使用可能性

アクション	使用可能性
mu_plugin_loaded
registered_post_type
plugins_loaded
wp_roles_init
setup_theme
after_setup_theme
set_current_user
init
register_sidebar
wp_loaded
send_headers
parse_query	〇
pre_get_posts	〇
wp	〇
template_redirect	〇
get_header
wp_head

このフィルタは特定のWordPressバージョンで非推奨又は削除されている情報はありません。