ワードプレスのadd_query_arg関数の使用方法・解説

概要

add_query_arg関数は、クエリーURIを更新するための便利なツールです。この関数を使うことで、URLのクエリ部分に新しい引数を追加したり、既存の引数の値を変更したりできます。以下はこの関数がよく使用されるシチュエーションの一例です。

1. フィルター付きのリストを表示する際にページネーションを管理する。
2. 特定のユーザーに関連するデータを表示する際のユーザーIDの管理。
3. フォームの送信後にフィードバックメッセージを表示するためのクエリパラメータを追加する。
4. 検索結果やフィルタリングされたコンテンツのリンクを生成する。
5. カスタムクエリを作成したいときに引数を簡単に組み立てる。
6. 追跡用のUTMパラメータを動的に追加する。
7. ソーシャルメディアシェアリンクの構築。
8. AJAXリクエストのURLを構築する際のパラメータ管理。

構文

add_query_arg( $key, $value, $url );

パラメータ

• $key: 追加または変更したいクエリ文字列のキー。
• $value: キーに対して設定する値。配列の場合は、自動的に続けてキーが作成される。
• $url: 更新対象のURL。省略した場合は、現在のURLが使用される。

戻り値

新しいクエリ文字列が追加されたURLを返します。

関連する関数

• remove_query_arg
• esc_url

使用可能なバージョン

この関数はWordPress 2.8.0以降で使用可能です。

コアファイルのパス

wp-includes/formatting.php

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

アクション名	使用可能性
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

サンプルコード

1. クエリパラメータを追加する: このコードでは、URLにpageというクエリパラメータを追加します。

   $url = add_query_arg('page', '2', 'http://example.com');
   // 結果: http://example.com?page=2
   

2. 複数のパラメータを追加する: URLに複数のクエリパラメータを追加することができます。

   $url = add_query_arg(array('page' => '2', 'sort' => 'asc'), 'http://example.com');
   // 結果: http://example.com?page=2&sort=asc
   

3. 既存のパラメータを変更する: add_query_argを使って、既存のパラメータを変更することができます。

   $url = add_query_arg('page', '3', 'http://example.com?page=2');
   // 結果: http://example.com?page=3
   

4. URLを保持しつつ新しいパラメータを追加する: 現在のURLに新しいパラメータを追加します。

   $current_url = 'http://example.com?page=1';
   $new_url = add_query_arg('filter', 'active', $current_url);
   // 結果: http://example.com?page=1&filter=active
   

5. プラグイン内で使用する: プラグインの機能でURLを動的に生成する例です。

   function my_plugin_url() {
       return add_query_arg('action', 'my_action', home_url());
   }
   // 結果: http://example.com/?action=my_action
   

これらのサンプルコードは、WordPressのadd_query_arg関数の使用方法を示すための基本的な例です。これらのコードを参考にして、自分のプロジェクトでのクエリ文字列の生成や管理に活かしてください。