WordPressの設定画面への項目追加方法まとめ

WordPressの設定メニュー内の「一般」「投稿設定」「表示設定」「ディスカッション」「メディア」「プライバシー」「パーマリンク設定」の７ページでは、ほぼ同一の手法で独自の項目を追加することができます。この追加方法と各設定画面における追加可能な場所をまとめてみました。
※ 「パーマリンク設定」ページでは、項目の表示追加方法は同じですが、データの保存方法が異なります。

設定画面の構成

設定ページでは、同一機能に関する項目をまとめたものをセクション、セクションが集まって１つの設定画面を構成し、これをページと捉えます。
設定画面では、ページに対してセクションを追加したり、セクションに対して項目が追加できるようになっています。

項目の表示追加

項目の表示追加は、add_settings_field関数を用いて行います。追加する項目が複数ある場合の表示順は、add_settings_field関数が実行された順となります。

add_settings_field( $id, $title, $callback, $page, $section = 'default', $args = array() );

add_settings_field関数は、最大で６つの引数を指定することができます。引数に指定する内容は下記の通り。

$id

独自項目のid。同一ページ、同一セクション内で重複しないことが必要。（重複した場合、後から登録した項目が優先される）

$title

設定画面に表示される項目名

$callback

フォームを表示するためのコールバック関数名

$page

項目を表示させるページ。各設定ページにおけるパラメータは次の通り。
設定：general、投稿設定：writing、表示設定：reading、ディスカッション：discussion、メディア：media、プライバシー：privacy、パーマリンク設定：permalink

$section

項目を表示させるセクション名。最上部の見出しの無いセクションでは default となります。各設定画面におけるセクション名は後述

$args

コールバック関数への引数となる他、label_for の指定すると、項目名をlabelタグで囲む事が可能

サンプルコード

function add_general_custom_fields() {
	add_settings_field( 'twitter', 'ツイッター', 'custom_twitter_field', 'general', 'default', array( 'label_for' => 'twitter_account' ) );
}
add_action( 'admin_init', 'add_general_custom_fields' );

function custom_twitter_field( $args ) {
	$twitter_account = get_option( 'twitter_account' );
?>
	@<input type="text" name="twitter_account" id="twitter_account" size="30" value="<?php echo esc_html( $twitter_account ); ?>" />
<?php
}

データの保存

add_settings_field関数にて、設定画面にフォームを追加することはできましたが、これだけでは、データの保存はできません。WordPressは内部的に各設定画面でデータの保存を許可する項目名を有しており、この項目名に独自の項目を追加する必要があるのです。
このデータは、wp-admin/options.phpに記述されている $whitelist_options という配列がそれで、ページ名をキーとし、有効な項目の配列を値としています。
この $whitelist_options をフックできる whitelist_options にフックして独自の項目を追加すれば、データベースへの保存処理はWordPress側で全て行ってくれます。
※ 但し、形式チェックなどデータのバリデートは一切行われません。

サンプルコード

function add_custom_whitelist_options_fields( $whitelist_options ) {
	$whitelist_options['general'][] = 'twitter_account';
	return $whitelist_options;
}
add_filter( 'whitelist_options', 'add_custom_whitelist_options_fields' );

※ ここで追加する項目名は、追加したフォームのname属性と合わせることが必要。

[2012.4.30追記]
register_setting 関数を使えば、直接 whitelist_options にフックせずに項目を追加でき、さらにサニタイズ（無害化）を行うための関数指定までできることが分かりました。
上記のコードを register_setting で行う場合下記のようになります。

サンプルコード

function add_custom_whitelist_options_fields() {
	register_setting( 'general', 'twitter_account' );
}
add_filter( 'admin_init', 'add_custom_whitelist_options_fields' );

パーマリンク設定でのデータ保存

パーマリンク設定のデータ保存は、他の設定画面と経路が異なっているため（更新時にパーリンク構造やリライトルールの再構築を行うなど独自処理が必要であるため）上述のフックの方法は使えません。
管理画面での初期設定が完了したあとに行われる load-options-permalink.php へのフック等にて独自にデータベースへの保存処理を組み込む必要があります。

