WordPressのユーザーメタの使い方（get_user_meta・プロフィール欄の追加・WP-CLI）

ユーザーメタは、ユーザーごとに追加の情報（電話番号、会社名、ポイントなど）を保存する仕組みです。値はデータベースの wp_usermeta テーブル（接頭辞が wp_ の場合）に、ユーザーID・キー・値の組で保存されます。プラグインやテーマの functions.php から、専用の関数で読み書きします。

この記事の関数とフックの動きは、WordPress 本体のソースコード（6.9）で確認しています。

基本の4つの関数

<?php
$user_id = get_current_user_id(); // ログイン中のユーザーのID（未ログインなら 0）

// 追加: 4番目の引数を true にすると、同じキーがすでにあれば追加しない
add_user_meta( $user_id, 'myplugin_points', 0, true );

// 取得: 3番目の引数を true にすると値を1つだけ返す
$points = (int) get_user_meta( $user_id, 'myplugin_points', true );

// 更新: キーがなければ追加される
update_user_meta( $user_id, 'myplugin_points', $points + 10 );

// 削除
delete_user_meta( $user_id, 'myplugin_points' );

取得した値の型には注意が必要です。数値や真偽値は文字列としてデータベースに入るため、100 を保存しても "100" が返り、false を保存すると "" が返ります。数値として使うときは (int) などで変換します。配列を保存した場合は、WordPress がシリアライズして保存し、取得時に配列に戻します。

キーには、ほかのプラグインと重ならないように、プラグイン名などの接頭辞を付けます（この記事では myplugin_）。

プロフィール画面に入力欄を追加する

管理画面の「プロフィール」と「ユーザーを編集」の画面に、電話番号と会社名の入力欄を追加する例です。

<?php
// 入力欄を表示する（$user は WP_User）
add_action( 'show_user_profile', 'myplugin_profile_fields' );
add_action( 'edit_user_profile', 'myplugin_profile_fields' );

function myplugin_profile_fields( $user ) {
	$phone   = get_user_meta( $user->ID, 'myplugin_phone', true );
	$company = get_user_meta( $user->ID, 'myplugin_company', true );
	?>
	<h2>追加情報</h2>
	<table class="form-table" role="presentation">
		<tr>
			<th><label for="myplugin_phone">電話番号</label></th>
			<td><input type="tel" id="myplugin_phone" name="myplugin_phone" value="<?php echo esc_attr( $phone ); ?>" class="regular-text"></td>
		</tr>
		<tr>
			<th><label for="myplugin_company">会社名</label></th>
			<td><input type="text" id="myplugin_company" name="myplugin_company" value="<?php echo esc_attr( $company ); ?>" class="regular-text"></td>
		</tr>
	</table>
	<?php
}

// 保存する
add_action( 'personal_options_update', 'myplugin_save_profile_fields' );
add_action( 'edit_user_profile_update', 'myplugin_save_profile_fields' );

function myplugin_save_profile_fields( $user_id ) {
	if ( ! current_user_can( 'edit_user', $user_id ) ) {
		return;
	}
	if ( isset( $_POST['myplugin_phone'] ) ) {
		update_user_meta( $user_id, 'myplugin_phone', sanitize_text_field( wp_unslash( $_POST['myplugin_phone'] ) ) );
	}
	if ( isset( $_POST['myplugin_company'] ) ) {
		update_user_meta( $user_id, 'myplugin_company', sanitize_text_field( wp_unslash( $_POST['myplugin_company'] ) ) );
	}
}

• 保存のフックが呼ばれる前に、WordPress 本体の wp-admin/user-edit.php が check_admin_referer( 'update-user_' . $user_id ) でフォームのノンスを確かめています。そのため、このフォームで独自のノンスを追加する必要はありません。権限は current_user_can( 'edit_user', $user_id ) で確かめます。
• $_POST の値には WordPress がバックスラッシュを付けているため、wp_unslash() で外してから sanitize_text_field() で整えます。

保存できたかは、プロフィールを保存したあと画面を再読み込みして、入力した値が残っているかで確かめます。

メタの値でユーザーを絞り込む

get_users() に meta_key などを渡すと、メタの値でユーザーを絞り込めます。数値として比べるときは meta_type を NUMERIC にします。指定しないと文字列として比べられ、"9" が "100" より大きいと判定されます。

<?php
// ポイントが100以上のユーザーを、ポイントの多い順に20人
$users = get_users( array(
	'meta_key'     => 'myplugin_points',
	'meta_value'   => 100,
	'meta_compare' => '>=',
	'meta_type'    => 'NUMERIC',
	'orderby'      => 'meta_value_num',
	'order'        => 'DESC',
	'number'       => 20,
) );

