WordPress.org

Make WordPress Core

Opened 5 months ago

Last modified 5 months ago

#52651 new defect (bug)

$option_group argument in settings_fields() function is misdescribed

Reported by: pe01b6 Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version: 2.7
Component: Options, Meta APIs Keywords:
Focuses: docs Cc:

Description

The settings_fields() function in plugin.php takes a single argument described as $option_group. However this argument is then used to populate the 'option_page' hidden element.

The docBlock param description says "This should match the group name used in register_setting()" but if you follow this advice, your option group will not be included in $allowed_settings and you will get an error.

/**
 * Output nonce, action, and option_page fields for a settings page.
 *
 * @since 2.7.0
 *
 * @param string $option_group A settings group name. This should match the group name
 *                             used in register_setting().
 */
function settings_fields( $option_group ) {
        echo "<input type='hidden' name='option_page' value='" . esc_attr( $option_group ) . "' />";
        echo '<input type="hidden" name="action" value="update" />';
        wp_nonce_field( "$option_group-options" );
}

It seems a common fix for this on the internet is to pass the 'option_page' value instead.

https://wordpress.stackexchange.com/questions/376785/wordpress-error-options-page-setting-not-found-in-the-allowed-options-list

if the argument name could be changed to $option_group and the docBlock updated accordingly, that would correct the issue without breaking existing implementations

<?php
/**
 * Output nonce, action, and option_page fields for a settings page.
 *
 * @since 2.7.0
 *
 * @param string $option_page The slug-name of the settings page on which the section is shown.
 */
function settings_fields( $option_page ) {
        echo "<input type='hidden' name='option_page' value='" . esc_attr( $option_page ) . "' />";
        echo '<input type="hidden" name="action" value="update" />';
        wp_nonce_field( "$option_page-options" );
}

Change History (2)

#1 @SergeyBiryukov
5 months ago

  • Component changed from General to Options, Meta APIs
  • Version changed from 5.6.2 to 2.7

Hi there, welcome to WordPress Trac! Thanks for the report.

Just noting that the function was introduced in [9249], changing the Version field accordingly.

#2 @SergeyBiryukov
5 months ago

  • Focuses docs added
Note: See TracTickets for help on using tickets.