ClassicPress Plugin Development: Add Plugin Options Page to Settings Main Menu

This post is part of the ClassicPress Plugin Development series in which I am going to look at both best practice for developing plugins and how I approach some requirements as well as some of the functions I commonly use.

When developing a plugin, it is usual to create an options page to allow users to configure the plugin. The most common way of making the plugin options page available to users is to add it to the Settings menu in the admin dashboard.

This is done using the add_options_page function available with ClassicPress.

add_options_page(string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = '', int $position = null)
Parameters
$page_title (string) (Required) The text to be displayed in the title tags of the page when the menu is selected.

$menu_title (string) (Required) The text to be used for the menu.

$capability (string) (Required) The capability required for this menu to be displayed to the user.

$menu_slug (string) (Required) The slug name to refer to this menu by (should be unique for this menu).

$function (callable) (Optional) The function to be called to output the content for this page.
Default value: ''

$position (int) (Optional) The position in the menu order this item should appear.
Default value: null
Return
(string|false) The resulting page's hook_suffix, or false if the user does not have the capability required.

The function above is made accessible using the add_action function along with a admin_menu tag.

The below is an example of an options page using my vendor prefix of azrcrv and a plugin identifer of XXXX:

add_action('admin_menu', 'azrcrv_XXXX_add_options_page');

function azrcrv_XXXX_add_options_page() {
    add_options_page( 
        esc_html__('XXXX Options', 'text-domain'),
        esc_html__('XXXX', 'text-domain'),
        'manage_options',
        dirname(plugin_basename(__FILE__ )),
        'azrcrv_XXXX_display_options_page'
    );
}

If the menu being added is for a network, rather than individual site, the $tag would be network_admin_menu instead of admin_menu.