概要
add_user_meta関数は、WordPressにおいてユーザーメタ情報を追加するための機能を提供します。以下のような状況でよく使用されます。
- ユーザーのプロフィール情報を拡張する。
- 特定のユーザーに対するカスタム設定を保存する。
- プラグインやテーマが必要とするユーザー関連データを管理する。
- 特定の条件や役割を持つユーザーに対する情報を記録する。
- ユーザーのレベルやポイントシステムを管理する。
- ユーザーの行動履歴をトラッキングする。
- ユーザーがアップロードしたコンテンツや情報を補足する。
- 特定のユーザーに対するカスタムフィールドを作成する。
構文
add_user_meta( int $user_id, string $meta_key, mixed $meta_value, bool $unique = false );
パラメータ
user_id(int) – 必須。メタ情報を追加するユーザーのID。meta_key(string) – 必須。メタ情報のキー。meta_value(mixed) – 必須。メタ情報の値。unique(bool) – 任意。指定されたキーに対して一意の値のみを追加するかどうか（デフォルトは false）。
戻り値
- 成功した場合は新しく追加されたメタ情報のIDを返し、失敗した場合は false を返します。
関連する関数
使用可能なバージョン
add_user_meta関数は、WordPress 1.2 以降で利用可能です。
コアファイルのパス
/wp-includes/user.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: 新しいユーザーメタ情報を追加する
add_action('user_register', 'add_custom_user_meta');
function add_custom_user_meta($user_id) {
add_user_meta($user_id, 'favorite_color', 'blue');
}
このサンプルコードは、新しいユーザーが登録された際に、そのユーザーのメタ情報として「favorite_color」を「blue」として追加します。
サンプル2: ユーザーメタ情報を一意として追加する
add_action('user_register', 'add_unique_user_meta');
function add_unique_user_meta($user_id) {
add_user_meta($user_id, 'unique_key', 'some_value', true);
}
このコードは、新しいユーザー登録時に「unique_key」というメタ情報を一意として追加します。他のメタ情報が同じキーで存在する場合は追加されません。
サンプル3: ユーザーのカスタムデータを更新する
function update_user_data($user_id) {
update_user_meta($user_id, 'custom_data', 'new_value');
}
このサンプルでは、指定したユーザーIDの「custom_data」を「new_value」に更新します。
サンプル4: メタ情報が存在しない場合は追加する
function add_meta_if_not_exists($user_id) {
if (!get_user_meta($user_id, 'meta_key', true)) {
add_user_meta($user_id, 'meta_key', 'default_value');
}
}
このコードは、指定したユーザーに「meta_key」が存在しない場合にのみ、「default_value」としてメタ情報を追加します。
サンプル5: 複数の値を持つユーザーメタ情報を追加する
function add_multiple_values_meta($user_id) {
add_user_meta($user_id, 'skills', 'php');
add_user_meta($user_id, 'skills', 'javascript');
}
このサンプルコードは、ユーザーに対して「skills」というメタ情報をPHPとJavaScriptの2つの値で追加する方法を示しています。