add_role() の使い方｜説明・引数・注意点

説明

基本構文

add_role( string $role, string $display_name, bool[] $capabilities = array() ): WP_Role|null

引数

• $role：ロールの識別名
• $display_name：表示名
• $capabilities：権限の配列

戻り値

WP_Role。既に存在すれば null。

使い方（サンプル）

add_role( 'shop_manager', 'ショップ管理者', array(
	'read'       => true,
	'edit_posts' => true,
) );

注意点

• ロールはデータベースに保存されるため、毎回のリクエストで呼ばず、プラグイン有効化時に1度だけ実行します。
• 不要になったら remove_role() で削除します。

実務での使いどころ

• プラグインの有効化時に、独自のロール（クライアント用など）を作るとき。
• 既存のロールの権限をまとめた、新しいロールを作るとき。

よくあるミスと対処

• 毎回のリクエストで呼んでいる。ロールはデータベースに保存されるため、有効化時など、1回だけ呼ぶ。
• すでに同じ名前のロールがあると、何もせず null が返る。
• 不要になったロールを、削除していない。アンインストール時に、remove_role() で削除する。

NG例

add_action( 'init', function () {
	add_role( 'client', 'クライアント', array( 'read' => true ) ); // 毎回呼ばれる
} );

OK例

register_activation_hook( __FILE__, function () {
	add_role( 'client', 'クライアント', array( 'read' => true, 'edit_posts' => true ) );
} );

使い分け早見表

関連項目

remove_role()、get_role()、add_cap()

公式リファレンス：add_role() | Function | WordPress Developer Resources