foreach ( $users as $user ) {
	$points = (int) get_user_meta( $user->ID, 'myplugin_points', true );
	echo esc_html( $user->display_name . ': ' . $points . 'ポイント' ) . '<br>';
}

// 電話番号のメタが登録されていないユーザー
$no_phone = get_users( array(
	'meta_query' => array(
		array(
			'key'     => 'myplugin_phone',
			'compare' => 'NOT EXISTS',
		),
	),
) );

メタの値での絞り込みは、ユーザー数が多いと遅くなります。頻繁に使う一覧は、結果を一時的に保存する（トランジェントなど）ことも検討します。

WP-CLI でユーザーメタを確認・変更する

WP-CLI の wp user meta コマンドで、ユーザーメタを確認・変更できます。<user> にはユーザーIDかログイン名、メールアドレスを指定します。

# ユーザー ID 1 のメタをすべて表示
wp user meta list 1

# 特定のキーの値を表示
wp user meta get 1 myplugin_points

# 値を変更（キーがなければ追加）
wp user meta update 1 myplugin_points 500

# 削除
wp user meta delete 1 myplugin_points

wp user list には get_users() と同じ引数を --引数名=値 の形で渡せます。

# ポイントが 0 より大きいユーザーの一覧
wp user list --meta_key=myplugin_points --meta_value=0 --meta_compare='>' --meta_type=NUMERIC --fields=ID,user_login,display_name

# 同じ条件の人数だけを表示
wp user list --meta_key=myplugin_points --meta_value=0 --meta_compare='>' --meta_type=NUMERIC --format=count

ユーザーの作成や権限の変更などは「WP-CLIのuserコマンドの使い方」で説明しています。

全ユーザーに初期値を一括で設定する

プラグインの新機能で、既存の全ユーザーに初期値を入れたい場合の例です。wp eval に長いコードを書くと、シェルの引用符やエスケープで崩れやすいため、PHP ファイルにして wp eval-file で実行します。

<?php
// init-points.php（実行: wp eval-file init-points.php）
$user_ids = get_users( array( 'fields' => 'ID' ) );
$count    = 0;

foreach ( $user_ids as $user_id ) {
	// キーがまだないユーザーにだけ 0 を入れる
	if ( ! metadata_exists( 'user', (int) $user_id, 'myplugin_points' ) ) {
		add_user_meta( (int) $user_id, 'myplugin_points', 0, true );
		$count++;
	}
}

WP_CLI::success( $count . ' users initialized' );

• metadata_exists() は、キーが存在するかだけを調べます。get_user_meta() の結果で判定すると、値が 0 のユーザーも「なし」と判定されてしまいます。
• マルチサイトでは、get_users() は既定で今のサイトに属するユーザーだけを返します。
• 本番で実行する前に、データベースのバックアップを取ります。

REST API でユーザーメタを扱う

ユーザーメタは、標準では REST API（/wp-json/wp/v2/users/<id>）に含まれません。ブロックエディターや外部のアプリから読み書きしたい場合は、register_meta() で登録して show_in_rest を true にします。

<?php
add_action( 'init', function () {
	register_meta( 'user', 'myplugin_points', array(
		'type'              => 'integer',
		'single'            => true,
		'default'           => 0,
		'show_in_rest'      => true,
		'sanitize_callback' => 'absint',
	) );
} );

default を登録すると、キーがないユーザーに対して get_user_meta( $id, 'myplugin_points', true ) は空文字ではなくその値（ここでは 0）を返すようになります。

登録すると、ユーザーの REST の応答の meta に値が入り、そのユーザーを編集する権限がある人は値を更新できます。キーを _ で始めると「保護されたメタ」として扱われ、auth_callback で許可しないかぎり REST から更新できません。

注意点

• パスワードや API キーのような秘密の情報は、ユーザーメタに平文で保存しないようにします。
• プラグインを削除するときにメタも消す場合は、uninstall.php で delete_metadata( 'user', 0, 'myplugin_points', '', true ) のように全ユーザー分を削除します（5番目の引数 true で全ユーザーが対象になる）。
• 投稿に付けるメタ（カスタムフィールド）は、別の関数（get_post_meta() など）と別のテーブル（wp_postmeta）を使います。

まとめ

• ユーザーメタは add_user_meta()・get_user_meta()・update_user_meta()・delete_user_meta() で読み書きし、取得した値は文字列なので必要に応じて型を変換する
• プロフィール画面の入力欄は show_user_profile・edit_user_profile で表示し、personal_options_update・edit_user_profile_update で権限を確かめて保存する
• 数値で絞り込むときは meta_type を NUMERIC にする
• WP-CLI では wp user meta で確認・変更し、一括処理は wp eval-file で実行する