サンプルコード

function update_twitter_account() {
	if ( isset( $_POST['submit'] ) && isset( $_POST['twitter_account'] ) && current_user_can( 'manage_options' ) ) {
		check_admin_referer('update-permalink');
		$twitter_account = stripslashes_deep( $_POST['twitter_account'] );
		if ( preg_match( '/^[a-zA-Z0-9_]{1,15}$/', $twitter_account ) ) {
			update_option( 'twitter_account', $twitter_account );
		}
	}
}
add_action( 'load-options-permalink.php', 'update_twitter_account' );

セクションの追加

各設定画面には、既存のセクション以外に、add_settings_section関数を使って独自のセクションを組み込むことが可能となっています。複数のセクションを追加する場合、セクションの表示順は、add_settings_section関数が実行された順となります。

add_settings_section( $id, $title, $callback, $page );

$id

独自セクションのid。このセクションにadd_settings_field関数で項目を追加する際のセクション名ともなる。

$title

セクションの見出しとして表示されるタイトル

$callback

見出し下で実行されるコールバック関数名。ことコールバック関数でセクションの説明文を表示させることなどが可能

$page

項目を表示させるページ。指定できるパラメータはadd_settings_field関数と同一。

サンプルコード

function add_custom_options_fields( $whitelist_options ) {
	$whitelist_options['general'][] = 'twitter_account';
	$whitelist_options['general'][] = 'facebook_account';
	return $whitelist_options;
}
add_filter( 'whitelist_options', 'add_custom_options_fields' );

function add_general_custom_sections() {
	add_settings_section( 'social', 'ソーシャルサービスアカウント', 'social_section_message', 'general' );
	add_settings_field( 'twitter', 'ツイッター', 'custom_twitter_field', 'general', 'social', array( 'label_for' => 'twitter_account' ) );
	add_settings_field( 'facebook', 'フェイスブック', 'custom_facebook_field', 'general', 'social', array( 'label_for' => 'facebook_account' ) );
}
add_action( 'admin_init', 'add_general_custom_sections' );

function social_section_message() {
?>
<p>各種ソーシャルサービスのアカウント設定を行います。</p>
<?php
}

function custom_twitter_field( $args ) {
	$twitter_account = get_option( 'twitter_account' );
?>
	@<input type="text" name="twitter_account" id="twitter_account" size="30" value="<?php echo esc_html( $twitter_account ); ?>" />
<?php
}

function custom_facebook_field( $args ) {
	$facebook_account = get_option( 'facebook_account' );
?>
	<input type="text" name="facebook_account" id="facebook_account" size="30" value="<?php echo esc_html( $facebook_account ); ?>" />
<?php
}

各設定画面における追加場所

追加できる場所は、マルチサイト化されている場合多少異なります。

一般設定

一般設定画面では、最下部にdefaultセクションの項目追加箇所、generalページのセクション追加箇所があります。

投稿設定

投稿設定画面では、Press This上部にdefaultセクション、メールでの投稿、リモート投稿下部に、それぞれ、post_via_email, remote_publishingセクションの項目追加箇所、最下部に writingページのセクション追加箇所があります。

表示設定

表示設定画面では、最下部にdefaultセクションの項目追加箇所、readingページのセクション追加箇所があります。

ディスカッション設定

ディスカッション設定画面では、アバター上部にdefaultセクション、下部にavatarsセクションの項目追加箇所、最下部にreadingページのセクション追加箇所があります。

メディア設定

メディア設定画面では、画像サイズ下部にdefaultセクション、埋め込み下部にembedsセクション、最下部にuploadsセクションの項目追加箇所と mediaページのセクション追加箇所があります。

プライバシー設定

プライバシー設定画面では、最下部にdefaultセクションの項目追加箇所、privacyページのセクション追加箇所があります。

パーマリンク設定

パーマリンク設定画面では、最下部にoptionalセクションの項目追加箇所、permalinkページのセクション追加箇所があります。defaultセクションへの項目追加はできません。

追加したデータの取得方法

サンプルコード内にもありますが、追加した項目はget_option関数で取得することができます。

$twitter_account = get_option( 'twitter_account' );