add_utility_page()

add_utility_page() は、WordPress の管理画面に「ユーティリティ」セクションとしてトップレベルのメニューを追加する関数です。

ただし、WordPress 4.5.0 以降で廃止され、代わりに add_menu_page() を使用することが推奨されています。

この関数は wp-admin/includes/deprecated.php に定義されており、実際には add_menu_page() をラップする形で機能しています。

機能の説明

この関数は、管理画面の「ユーティリティ」セクションにトップレベルのメニューを追加します。
$capability を設定することで、特定のユーザー権限（管理者など）を持つユーザーだけがアクセスできるように制限できます。
ただし、WordPress 4.5.0 以降では非推奨のため、新規開発では add_menu_page() の使用を推奨します。

シンプルなコード例

add_utility_page() を使用して管理画面にメニューを追加する簡単な例を示します。

function my_utility_page() {
    echo '<h1>ユーティリティページ</h1>';
    echo '<p>これはユーティリティページの内容です。</p>';
}

add_action('admin_menu', function() {
    add_utility_page(
        'ユーティリティページ', // ページタイトル
        'ユーティリティ',       // メニュータイトル
        'manage_options',        // 権限（管理者のみ）
        'my-utility-page',       // メニューのスラッグ
        'my_utility_page'        // コールバック関数
    );
});

このコードを実装すると、管理画面の「ユーティリティ」セクションに新しいメニューが追加され、そのページを開くと my_utility_page() の内容が表示されます。

使い方の説明

この関数は以下の引数を受け取ります。

実際の使用例

非推奨であるため、推奨される add_menu_page() を用いたコードを紹介します。

function my_custom_page() {
    echo '<h1>カスタム管理ページ</h1>';
    echo '<p>これはカスタム管理ページの内容です。</p>';
}

add_action('admin_menu', function() {
    add_menu_page(
        'カスタム管理ページ', // ページタイトル
        'カスタム管理',       // メニュータイトル
        'manage_options',     // 権限
        'my-custom-page',     // メニューのスラッグ
        'my_custom_page',     // コールバック関数
        'dashicons-admin-generic' // メニューアイコン
    );
});

一緒に使うことが多い関連タグ

add_menu_page()

add_utility_page() の代替として使用される、トップレベルの管理メニューを追加する関数。

add_menu_page(
    '設定ページ',
    'カスタム設定',
    'manage_options',
    'custom-settings',
    'custom_settings_page'
);

add_submenu_page()

add_menu_page() で追加したメニューにサブメニューを追加する際に使用。

add_submenu_page(
    'custom-settings',
    'サブメニュー',
    'サブメニュー',
    'manage_options',
    'custom-submenu',
    'custom_submenu_page'
);

追加情報で取得したい場合

add_utility_page() は add_menu_page() をラップしているため、
add_menu_page() のリファレンスを参照するとより詳細な情報を得られます。

add_menu_page() の返り値

この関数は、追加されたページの hook_suffix を返します。
この hook_suffix を利用すると、特定のメニューが開かれた際に処理を実行できます。

hook_suffix を利用した処理の追加例

add_action('admin_menu', function() {
    $hook = add_menu_page('設定ページ', '設定', 'manage_options', 'custom-settings', 'custom_settings_page');
    add_action("admin_head-{$hook}", function() {
        echo '<style>.wrap { color: red; }</style>';
    });
});

想定されるトラブル

add_utility_page() が機能しない

WordPress 4.5.0 以降では add_utility_page() が非推奨となったため、正常に動作しない可能性があります。

解決方法

add_menu_page() に置き換えることで解決できます。

メニューが表示されない

$capability に指定した権限をユーザーが持っていない可能性があります。

解決方法

manage_options ではなく edit_posts など適切な権限に変更して試してみてください。

add_menu_page('設定ページ', '設定', 'edit_posts', 'custom-settings', 'custom_settings_page');

Q＆A

add_menu_page('設定', '設定', 'manage_options', 'settings', 'settings_page', 'dashicons-admin-tools');

add_action("admin_head-{$hook_suffix}", function() {
    echo '<style>.wrap { color: blue; }</style>';
});

まとめ

add_utility_page() は、かつて WordPress の管理画面にユーティリティメニューを追加するために使用されていましたが、WordPress 4.5.0 以降で非推奨となりました。

現在では add_menu_page() を使用するのが一般的です。

メニューの追加方法やアイコンの設定、サブメニューの追加方法については add_menu_page() の仕様を参考にするのがよいでしょう。