6.1 Меню верхнего уровня

Для добавления нового меню верхнего уровня в WordPress Administration используйте функцию add_menu_page().

<?php
add_menu_page(
    string $page_title,
    string $menu_title,
    string $capability,
    string $menu_slug,
    callable $function = '',
    string $icon_url = '',
    int $position = null
);

Пример

Допустим, мы хотим добавить новое меню верхнего уровня под названием "WPOrg".

Первым шагом будет создание функции, которая будет выводить HTML. В этой функции мы выполним необходимые проверки безопасности и отобразим зарегистрированные нами опции с помощью Settings API (Настройки API).

<?php
function wporg_options_page_html() {
    ?>
    <div class="wrap">
      <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
      <form action="options.php" method="post">
        <?php
        // output security fields for the registered setting "wporg_options"
        settings_fields( 'wporg_options' );
        // output setting sections and their fields
        // (sections are registered for "wporg", each field is registered to a specific section)
        do_settings_sections( 'wporg' );
        // output save settings button
        submit_button( __( 'Save Settings', 'textdomain' ) );
        ?>
      </form>
    </div>
    <?php
}
?>

Вторым шагом будет регистрация нашего меню WPOrg. Регистрация должна произойти во время перехвата ([erf) действия admin_menu.

<?php
add_action( 'admin_menu', 'wporg_options_page' );
function wporg_options_page() {
    add_menu_page(
        'WPOrg',
        'WPOrg Options',
        'manage_options',
        'wporg',
        'wporg_options_page_html',
        plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
        20
    );
}
?>

Список параметров и то, что каждый из них делает, смотрите в справке add_menu_page().

Использование PHP-файла для HTML

Лучшей практикой для переносимого кода было бы создание функции обратного вызова (Callback), которая требует/включает в себя ваш PHP-файл.

Для полноты и облегчения понимания унаследованного кода мы покажем другой способ: передача пути к PHP-файлу в виде параметра $menu_slug с параметром null $function.

<?php
add_action( 'admin_menu', 'wporg_options_page' );
function wporg_options_page() {
    add_menu_page(
        'WPOrg',
        'WPOrg Options',
        'manage_options',
        plugin_dir_path(__FILE__) . 'admin/view.php',
        null,
        plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
        20
    );
}
?>

Удаление меню верхнего уровня

Чтобы удалить зарегистрированное меню из администрирования WordPress, используйте функцию remove_menu_page().

<?php
remove_menu_page(
    string $menu_slug
);
?>

Пример

Допустим, мы хотим убрать меню "Инструменты" (Tools).

<?php
add_action( 'admin_menu', 'wporg_remove_options_page', 99 );
function wporg_remove_options_page() {
    remove_menu_page( 'tools.php' );
}
?>

Убедитесь, что меню было зарегистрировано с помощью хука admin_menu, прежде чем пытаться удалить, укажите номер с более высоким приоритетом для функции add_action().

Отправка форм

Чтобы обработать отправку форм на страницах параметров, вам понадобятся две вещи:

1. Используйте URL-адрес страницы в качестве атрибута действия формы.
2. Добавьте хук со слагом (slug), возвращаемый add_menu_page.

Атрибут действия формы

Используйте параметр $menu_slug страницы параметров в качестве первого параметра menu_page_url(). Функция автоматически экранирует URL и выводит его по умолчанию, поэтому вы можете напрямую использовать его в теге <form>:

<form action="<?php menu_page_url( 'wporg' ) ?>" method="post">

Обработка формы

$function, указанная вами при добавлении страницы, будет вызываться только тогда, когда пришло время отобразить страницу, что делает ее неуместной, если вам нужно отправить заголовки (например, перенаправления) обратно в браузер.

add_menu_page возвращает $hookname, а WordPress запускает действие "load-$hookname" перед любым выводом HTML. Вы можете использовать это, чтобы назначить функцию, которая может обрабатывать форму.

Учитывая возвращаемый параметр и действие, приведенный выше пример будет выглядеть так:

add_action( 'admin_menu', 'wporg_options_page' );
function wporg_options_page() {
    $hookname = add_menu_page(
        'WPOrg',
        'WPOrg Options',
        'manage_options',
        'wporg',
        'wporg_options_page_html',
        plugin_dir_url(__FILE__) . 'images/icon_wporg.png',
        20
    );
 
    add_action( 'load-' . $hookname, 'wporg_options_page_submit' );
}

Вы можете запрограммировать wporg_options_page_submit в соответствии с вашими потребностями, но имейте в виду, что вы должны вручную выполнить все необходимые проверки, включая:

1. Отправляется ли форма ('POST' === $_SERVER['REQUEST_METHOD']).
2. Проверка CSRF
3. Валидация (Validation)
4. Очистка (Sanitization)