コンテンツにスキップ

WordPress の関数 register_meta() の使い方まとめ

メインイメージ

WordPress でメタデータ（カスタムフィールド）を登録するための関数 register_meta() についてまとめました。

register_meta( $object_type, $meta_key, $args );

Note

register_meta() は汎用の関数です。 これとは別に投稿専用の register_post_meta() という関数もあります。 投稿・固定ページ・カスタム投稿タイプにカスタムフィールドを追加したいときは register_post_meta() を使用してください。 ちなみに、 register_post_meta() はほとんどの引数を register_meta() に渡すラッパー関数となっています。

基本的な使い方

register_meta() は通常 init フックのコールバック内で実行して使用します。 関数に渡すべき引数は次の 3 つです。

  1. オブジェクトタイプ（文字列）
  2. メタキー（文字列）
  3. 設定（連想配列）
add_action( 'init', 'myplugin_register_meta' );
function myplugin_register_meta() {
  // メタデータを登録する
  $object_type = 'post';
  $meta_key = 'my_meta_key';
  $args = [
    // 格納する値の型:
    'type' => 'string',
    // 説明:
    'description' => 'カスタムメタデータの説明',
    // 各投稿オブジェクトに対して保存できる値を 1 つだけにするかどうか:
    'single' => true,
    // 値のデフォルト値:
    'default' => 'デフォルト値',
    // REST API でフィールドを公開するかどうか:
    'show_in_rest' => true,
  ];
  register_meta( $object_type, $meta_key, $args );
}

厳密には第 4 引数もありますが deprecrated 扱いとなっており使用することはありません。 戻り値は登録結果を表す boolean （ true / false ）です。

引数・戻り値

以下引数と戻り値の説明です。

第 1 引数 $object_type string

メタデータを追加する先のオブジェクトタイプ。 通常次のうちのどれかを指定する。

  • post: 投稿、固定ページ、カスタム投稿タイプ
  • comment: コメント
  • term: タクソノミーターム
  • user: ユーザー

第 2 引数 $meta_key string

メタデータのキー（名前）。

第 3 引数 $args array

メタデータの設定を指定するための連想配列。

$args = [
'object_subtype' => '...',
'type' => '...',
'description' => '...',
'single' => true,
'default' => '',
'sanitize_callback' => '',
'auth_callback' => '',
'show_in_rest' => true,
'revisions_enabled' => true,
];

指定可能なキーは次のとおり。

object_subtype (string)

オブジェクトのサブタイプ。 例えば $object_type が post の場合は投稿タイプを指す。 デフォルトは空文字列で、空文字列の場合はそのオブジェクトタイプすべてに適用される。

type (string)

メタデータの型。 以下の値が指定可能。

  • string: 文字列
  • boolean: 真偽値
  • integer: 整数
  • number: 数値
  • array: 配列
  • object: オブジェクト

デフォルトは string。

description (string)

説明。

single (bool)

メタデータが単一の値か複数の値か。 true の場合は単一の値、 false の場合は複数の値を持つことができる。 デフォルトは false。

default (mixed)

値がセットされていないときに get_metadata() が返すデフォルト値。 get_metadata() を引数 $single を false で呼び出した場合はこの値を格納した配列が返される。 WordPress 5.5 で追加された。

sanitize_callback (callable)

サニタイジングに使用される関数。 sanitize_meta() で使用される。 sanitize_meta() は add_metadata() update_metadata() などで使用される。

auth_callback (callable)

edit_post_meta add_post_meta delete_post_meta の権限チェックで使用される関数。 これらは current_user_can() 関数で使用される。

show_in_rest (bool|array)

REST API でメタデータを公開するかどうか。 カスタム投稿タイプの場合は、この値が true であることに加えて custom-fields が supports に含まれている必要がある。 現状ではブロックエディタでメタデータ（カスタムフィールド）を編集できるようにするためにはこの値を true にしなくてはならない。 複雑な設定をしたい場合は boolean の代わりに schema と prepare_callback というキーを持つ連想配列をセットするとよい。 デフォルトは false。

revisions_enabled (bool)

リビジョン機能を有効にするかどうか。 WordPress 6.4 で追加された。

デフォルト値まとめ

キー デフォルト値
object_subtype ''
type 'string'
description ''
default ''
single false
sanitize_callback null
auth_callback null
show_in_rest false
revisions_enabled false

サンプルコード

サンプル A. 基本的な使い方

add_action( 'init', 'myplugin_register_meta' );
function myplugin_register_meta() {
  register_meta( 'post', 'my_custom_meta', [
    'type' => 'string',
    'single' => true,
    'show_in_rest' => true,
  ] );
}

このコードは my_custom_meta という名前のメタデータを登録します。型は文字列で、単一の値を持ち、REST API で利用可能です。

サンプル B. リビジョン機能を使う

add_action( 'init', 'myplugin_register_meta' );
function myplugin_register_meta() {
  register_meta( 'post', 'my_year', [
    'type' => 'integer',
    'single' => false,
    'revisions_enabled' => true,
  ] );
}

このコードは my_year という名前のメタデータを登録します。型は整数値で、複数の値を持ち、投稿のリビジョン機能をサポートしています。

サンプル C. カスタムサニタイズ関数を使う

add_action( 'init', 'myplugin_register_meta' );
function myplugin_register_meta() {
  register_meta( 'post', 'my_custom_number', [
    'type' => 'integer',
    'single' => true,
    'show_in_rest' => true,
    'sanitize_callback' => 'myplugin_sanitize_number',
  ] );
}

function myplugin_sanitize_number( $meta_value, $meta_key, $object_type, $object_subtype ) {
  return absint( $meta_value );
}

このサンプルでは、my_custom_number というメタデータを登録し、カスタムのサニタイズ関数を使用して、値が必ず正の整数になるようにしています。

サンプル D. 権限チェック関数を使う

add_action( 'init', 'myplugin_register_meta' );
function myplugin_register_meta() {
  register_meta( 'post', 'my_restricted_field', [
    'type' => 'string',
    'single' => true,
    'show_in_rest' => true,
    'auth_callback' => 'myplugin_check_meta_permission',
  ] );
}

function myplugin_check_meta_permission( $allowed, $meta_key, $post_id, $user_id, $cap, $caps ) {
  return current_user_can( 'edit_post', $post_id );
}

このサンプルでは、my_restricted_field というメタデータを登録し、カスタムの権限チェック関数を使用して、投稿を編集する権限を持つユーザーのみがこのフィールドを編集できるようにしています。

WordPress.org 参考ページ / WordPress コード

確認時のバージョン

  • WordPress 6.6.2

関連ページ